sorodb 0.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to SoroDB
+
+## Set up a checkout
+
+Use Node.js 20 or later, Bun for the committed `bun.lock`, and npm for the package preview command.
+
+```sh
+bun install --frozen-lockfile
+node examples/basic.js
+bun run test
+bun run typecheck
+bun run build:types
+```
+
+The example uses an in-memory store. File-backed tests create and remove temporary directories.
+
+## Make a change
+
+The package is ESM JavaScript with JSDoc types checked by TypeScript. `npm run build:types` generates publishable declarations in `types/`; npm also runs it automatically before packing or publishing. Public imports come from `src/index.js`; add public APIs there deliberately. Use `src/types.js` for shared JSDoc definitions. See the [architecture map](docs/explanation/architecture.md) for module responsibilities.
+
+Add a behavioral test in `test/sorodb.test.js` for changes to validation, persistence, indexes, query results, transactions, or cursor behavior. Update the [API reference](docs/reference/api.md) and relevant guide when public behavior changes. Keep runnable examples aligned with the documented API.
+
+Before opening a pull request, run:
+
+```sh
+bun run test
+bun run typecheck
+bun run lint
+bun run fmt --check
+bun run pack:dry
+```
+
+The package preview should include `src`, `types`, `LICENSE`, `README.md`, `CONTRIBUTING.md`, `docs`, and `examples`. Summarize the behavior changed, the checks you ran, and any compatibility or migration impact in the pull request.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alloys Mila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# SoroDB
+
+SoroDB is an embedded document database for Node.js, built on SlateDB. Define a schema, store JavaScript documents, and query them with indexes, transactions, and snapshot-backed pagination.
+
+SoroDB is an ECMAScript module and requires Node.js 20 or later.
+TypeScript declarations are generated from the JSDoc annotations and included in the npm package.
+
+## Quick start
+
+From this checkout, run `bun install --frozen-lockfile` first. Once SoroDB is published to npm, an application can install it with `npm install sorodb`. This example uses an in-memory store; its data disappears when the process ends.
+
+```js
+import SoroDB from "sorodb";
+
+const db = SoroDB({ store: "memory:///", path: "quick-start" });
+db.schema({ version: 1 }, [
+	{
+		table: "users",
+		columns: {
+			id: { type: "number", primary: true },
+			name: { type: "string" },
+		},
+	},
+]);
+
+try {
+	const users = await db.collection("users");
+	await users.create({ id: 1, name: "Ada" });
+	const page = await users.filter({ where: (w) => w.eq("name", "Ada") }).page();
+	console.log(page.items); // [{ id: 1, name: "Ada" }]
+} finally {
+	await db.close();
+}
+```
+
+Register the schema before the first collection or transaction call. Always close the database to release the underlying store and any active query snapshots.
+
+## Store data in Amazon S3
+
+Create a bucket and give the application read and write access to it. Set `AWS_DEFAULT_REGION` to the bucket's region and provide credentials through the environment, such as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (plus `AWS_SESSION_TOKEN` for temporary credentials). The [S3 object-store configuration](https://docs.rs/object_store/latest/object_store/aws/struct.AmazonS3Builder.html#method.from_env) lists supported environment variables.
+
+Replace `your-bucket-name` with your bucket. The `store` URL selects the bucket; `path` places this database under the `sorodb-demo` prefix in that bucket.
+
+```js
+import SoroDB from "sorodb";
+
+const db = SoroDB({ store: "s3://your-bucket-name", path: "sorodb-demo" });
+db.schema({ version: 1 }, [
+	{
+		table: "users",
+		columns: {
+			id: { type: "number", primary: true },
+			name: { type: "string" },
+		},
+	},
+]);
+
+try {
+	const users = await db.collection("users");
+	if (!(await users.get(1))) await users.create({ id: 1, name: "Ada" });
+	console.log(await users.get(1)); // { id: 1, name: "Ada" }
+} finally {
+	await db.close();
+}
+```
+
+Run the program again with the same bucket, path, and schema to read the stored document. See the [SlateDB object-store guide](https://slatedb.io/docs/get-started/quickstart/) for supported store URLs.
+
+## Store data in Cloudflare R2
+
+This Node.js example uses R2's S3-compatible API. Create an R2 bucket and an API token with **Object Read & Write** access to that bucket. Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to the token's R2 credentials, and set `AWS_DEFAULT_REGION=auto`. See [Cloudflare's R2 S3 guide](https://developers.cloudflare.com/r2/get-started/s3/) for the bucket, token, and account ID setup.
+
+Replace `your-account-id` and `your-bucket-name` below. The `store` URL selects the R2 endpoint and bucket; `path` places the database under the `sorodb-demo` prefix in the bucket.
+
+```js
+import SoroDB from "sorodb";
+
+const db = SoroDB({
+	store: "https://your-account-id.r2.cloudflarestorage.com/your-bucket-name",
+	path: "sorodb-demo",
+});
+db.schema({ version: 1 }, [
+	{
+		table: "users",
+		columns: {
+			id: { type: "number", primary: true },
+			name: { type: "string" },
+		},
+	},
+]);
+
+try {
+	const users = await db.collection("users");
+	if (!(await users.get(1))) await users.create({ id: 1, name: "Ada" });
+	console.log(await users.get(1)); // { id: 1, name: "Ada" }
+} finally {
+	await db.close();
+}
+```
+
+Run the program again with the same endpoint, bucket, path, and schema to read the stored document. For a bucket in a specific R2 jurisdiction, use its [jurisdiction-specific endpoint](https://developers.cloudflare.com/r2/api/tokens/).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md): build a file-backed database and reopen it.
+- [API reference](docs/reference/api.md): database, collection, query, and error APIs.
+- [Schema and query reference](docs/reference/schema-and-query.md): types, indexes, filters, and ordering.
+- Guides: [schema upgrades](docs/guides/schema-upgrades.md), [indexes and sorting](docs/guides/indexes-and-sorting.md), [transactions](docs/guides/transactions.md), and [pagination](docs/guides/pagination.md).
+- [Architecture](docs/explanation/architecture.md): how documents, indexes, and snapshots fit together.
+- [Contributing](CONTRIBUTING.md): setup and checks for repository changes.
+
+## Run this repository
+
+```sh
+bun install --frozen-lockfile
+node examples/basic.js
+bun run test
+bun run typecheck
+bun run build:types
+```
+
+The [basic example](examples/basic.js) also demonstrates a descending index and async iteration.
+
+## License
+
+SoroDB is licensed under the [MIT License](LICENSE).

package/docs/explanation/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+This page maps the implementation for contributors. The [API reference](../reference/api.md) describes the supported public behavior.
+
+## Module map
+
+| Module                                                                                         | Responsibility                                                         |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [`src/index.js`](../../src/index.js)                                                           | Public factory and error exports.                                      |
+| [`src/storage.js`](../../src/storage.js)                                                       | SlateDB lifecycle, transactions, schema upgrades, and cursor sessions. |
+| [`src/schema.js`](../../src/schema.js)                                                         | ArkType compilation, document validation, and safe schema comparisons. |
+| [`src/collection.js`](../../src/collection.js)                                                 | CRUD operations and index maintenance around writes.                   |
+| [`src/query.js`](../../src/query.js)                                                           | Filter expressions, query planning, projection, iteration, and pages.  |
+| [`src/index-methods.js`](../../src/index-methods.js), [`src/indexes.js`](../../src/indexes.js) | B-tree key encoding, uniqueness checks, and index entry changes.       |
+| [`src/encoding.js`](../../src/encoding.js)                                                     | CBOR values, document keys, key ranges, and stable value encoding.     |
+| [`src/errors.js`](../../src/errors.js), [`src/types.js`](../../src/types.js)                   | Error classes and JSDoc type definitions.                              |
+
+## Storage and writes
+
+`SoroDB(config)` constructs a `Database` without opening SlateDB. `schema()` compiles and stores the requested definition in memory. The first collection or transaction operation opens the native store and compares the persisted schema with that definition. The database uses distinct key prefixes for schema metadata, documents, and index entries.
+
+Document values are CBOR-encoded. An index entry's key contains the indexed values, and its value points to the document key. CRUD writes update both in one serializable snapshot transaction. Unique indexes check for an existing pointer before writing. A failed write rolls back the transaction, so its document and index entries are not partially committed.
+
+## Schema upgrades
+
+`schemaDiff` compares the stored and requested definitions. For a higher version, it permits additions and rejects changes or removals to existing definitions. `_migrate` validates old documents with the new table definition, applies defaults, rebuilds newly added indexes, and writes the new schema metadata after backfill succeeds. The index rebuild path is designed to allow retrying an interrupted or failed addition. The repository's `test/sorodb.test.js` exercises successful backfill and a failed unique-index addition.
+
+## Reads and cursors
+
+`Query` compiles filter and order options when `filter()` is called. Its planner uses a direct document lookup for suitable `id` equality, an index scan for matching sort order or eligible equality, and otherwise a document scan. Every candidate is checked against the full filter expression before projection.
+
+Async iteration reads from a snapshot, or from the active transaction when used there. `page()` retains a snapshot in a database-local cursor session so later pages see the same data even if writes occur. The cursor token carries a session ID, last key, and query fingerprint. Sessions expire after inactivity and are released on completion, explicit `Query.close()`, or `Database.close()`.
+
+When changing public behavior, update the matching [reference page](../reference/api.md), task guide, and behavioral test together.

package/docs/getting-started.md

@@ -0,0 +1,68 @@
+# Getting started
+
+This tutorial creates a file-backed SoroDB database, writes documents, queries them, and reopens the data. You need Node.js 20 or later. Run `bun install --frozen-lockfile` in this checkout and save `app.mjs` at the repository root. Once SoroDB is published to npm, you can instead install it in another ESM project with `npm install sorodb`.
+
+## 1. Create a store and schema
+
+Save the following as `app.mjs`:
+
+```js
+import { mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import SoroDB from "sorodb";
+
+const directory = resolve("./sorodb-data");
+await mkdir(directory, { recursive: true });
+const config = { store: pathToFileURL(directory).href, path: "app" };
+
+function openDatabase() {
+	return SoroDB(config).schema({ version: 1 }, [
+		{
+			table: "users",
+			columns: {
+				id: { type: "number", primary: true },
+				name: { type: "string" },
+				joinedAt: { type: "date", default: () => new Date() },
+			},
+			indexes: [{ name: "joined_at", columns: [{ field: "joinedAt", direction: "desc" }] }],
+		},
+	]);
+}
+
+const db = openDatabase();
+try {
+	const users = await db.collection("users");
+	await users.create({ id: 1, name: "Ada" });
+	await users.create({ id: 2, name: "Grace" });
+
+	for await (const user of users.filter({ orderBy: (order) => order.desc("joinedAt") })) {
+		console.log(user.name, user.joinedAt);
+	}
+} finally {
+	await db.close();
+}
+```
+
+Run `node app.mjs`. The `store` URL identifies the filesystem directory; `path` names the SlateDB database within it. The first operation that needs storage opens the database. `close()` releases it.
+
+## 2. Reopen and read
+
+Replace the write block inside `try` with this block, then run `node app.mjs` again:
+
+```js
+const users = await db.collection("users");
+console.log(await users.get(1));
+console.log((await users.filter({ where: (w) => w.eq("name", "Grace") }).page()).items);
+```
+
+The first result is Ada's document, including a `Date` in `joinedAt`. The second result contains Grace's document. Keep the same schema version and definition when reopening existing data.
+
+## Next steps
+
+- [Schema and query reference](reference/schema-and-query.md) lists the supported definitions and operators.
+- [Indexes and sorting](guides/indexes-and-sorting.md) explains the index required by `orderBy`.
+- [Schema upgrades](guides/schema-upgrades.md) shows how to evolve a persistent schema.
+- [API reference](reference/api.md) covers CRUD, transactions, and query results.
+
+For a disposable database, use `{ store: "memory:///", path: "example" }` instead of a file URL. See [`examples/basic.js`](../examples/basic.js) for a complete in-memory example.

package/docs/guides/indexes-and-sorting.md

@@ -0,0 +1,70 @@
+# Add indexes for queries and sorting
+
+Declare indexes in the table schema. They are maintained when documents are created, replaced, or deleted. The current index method is `btree`.
+
+## Sort by an indexed field
+
+```js
+import SoroDB, { ConflictError } from "sorodb";
+
+const db = SoroDB({ store: "memory:///", path: "index-guide" });
+db.schema({ version: 1 }, [
+	{
+		table: "users",
+		columns: {
+			id: { type: "number", primary: true },
+			name: { type: "string" },
+			email: { type: "string" },
+			joinedAt: { type: "date" },
+		},
+		indexes: [
+			{ name: "recent_users", columns: [{ field: "joinedAt", direction: "desc" }] },
+			{ name: "email_unique", columns: ["email"], unique: true },
+		],
+	},
+]);
+
+try {
+	const users = await db.collection("users");
+	await users.create({
+		id: 1,
+		name: "Ada",
+		email: "ada@example.com",
+		joinedAt: new Date("2026-01-01"),
+	});
+	await users.create({
+		id: 2,
+		name: "Grace",
+		email: "grace@example.com",
+		joinedAt: new Date("2026-02-01"),
+	});
+	const newest = await users.filter({ orderBy: (order) => order.desc("joinedAt") }).page();
+	console.log(newest.items.map((user) => user.name)); // ["Grace", "Ada"]
+
+	try {
+		await users.create({
+			id: 3,
+			name: "Another Ada",
+			email: "ada@example.com",
+			joinedAt: new Date(),
+		});
+	} catch (error) {
+		if (!(error instanceof ConflictError)) throw error;
+		console.log(error.code); // CONFLICT
+	}
+} finally {
+	await db.close();
+}
+```
+
+The requested order must match the leading fields and directions of one declared index. For example, an index on `(team asc, joinedAt desc)` supports `order.asc("team")` and `order.asc("team").desc("joinedAt")`. It does not support sorting only by `joinedAt`. Ascending `id` is the one order that needs no declared index. An unsupported order raises `QueryError` when `filter()` builds the query.
+
+## Enforce uniqueness
+
+The `email_unique` index in the example raises `ConflictError` for a duplicate value. Creating or replacing a document with another document's indexed value has the same result. A document missing an indexed field is omitted from that unique index; `null` is indexed and therefore subject to the constraint.
+
+## Equality lookups
+
+An equality filter on `id` uses the document key. Other equality filters may use an index if its first field is the filtered path, the field is ascending, and the value is indexable. All returned candidates are still checked against the entire filter expression. Other predicates may require a scan, so choose indexes for the filters and orderings that matter to your workload.
+
+For index syntax and supported values, see the [schema and query reference](../reference/schema-and-query.md#index-definitions).

package/docs/guides/pagination.md

@@ -0,0 +1,47 @@
+# Read stable pages
+
+Call `page()` on a filtered collection. It returns `items` and a `nextCursor`, which is `null` after the final page. The default page size is 100; set a positive `limit` for another size.
+
+```js
+import SoroDB from "sorodb";
+
+const db = SoroDB({ store: "memory:///", path: "pagination-guide" });
+db.schema({ version: 1 }, [
+	{
+		table: "users",
+		columns: {
+			id: { type: "number", primary: true },
+			team: { type: "string" },
+		},
+	},
+]);
+
+try {
+	const users = await db.collection("users");
+	for (let id = 1; id <= 3; id++) await users.create({ id, team: "platform" });
+
+	const options = {
+		where: (w) => w.eq("team", "platform"),
+		orderBy: (order) => order.asc("id"),
+		limit: 2,
+	};
+	let cursor;
+	do {
+		const page = await users.filter({ ...options, cursor }).page();
+		for (const user of page.items) console.log(user);
+		cursor = page.nextCursor ?? undefined;
+	} while (cursor);
+
+	const abandoned = users.filter({ limit: 1 });
+	const first = await abandoned.page();
+	if (first.nextCursor) abandoned.close();
+} finally {
+	await db.close();
+}
+```
+
+Pages in one cursor chain read from the same snapshot, so intervening writes do not change the remaining pages. To continue, use the same table, filter, order, and projection. The page size can change. A cursor belongs to the same open database object and expires after inactivity; `cursorTtlMs` sets that interval and defaults to five minutes. A mismatched, invalid, expired, or closed cursor raises `CursorError`.
+
+If you abandon a page chain, keep a reference to its query and call `query.close()` to release its snapshot promptly, as the example does with `abandoned`.
+
+`page()` cannot run inside a transaction. Async iteration is useful when you want to consume results in one pass, including within a transaction. A cursor is an opaque token; store or transmit it unchanged, and do not expect it to work after the database closes.

package/docs/guides/schema-upgrades.md

@@ -0,0 +1,67 @@
+# Upgrade a persistent schema
+
+SoroDB stores the schema version and definition with the database. Register the same version and definition to reopen it unchanged. Increase the version when changing the definition; changing a stored definition without increasing the version raises `SchemaError`.
+
+An upgrade can add tables, columns, or indexes. Removing or changing an existing table, column, or index is rejected as unsafe. SoroDB validates existing documents when it backfills newly added columns and builds newly added indexes.
+
+## Add a column with a default and an index
+
+This complete example creates version 1 in a temporary directory, then reopens it with an added `createdAt` column and index:
+
+```js
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import SoroDB from "sorodb";
+
+const directory = await mkdtemp(join(tmpdir(), "sorodb-upgrade-"));
+const config = { store: pathToFileURL(directory).href, path: "data" };
+try {
+	const first = SoroDB(config).schema({ version: 1 }, [
+		{
+			table: "items",
+			columns: {
+				id: { type: "number", primary: true },
+				label: { type: "string" },
+			},
+		},
+	]);
+	try {
+		await (await first.collection("items")).create({ id: 1, label: "one" });
+	} finally {
+		await first.close();
+	}
+
+	const second = SoroDB(config).schema({ version: 2 }, [
+		{
+			table: "items",
+			columns: {
+				id: { type: "number", primary: true },
+				label: { type: "string" },
+				createdAt: { type: "date", default: () => new Date("2026-01-01") },
+			},
+			indexes: [{ name: "created_at", columns: ["createdAt"] }],
+		},
+	]);
+	try {
+		const items = await second.collection("items"); // opens and upgrades
+		console.log(await items.get(1));
+	} finally {
+		await second.close();
+	}
+} finally {
+	await rm(directory, { recursive: true, force: true });
+}
+```
+
+Supply a default for a new required field if existing documents need a value. An optional field can be added without a default. If backfill validation fails or a new unique index finds duplicates, opening fails; correct the stored data under the previous schema, close it, and retry the upgrade.
+
+## Before an upgrade
+
+1. Keep the full existing table and index definitions in the new schema.
+2. Increase `version` and add only the new definitions.
+3. Check that defaults produce valid values for old documents and that unique index values have no duplicates.
+4. Back up the database directory before upgrading production data, then open with the new schema and verify representative reads and queries.
+
+The repository's `test/sorodb.test.js` covers a successful upgrade and a failed unique-index backfill followed by a retry.

package/docs/guides/transactions.md

@@ -0,0 +1,38 @@
+# Write across collections in a transaction
+
+Use `db.transaction()` when related operations must commit together. The callback receives a transaction object; obtain collections through `tx.collection()` so their reads and writes participate in the transaction.
+
+```js
+import SoroDB from "sorodb";
+
+const db = SoroDB({ store: "memory:///", path: "transaction-guide" });
+db.schema({ version: 1 }, [
+	{ table: "users", columns: { id: { type: "number", primary: true }, name: { type: "string" } } },
+	{ table: "notes", columns: { id: { type: "string", primary: true }, text: { type: "string" } } },
+]);
+
+try {
+	await db.transaction(async (tx) => {
+		const users = await tx.collection("users");
+		const notes = await tx.collection("notes");
+
+		await users.create({ id: 1, name: "Ada" });
+		await notes.create({ id: "welcome", text: "Hello, Ada" });
+	});
+
+	await db.transaction(async (tx) => {
+		const users = await tx.collection("users");
+		for await (const user of users.filter({ where: (w) => w.eq("name", "Ada") })) {
+			console.log(user);
+		}
+	});
+} finally {
+	await db.close();
+}
+```
+
+The transaction commits when the callback resolves. If an operation or the callback throws, the transaction rolls back. Await each operation before the callback returns.
+
+Collection `get`, `create`, `replace`, and `delete` work inside a transaction. Queries can use async iteration, as shown above.
+
+`query.page()` and cursor-based iteration are unavailable on transaction-bound collections. For paginated reads, run `page()` outside the transaction; see [pagination](pagination.md).

package/docs/reference/api.md

@@ -0,0 +1,90 @@
+# API reference
+
+This page describes the API available from `sorodb`. Import the default or named `SoroDB` factory. The package also exports the error classes listed below.
+
+```js
+import SoroDB, { ConflictError, CursorError } from "sorodb";
+```
+
+All database and collection operations that access storage are asynchronous. Call `db.close()` when finished.
+
+## Database
+
+### `SoroDB(config)`
+
+Creates a database object. `config` requires a `store` URL string and a nonempty `path` string. Tested store forms are `memory:///` and a filesystem URL such as one produced by `pathToFileURL(directory).href`. For a file URL, SoroDB joins the URL's directory with `path`. Optional `cursorTtlMs` is a positive integer; its default is five minutes.
+
+### `db.schema({ version }, definitions)`
+
+Registers the schema and returns `db` for chaining. `version` is an integer of at least 1. `definitions` is a nonempty array of table definitions. Register it before opening the database. The database opens when a collection or transaction first needs storage. See [schema and query reference](schema-and-query.md) and [schema upgrades](../guides/schema-upgrades.md).
+
+### `await db.collection(name)`
+
+Returns a collection registered in the schema. Unknown collection names raise `SchemaError`.
+
+### `await db.transaction(async (tx) => { ... })`
+
+Runs the callback in a transaction. Obtain transaction-bound collections with `await tx.collection(name)`. The transaction commits after the callback resolves and rolls back if it throws. Use `await` for operations inside the callback. See [transactions](../guides/transactions.md).
+
+### `await db.close()`
+
+Closes the database and releases active cursor snapshots. Calling it again is safe. A closed database cannot be reopened; construct a new SoroDB object to reopen the same store.
+
+## Collection
+
+Get a collection with `await db.collection(name)` or, inside a transaction, `await tx.collection(name)`.
+
+| Method                                   | Result                                         | Behavior                                                                            |
+| ---------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `await collection.create(document)`      | Validated document, including applied defaults | Requires a unique `id`; duplicate IDs or unique index values raise `ConflictError`. |
+| `await collection.get(id)`               | Document or `null`                             | Reads by string or number ID.                                                       |
+| `await collection.replace(id, document)` | Validated replacement                          | Requires an existing document and the same `id`; replaces the whole document.       |
+| `await collection.delete(id)`            | `true` or `false`                              | Returns `false` when no document had that ID.                                       |
+| `collection.filter(options?)`            | Query object                                   | Builds a query without reading storage yet.                                         |
+
+Writes validate against the table schema. Extra fields are rejected. Values must be CBOR-compatible plain data: null, booleans, finite numbers, strings, BigInts, Dates, byte arrays, arrays, and plain objects. Cycles, sparse arrays, invalid Dates, and unsupported object types raise `ValidationError`. See [schema and query reference](schema-and-query.md).
+
+## Query
+
+`collection.filter(options)` accepts the following optional fields:
+
+| Option                                                 | Meaning                                                                                                      |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `where: (w) => expression`                             | Filter expression built with the operators in the [query reference](schema-and-query.md#filters).            |
+| `orderBy: (order) => order.asc(path)` or `.desc(path)` | Sort by one or more fields. Chaining calls adds fields. Requires a matching index except for ascending `id`. |
+| `select: [path, ...]`                                  | Project fields; `id` is always present. Paths may be dotted.                                                 |
+| `limit: positiveInteger`                               | Maximum items from an iterator, or page size for `page()`.                                                   |
+| `cursor: string`                                       | Continue a previous page or iteration from a matching query snapshot.                                        |
+
+### `await query.page()`
+
+Returns `{ items, nextCursor }`, where `nextCursor` is a string if another page exists and `null` otherwise. The default page size is 100. Reuse the same filter, order, and projection with the returned cursor. The cursor is tied to an in-memory snapshot on the same open database object, so it cannot survive `db.close()` or expiration. `page()` is unavailable inside a transaction. See [pagination](../guides/pagination.md).
+
+### `for await (const document of query)`
+
+Iterates matching documents. A `limit` applies if provided; otherwise iteration continues through the matching results. Async iteration works with transaction-bound collections. Complete or break out of the loop to release its snapshot.
+
+### `query.close()`
+
+Releases a snapshot retained by a `page()` query when abandoning its next cursor. The cursor then cannot be resumed.
+
+## Errors
+
+All exported errors extend `SoroError` and have a `code` string. Some include `details`.
+
+| Export            | Code               | Typical cause                                                                        |
+| ----------------- | ------------------ | ------------------------------------------------------------------------------------ |
+| `ValidationError` | `VALIDATION_ERROR` | Document violates its schema or contains unsupported values.                         |
+| `SchemaError`     | `SCHEMA_ERROR`     | Invalid schema, incompatible version, unknown collection, or invalid database state. |
+| `ConflictError`   | `CONFLICT`         | Duplicate ID, unique index collision, or missing replacement target.                 |
+| `QueryError`      | `QUERY_ERROR`      | Invalid filter or sort, or unsupported query operation.                              |
+| `CursorError`     | `CURSOR_ERROR`     | Invalid, expired, or mismatched cursor.                                              |
+
+```js
+try {
+	await users.create({ id: 1, name: "Ada" });
+} catch (error) {
+	if (error instanceof ConflictError) console.error(error.code, error.message);
+	else throw error;
+}
+```