#MoonDynamo

#Features

• Core operations: CreateTable, DescribeTable, ListTables, PutItem, GetItem, UpdateItem, DeleteItem, Query, and Scan.
• Batch operations: batch_get_item reads up to 100 keys in one round trip and batch_write_item applies up to 25 puts/deletes; whatever DynamoDB could not process comes back for an explicit re-drive.
• Every DynamoDB attribute type: S, N, B, BOOL, NULL, L, M, SS, NS, and BS map to one typed AttributeValue enum. Numbers stay as decimal strings end to end, so no precision is lost through floating point.
• Conditional writes and filtered queries: you write condition, key-condition, and filter expressions; the client sends typed expression-attribute values with them.
• Selective reads: get_item, batch_get_item, query, and scan can return only the fields named by projection_expression, including reserved names via expression_attribute_names.
• Secondary indexes: point query or scan at any local or global secondary index with index_name, read oldest-first with descending, and force strongly consistent base-table reads with consistent_read.
• Reserved-word-safe expressions: pass #name placeholders through expression_attribute_names, so attributes called status, size, or timestamp are reachable from any expression.
• Conditional updates: update_item runs SET / ADD / REMOVE expressions, can require a condition_expression before writing, and can return affected attributes via ReturnValues.
• Pagination: Query returns LastEvaluatedKey; ListTables returns LastEvaluatedTableName. Use list_all_tables to collect every table name automatically.
• Structured errors: service failures raise DynamoError::Service carrying the HTTP status, the error code, the message, and the x-amzn-RequestId of the failed call.
• Automatic retries: throttling and transient server failures — 429/500/503 statuses and codes like ProvisionedThroughputExceededException — are retried with capped exponential backoff (2 retries, 100 ms doubling up to 2 s) before an error ever reaches your code.
• Local-first configuration: endpoint, region, and credentials (including session tokens) are all explicit, so pointing at DynamoDB Local takes no extra setup.

#Requirements

• MoonBit with moonc 0.10.19 or newer — verified with moon 0.1.20261102 / moonc 0.10.19. MoonDynamo targets the JavaScript backend and runs on Node.js.
• Optional: Java 8+ to run DynamoDB Local, or Node.js 18+ for the bundled mock server.

#Installation

moon add Mr-Shi123/moondynamo

import {
  "Mr-Shi123/moondynamo"
}

#Quick start

moon version --all
moon check --target js --deny-warn
moon build --target js
moon test --target js --deny-warn

docker run --rm -p 8000:8000 amazon/dynamodb-local
# in another terminal
moon run cmd/main --target js

node scripts/mock-dynamodb.mjs
# in another terminal
moon run cmd/main --target js

#Usage

#Configure a client

let config : @moondynamo.Config = {
  endpoint: "http://127.0.0.1:8000",
  region: "us-east-1",
  credentials: {
    access_key_id: "local",
    secret_access_key: "local",
    session_token: None,
  },
}
let db = @moondynamo.Client::new(config)

#Create a table

try db.create_table("Books", "pk") |> ignore catch {
  @moondynamo.DynamoError::Service(_, "ResourceInUseException", _, _) => ()
  error => raise error
}
db.describe_table("Books") |> ignore

#List tables

let first = db.list_tables(limit=2)
for name in first.table_names {
  println(name)
}
if first.last_evaluated_table_name is Some(cursor) {
  let next = db.list_tables(limit=2, exclusive_start_table_name=cursor)
  for name in next.table_names {
    println(name)
  }
}

let all_tables = db.list_all_tables(limit=2)
for name in all_tables {
  println(name)
}

#Write and read items

let item : @moondynamo.Item = Map([
  ("pk", @moondynamo.Text("book#1")),
  ("title", @moondynamo.Text("The MoonBit Book")),
  ("pages", @moondynamo.Number("128")),
  ("tags", @moondynamo.StringSet(["moonbit", "database"])),
])
db.put_item("Books", item)

let saved = db.get_item(
  "Books",
  Map([("pk", @moondynamo.Text("book#1"))]),
  consistent_read=true,
)
guard saved is Some(book) else { fail("GetItem returned no item") }
guard book.get("title") == Some(@moondynamo.Text("The MoonBit Book")) else {
  fail("GetItem returned an unexpected item")
}

let selected = db.get_item(
  "Books",
  Map([("pk", @moondynamo.Text("book#1"))]),
  projection_expression="title, #st",
  expression_attribute_names=Map([("#st", "status")]),
)

#Conditional writes

try db.put_item(
  "Books",
  item,
  condition_expression="attribute_not_exists(pk)",
) catch {
  @moondynamo.DynamoError::Service(
    _,
    "ConditionalCheckFailedException",
    message,
    _,
  ) => println("conditional write rejected: \{message}")
  error => raise error
}

#Update items

let updated = db.update_item(
  "Books",
  Map([("pk", @moondynamo.Text("book#1"))]),
  "SET pages = :pages",
  expression_attribute_values=Map([
    (":pages", @moondynamo.Number("200")),
    (":expected", @moondynamo.Number("128")),
  ]),
  condition_expression="pages = :expected",
  return_values=AllNew,
)
guard updated is Some(book) && book.get("pages") == Some(@moondynamo.Number("200")) else {
  fail("UpdateItem did not apply the new page count")
}

#Reserved words and name placeholders

let result = db.query(
  "Books",
  "pk = :pk",
  Map([
    (":pk", @moondynamo.Text("user#1")),
    (":st", @moondynamo.Text("active")),
    (":max", @moondynamo.Number("500")),
  ]),
  filter_expression="#st = :st AND pages <= :max",
  expression_attribute_names=Map([("#st", "status")]),
  projection_expression="title",
)
for book in result.items {
  // only the title of active books with at most 500 pages
  ignore(book)
}

