#Apache OpenDAL for MoonBit

#Release and source status

• whole, ranged, random-access, and output-bounded sequential reads;
• whole and chunked writes with explicit finish or abort;
• metadata, existence, directories, listing, delete, copy, and rename;
• typed S3 construction with default-chain, static/session, unsigned, and assume-role authentication;
• owned presigned read/write/stat requests;
• immutable timeout, retry, and concurrency-limit layers, all opt-in;
• all-or-error delete_many and a managed same-Operator, one-object Copier;
• one root-package async facade for whole writes and reads, bounded read streams, and explicit streaming writers on native and browser JS targets;
• an embedded browser OpenDAL Wasm runtime with additional async operations and listers;
• typed OpenDalError values and capability inspection.

#Install a release

moon add Eric-Song-Nop/opendal@0.2.0

moon add Eric-Song-Nop/opendal@0.1.0

supported_targets = "+native+js"

import {
  "Eric-Song-Nop/opendal",
}

make moon-deps
make test-profile NATIVE_SERVICE_PROFILE=standard

#Browser quickstart

moon run --target js --release src/browser_demo

supported_targets = "js"

import {
  "Eric-Song-Nop/opendal",
  "moonbitlang/async",
}

///|
async fn browser_round_trip() {
  let storage = @opendal.AsyncOperator::new("memory")
  defer storage.close()
  storage.write("hello.txt", b"hello from Chrome") |> ignore
  assert_eq(storage.read("hello.txt"), b"hello from Chrome")
}

#First operation

///|
#cfg(target="native")
test "README: memory round trip" {
  let operator = @opendal.Operator::new("memory")
  operator.write("hello.txt", b"hello from MoonBit") |> ignore
  assert_eq(operator.read("hello.txt"), b"hello from MoonBit")
}

///|
#cfg(target="native")
test "README: typed storage error" {
  let operator = @opendal.Operator::new("memory")
  try operator.read("missing.txt") catch {
    error => {
      assert_true(error.kind() is NotFound)
      assert_true(error.info().operation is Read)
      assert_eq(error.info().path, Some("missing.txt"))
    }
  } noraise {
    _ => fail("expected a missing-object error")
  }
}

///|
async test "README: async memory round trip" {
  let async_operator = @opendal.AsyncOperator::new("memory")
  defer async_operator.close()
  async_operator.write("whole.txt", b"whole object") |> ignore
  assert_eq(async_operator.read("whole.txt"), b"whole object")
  let writer = async_operator.open_writer("async.txt")
  writer.write(b"hello ")
  writer.write(b"asynchronously")
  writer.finish() |> ignore
  assert_eq(async_operator.read("async.txt"), b"hello asynchronously")
}

#Guides

• Documentation index — user guides, target-specific API reference, architecture contracts, release procedure, and examples.
• Getting started — install v0.2.0 or validate a source checkout, then choose synchronous or async I/O.
• Connecting — understand profiles and construct memory, filesystem, and typed S3 operators.
• Using OpenDAL in a browser — select the JS target, use the embedded runtime, configure OPFS or S3, and deploy it safely.
• Common tasks — recipes for streams, abort, presign, layers, batch deletion, Copier, async I/O, and the blocking core.
• Roadmap — completed Phase 5 slices and the remaining release gates.

#Deliberate limits

• Native source builds enable memory, fs, and s3; browser JS builds enable memory, opfs, and s3. GCS, Azure Blob, WebDAV, and other OpenDAL services are not compiled in.
• delete_many is all-or-error and can have partial remote effects; it does not fabricate ordered per-path results or promise atomicity.
• Copier copies one object between two paths on the same Operator. It is not recursive and cannot bridge two operators or services.
• ReadStream.chunk_size hard-bounds each returned value and binding copy, but OpenDAL or a backend may provide and retain one larger raw buffer internally.
• Suffix ranges require capability.can_read_suffix(); the binding does not emulate suffix reads with a preliminary stat.
• The portable async slice covers whole writes and reads, bounded read streams, and chunked writers. Whole-object buffers are limited to 64 MiB and stream and writer chunks to 256 KiB on both targets. Native async stat/list/delete/copy/presign and public task handles remain later work; the JavaScript target additionally exposes its capability-checked Promise operations and stateful listers.
• Retry, timeout, and concurrency limits are never implicit. Logging, tracing, metrics exporters, and custom callback layers are not exposed.
• Standard artifacts are published for v0.2.0. Intel macOS, Windows, and musl Linux are not advertised; a Rust-only build is not treated as MoonBit host support.

#Upstream references

• Node.js binding overview
• Getting started
• Connecting
• Common tasks

#Apache OpenDAL for MoonBit

#Release and source status

• whole, ranged, random-access, and output-bounded sequential reads;
• whole and chunked writes with explicit finish or abort;
• metadata, existence, directories, listing, delete, copy, and rename;
• typed S3 construction with default-chain, static/session, unsigned, and assume-role authentication;
• owned presigned read/write/stat requests;
• immutable timeout, retry, and concurrency-limit layers, all opt-in;
• all-or-error delete_many and a managed same-Operator, one-object Copier;
• one root-package async facade for whole writes and reads, bounded read streams, and explicit streaming writers on native and browser JS targets;
• an embedded browser OpenDAL Wasm runtime with additional async operations and listers;
• typed OpenDalError values and capability inspection.

#Install a release

moon add Eric-Song-Nop/opendal@0.2.0

moon add Eric-Song-Nop/opendal@0.1.0

supported_targets = "+native+js"

import {
  "Eric-Song-Nop/opendal",
}

make moon-deps
make test-profile NATIVE_SERVICE_PROFILE=standard

#Browser quickstart

moon run --target js --release src/browser_demo

supported_targets = "js"

import {
  "Eric-Song-Nop/opendal",
  "moonbitlang/async",
}

///|
async fn browser_round_trip() {
  let storage = @opendal.AsyncOperator::new("memory")
  defer storage.close()
  storage.write("hello.txt", b"hello from Chrome") |> ignore
  assert_eq(storage.read("hello.txt"), b"hello from Chrome")
}

#First operation

///|
#cfg(target="native")
test "README: memory round trip" {
  let operator = @opendal.Operator::new("memory")
  operator.write("hello.txt", b"hello from MoonBit") |> ignore
  assert_eq(operator.read("hello.txt"), b"hello from MoonBit")
}

///|
#cfg(target="native")
test "README: typed storage error" {
  let operator = @opendal.Operator::new("memory")
  try operator.read("missing.txt") catch {
    error => {
      assert_true(error.kind() is NotFound)
      assert_true(error.info().operation is Read)
      assert_eq(error.info().path, Some("missing.txt"))
    }
  } noraise {
    _ => fail("expected a missing-object error")
  }
}

///|
async test "README: async memory round trip" {
  let async_operator = @opendal.AsyncOperator::new("memory")
  defer async_operator.close()
  async_operator.write("whole.txt", b"whole object") |> ignore
  assert_eq(async_operator.read("whole.txt"), b"whole object")
  let writer = async_operator.open_writer("async.txt")
  writer.write(b"hello ")
  writer.write(b"asynchronously")
  writer.finish() |> ignore
  assert_eq(async_operator.read("async.txt"), b"hello asynchronously")
}

#Guides

• Documentation index — user guides, target-specific API reference, architecture contracts, release procedure, and examples.
• Getting started — install v0.2.0 or validate a source checkout, then choose synchronous or async I/O.
• Connecting — understand profiles and construct memory, filesystem, and typed S3 operators.
• Using OpenDAL in a browser — select the JS target, use the embedded runtime, configure OPFS or S3, and deploy it safely.
• Common tasks — recipes for streams, abort, presign, layers, batch deletion, Copier, async I/O, and the blocking core.
• Roadmap — completed Phase 5 slices and the remaining release gates.

#Deliberate limits

• Native source builds enable memory, fs, and s3; browser JS builds enable memory, opfs, and s3. GCS, Azure Blob, WebDAV, and other OpenDAL services are not compiled in.
• delete_many is all-or-error and can have partial remote effects; it does not fabricate ordered per-path results or promise atomicity.
• Copier copies one object between two paths on the same Operator. It is not recursive and cannot bridge two operators or services.
• ReadStream.chunk_size hard-bounds each returned value and binding copy, but OpenDAL or a backend may provide and retain one larger raw buffer internally.
• Suffix ranges require capability.can_read_suffix(); the binding does not emulate suffix reads with a preliminary stat.
• The portable async slice covers whole writes and reads, bounded read streams, and chunked writers. Whole-object buffers are limited to 64 MiB and stream and writer chunks to 256 KiB on both targets. Native async stat/list/delete/copy/presign and public task handles remain later work; the JavaScript target additionally exposes its capability-checked Promise operations and stateful listers.
• Retry, timeout, and concurrency limits are never implicit. Logging, tracing, metrics exporters, and custom callback layers are not exposed.
• Standard artifacts are published for v0.2.0. Intel macOS, Windows, and musl Linux are not advertised; a Rust-only build is not treated as MoonBit host support.

#Upstream references

• Node.js binding overview
• Getting started
• Connecting
• Common tasks