#Query a secondary index

let recent = db.query(
  "Books",
  "#st = :st",
  Map([(":st", @moondynamo.Text("active"))]),
  index_name="status-index",
  descending=true,
  expression_attribute_names=Map([("#st", "status")]),
)
for book in recent.items {
  ignore(book) // newest active books first
}

#Scan a table

let mut exclusive_start_key : @moondynamo.Item? = None
while true {
  let page = db.scan(
    "Books",
    filter_expression="pages <= :max",
    expression_attribute_values=Map([(":max", @moondynamo.Number("500"))]),
    projection_expression="title, #st",
    expression_attribute_names=Map([("#st", "status")]),
    exclusive_start_key?,
    limit=100,
  )
  for book in page.items {
    ignore(book) // do something with each matching item
  }
  match page.last_evaluated_key {
    Some(key) => exclusive_start_key = Some(key)
    None => break
  }
}

#Batch reads and writes

let batch = db.batch_get_item("Books", [key1, key2, key3])
for item in batch.items {
  ignore(item)
}
let pending = batch.unprocessed_keys // re-drive these, if any

let selected_batch = db.batch_get_item(
  "Books",
  [key1, key2],
  projection_expression="pk, title, #st",
  expression_attribute_names=Map([("#st", "status")]),
)
// Include the primary key in the projection to match results to input keys.
// Re-drive selected_batch.unprocessed_keys with the same projection options.

let leftover = db.batch_write_item("Books", [
  Put(
    Map([
      ("pk", @moondynamo.Text("book#4")),
      ("pages", @moondynamo.Number("80")),
    ]),
  ),
  Delete(key1),
])
guard leftover.is_empty() else {
  fail("re-drive the requests in leftover")
}

#Query with pagination

let mut exclusive_start_key : @moondynamo.Item? = None
let mut pages = 0
while true {
  let page = db.query(
    "Books",
    "pk = :pk",
    Map([(":pk", @moondynamo.Text("book#1"))]),
    exclusive_start_key?,
    limit=1,
  )
  pages = pages + page.items.length()
  match page.last_evaluated_key {
    Some(key) => exclusive_start_key = Some(key)
    None => break
  }
}
println("query matched \{pages} item(s)")

#Error handling

try db.describe_table("Books") |> ignore catch {
  @moondynamo.DynamoError::Service(status, code, message, request_id) =>
    println("HTTP \{status} \{code}: \{message} (request \{request_id})")
  error => raise error
}

#Attribute value types

#Error model

pub(all) suberror DynamoError {
  InvalidConfig(String)
  InvalidResponse(String)
  Service(Int, String, String, String?)
}

• InvalidConfig — bad endpoint, empty region or credentials, malformed timestamp.
• InvalidResponse — a 2xx response the client could not parse.
• Service(status, code, message, request_id) — a non-2xx answer. The code is taken from the __type suffix (or the code field), e.g. ConditionalCheckFailedException; the message falls back from message to Message; the request ID comes from the x-amzn-RequestId header. Even a non-JSON error body surfaces as Service with the code UnknownServiceError, so callers always get a typed error.

#How it is tested

• 48 unit tests (moon test --target js) cover attribute round-trips, request construction and signing, expression payloads with name placeholders, projected GetItem, BatchGetItem, Query, and Scan requests, conditional UpdateItem payloads and response parsing, the ReturnValues mapping, index and scan payloads, batch payloads and limits with unprocessed-key/request parsing, ListTables paging and validation, response and error parsing, and the retry decision predicate.
• A self-verifying HTTP fixture (scripts/mock-dynamodb.mjs) exercises real HTTP round trips and independently recomputes every SigV4 signature, so signing drift cannot pass silently. Its scenario includes two-page list_all_tables, projected GetItem, BatchGetItem, Query, and Scan calls, and both successful and rejected conditional UpdateItem calls. CI waits for the fixture to complete the entire scenario.
• Verified against DynamoDB Local 1.25.1 end to end: CreateTable → DescribeTable → PutItem → GetItem → UpdateItem → Query → Scan → DeleteItem → GetItem, including conditional-write rejection with a real ConditionalCheckFailedException, multi-page Query walks through LastEvaluatedKey, #name placeholders for reserved-word attributes, a Query against a real global secondary index (index_name + descending) plus a filtered, paged Scan, and batch_get_item / batch_write_item runs confirming that missing keys are absent (not unprocessed) while processed writes take effect.

#Platform status

• JavaScript — compile, unit tests, and live HTTP calls all verified.
• Native — moon check passes. Running natively on Windows is currently blocked by a MinGW incompatibility in moonbitlang/async's C sources (that dependency documents MSVC for its Windows event loop); native runtime testing is pending.

#Architecture

• Protocol layer (protocol.mbt, attribute.mbt) — pure functions with no I/O: they normalize the endpoint, build the DynamoDB JSON payload, sign it with kaashyapan/sigv4, and parse responses into typed values or structured errors. Purity makes the whole wire format deterministic to test.
• Client layer (client.mbt) — a small async wrapper that sends requests through moonbitlang/async's HTTP client.

#Current limitations

• Credentials come from the caller — no default credential chain, no automatic refresh.
• The endpoint must be an origin without a path; no IPv6 hostnames yet.
• Value placeholders (:name) and name placeholders (#name) are supported; programmatic expression builders are not (yet).
• The retry policy is fixed — 2 retries, 100 ms doubling up to 2 s, no jitter or per-client tuning.
• No Transact*, Streams, PartiQL, or schema modeling yet. The batch helpers are single-table wrappers over the multi-table AWS wire format.
• create_table only creates on-demand tables with string keys; tables with indexes or other shapes need to be created out of band.

#License