@antelopejs/interface-database 0.1.9 → 0.1.10

package/README.md

@@ -1,29 +1,104 @@
-# Interface Database
+# @antelopejs/interface-database
 
 <div align="center">
-<a href="https://www.npmjs.com/package/@antelopejs/interface-database"><img src="https://img.shields.io/npm/v/@antelopejs/interface-database?style=for-the-badge&labelColor=000000&color=000000" alt="npm"></a>
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge&labelColor=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
-<a href="./docs/index.md"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
+<a href="https://www.npmjs.com/package/@antelopejs/interface-database"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-database?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-database?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://interfaces.antelopejs.com/docs/database"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
 </div>
 
-A database-agnostic query interface that provides consistent operations across different database implementations. Interface Database brings AQL (Antelope Query Language) to your projects, enabling you to write database code that works seamlessly with multiple database backends through a chainable, type-safe API inspired by ReQL.
+AQL (Antelope Query Language), the database-agnostic query builder of AntelopeJS: write a chainable, typed query once and run it on any database module that implements the interface.
 
-## Installation
+## What it offers
+
+- `Schema` declares tables, fields and indexes; each schema can hold several isolated instances.
+- `Table`, `Selection` and `SingleSelection` insert, read, update and delete documents.
+- `Stream` filters, maps, joins, groups and aggregates; `ValueProxy` builds the expressions inside them.
+- `changes()` streams inserts, updates and deletions as they happen.
+- Queries are lazy: nothing runs until you `await` them, call `.run()` or iterate them.
+
+## Implementations
+
+| Module                                                             | Notes                                                        |
+| ------------------------------------------------------------------ | ------------------------------------------------------------ |
+| [`@antelopejs/mongodb`](https://github.com/AntelopeJS/mongodb)     | MongoDB; also implements `@antelopejs/interface-mongodb`     |
+| [`@antelopejs/rethinkdb`](https://github.com/AntelopeJS/rethinkdb) | RethinkDB; also implements `@antelopejs/interface-rethinkdb` |
+
+## Install
+
+Add the interface to the module that runs queries:
 
 ```bash
-npm install @antelopejs/interface-database
+pnpm add @antelopejs/interface-database
+```
+
+Then add an implementation to the project:
+
+```bash
+ajs project modules add @antelopejs/mongodb
+```
+
+## Quick start
+
+```ts
+import { Schema } from "@antelopejs/interface-database";
+
+interface Novel {
+  _id?: string;
+  title: string;
+  pageCount: number;
+}
+
+const schema = new Schema<{ novels: Novel }>("library", {
+  novels: {
+    fields: { title: "string", pageCount: "number" },
+    indexes: { pageCount: {} },
+  },
+});
+
+const novels = schema.instance().table("novels");
+
+export async function addNovel(title: string, pageCount: number) {
+  return await novels.insert({ title, pageCount });
+}
+
+export async function listLongNovels() {
+  return await novels
+    .filter((novel) => novel.key("pageCount").ge(300))
+    .orderBy("pageCount", "desc");
+}
 ```
 
+Callbacks such as the `filter` above receive a `ValueProxy`, not a document: only its methods travel to the database.
+
 ## Documentation
 
-Detailed documentation is available in the `docs` directory:
+- [Overview and import paths](./docs/index.md)
+- [Query types](./docs/1.query_types/1.index.md)
+- [Operations](./docs/2.operations/1.index.md)
+- [Atomic mutations](./docs/2.operations/8.atomic_mutations.md)
+- [Results](./docs/3.results/1.index.md)
+
+## Compatibility
+
+Requires AntelopeJS core `1.x` and the following peer dependency:
 
-- [Overview](./docs/index.md) - Introduction and documentation structure
-- [Query Types](./docs/1.query_types/1.index.md) - Table, Selection, Stream, Datum, ValueProxy, and other query types
-- [Operations](./docs/2.operations/1.index.md) - Schema management, CRUD operations, filtering, and lookups
-- [Results](./docs/3.results/1.index.md) - Result types and change feed handling
+<!-- docs-compat: ./package.json#peerDependencies -->
+
+| Package                      | Range            |
+| ---------------------------- | ---------------- |
+| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
+
+## Contributing
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+```
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+[Apache-2.0](./LICENSE)

package/docs/1.query_types/2.table.md

@@ -6,6 +6,10 @@ The `Table<T>` class represents a database table and provides methods for insert
 
 ```typescript
 class Table<T> extends Selection<T> {
+  atomicMutation(
+    id: string,
+    request: AtomicMutation<T>,
+  ): Query<AtomicMutationOutcome>;
   insert(
     obj: DeepPartial<T> | DeepPartial<T>[],
     options?: InsertOptions,
@@ -74,6 +78,8 @@ const upsertIds = await users.insert(
 
 Retrieve a single document by its primary key. Returns a `SingleSelection<T>`.
 
+Awaiting this selection is declared as `T`, not `T | null`. The declaration does not prove a row exists; providers can return `null` for missing keys, so check before reading fields.
+
 ```typescript
 const user = await users.get("user-123");
 
@@ -108,6 +114,8 @@ const recent = await users.between(
 
 ## Inherited Methods
 
+For conditional single-record writes, see [Atomic Mutations](../2.operations/8.atomic_mutations.md). `atomicMutation()` is a table method, not a selection method; it returns an explicit outcome rather than a modified count.
+
 Since `Table` extends `Selection`, which extends `Stream`, it inherits:
 
 - **Selection methods**: `update()`, `replace()`, `delete()` -- see [Selection](./3.selection.md)

package/docs/1.query_types/4.single_selection.md

@@ -32,6 +32,8 @@ const user = users.get("user-123");
 
 Since `SingleSelection` extends `Datum`, you can execute it directly to retrieve the document value:
 
+The declared result is `T`, even though a provider can return `null` for a missing key. Check for absence before accessing the document; the generic type is not an existence guarantee.
+
 ```typescript
 const user = await users.get("user-123");
 
@@ -98,9 +100,7 @@ if (count === 1) {
 The `changes` method returns change events for the document. Each event contains a `changeType` and the `oldValue`/`newValue` of the document.
 
 ```typescript
-const changes = await users.get("user-123").changes();
-
-for (const change of changes) {
+for await (const change of users.get("user-123").changes()) {
   console.log("Type:", change.changeType); // "added" | "removed" | "modified"
   console.log("Old:", change.oldValue);
   console.log("New:", change.newValue);

package/docs/1.query_types/5.stream.md

@@ -10,7 +10,9 @@ class Stream<T> extends Query<T[]> {
   cast<U>(): Stream<U>;
 
   // Field access
-  key<K extends keyof T>(key: K, def?: unknown): Stream<T[K]>;
+  key<K extends keyof T, U = undefined>(key: K, def?: U): Stream<
+    U extends undefined ? T[K] : Exclude<T[K], undefined | null> | U
+  >;
   default<U>(val: Value<U>): Stream<Exclude<T, undefined | null> | U>;
 
   // Transformation
@@ -53,6 +55,8 @@ class Stream<T> extends Query<T[]> {
 
 Access a specific field from all documents in the stream with `key()`, or provide a default value for null fields with `default()`.
 
+`key(field, fallback)` also accepts a fallback. When it is not `undefined`, the result type excludes `null` and `undefined` from the field type and includes the fallback's type; without it, the declared field type is unchanged.
+
 ```typescript
 const users = schema.instance().table("users");
 

package/docs/1.query_types/6.feed.md

@@ -20,7 +20,7 @@ interface Changes<T> {
 
 ## Create a Change Feed
 
-Call `changes()` on any stream or single selection to subscribe to change events:
+Call `changes()` on a stream or single selection to build a feed query. Consume it with async iteration to receive events as they arrive:
 
 ```typescript
 import { Schema } from "@antelopejs/interface-database";
@@ -29,10 +29,10 @@ const schema = Schema.get("myapp")!;
 const users = schema.instance().table("users");
 
 // Monitor all changes to a table
-const allChanges = await users.changes();
+const allChanges = users.changes();
 
 // Monitor changes to a specific document
-const userChanges = await users.get("user-123").changes();
+const userChanges = users.get("user-123").changes();
 ```
 
 ## Process Change Events
@@ -40,38 +40,45 @@ const userChanges = await users.get("user-123").changes();
 Each change event includes a `changeType` field that indicates the nature of the change:
 
 ```typescript
-const changes = await users.changes();
-
-for (const change of changes) {
-  switch (change.changeType) {
-    case "added":
-      console.log("New document:", change.newValue);
-      break;
-    case "modified":
-      console.log("Updated from:", change.oldValue);
-      console.log("Updated to:", change.newValue);
-      break;
-    case "removed":
-      console.log("Deleted document:", change.oldValue);
-      break;
+for await (const change of users.changes()) {
+  if (change.changeType === "added") {
+    console.log("New document:", change.newValue);
+  } else if (change.changeType === "modified") {
+    console.log("Updated from:", change.oldValue);
+    console.log("Updated to:", change.newValue);
+  } else {
+    console.log("Deleted document:", change.oldValue);
   }
 }
 ```
 
 ## Use with Async Iteration
 
-Since `changes()` returns a `Query`, you can use the cursor for streaming results:
+`changes()` returns `Query<Changes<T>[]>`, but `Query`'s cursor and async iterator yield each array element: one `Changes<T>` event, not a batch. A direct `await` uses `run()` and asks the provider for a completed result; an open-ended feed may never complete, so use iteration for continuous monitoring.
 
-```typescript
-const feed = users.changes();
+```ts docs-check
+import { Schema } from "@antelopejs/interface-database";
+import type { Changes } from "@antelopejs/interface-database/common";
+
+interface User {
+  _id: string;
+  name: string;
+}
+
+export async function watchUsers(onChange: (change: Changes<User>) => boolean) {
+  const schema = Schema.get<{ users: User }>("myapp");
+  if (!schema) throw new Error("Register the myapp schema first");
+  const feed = schema.instance().table("users").changes();
 
-for await (const batch of feed) {
-  for (const change of batch) {
+  for await (const change of feed) {
     console.log(`${change.changeType}:`, change.newValue ?? change.oldValue);
+    if (!onChange(change)) break;
   }
 }
 ```
 
+Breaking out of the loop closes its cursor. When using `cursor()` manually, call `return()` when finished.
+
 ## Use Cases
 
 Change feeds are well suited for:

package/docs/1.query_types/7.query.md

@@ -41,6 +41,8 @@ Both approaches are equivalent. Use whichever reads better in context.
 
 ## Async Iteration
 
+Array-valued queries yield one element at a time, including one `Changes<T>` event per iteration of a change feed. [Atomic mutations](../2.operations/8.atomic_mutations.md) are an exception: they reject cursor execution and must be awaited directly or executed with `run()`.
+
 ### `cursor()`
 
 Return an `AsyncGenerator` that yields results one at a time. This is useful for processing large result sets without loading everything into memory.

package/docs/1.query_types/8.datum.md

@@ -7,7 +7,9 @@ The `Datum<T>` class represents a single value in the query system. It extends `
 ```typescript
 class Datum<T> extends Query<T> {
   cast<U>(): Datum<U>;
-  key<K extends keyof NonNullable<T>>(key: K, def?: unknown): Datum<NonNullable<T>[K]>;
+  key<K extends keyof NonNullable<T>, U = undefined>(key: K, def?: U): Datum<
+    U extends undefined ? NonNullable<T>[K] : NonNullable<NonNullable<T>[K]> | U
+  >;
   default<U>(val: Value<U>): Datum<Exclude<T, undefined | null> | U>;
   do<U>(mapper: (val: ValueProxy<T>) => U): Datum<ExtractType<U>>;
   lookup<U>(other: Selection<U>, localKey: keyof T, otherKey: keyof U): Datum<...>;
@@ -17,7 +19,7 @@ class Datum<T> extends Query<T> {
 
 ## Field Access
 
-The `key` method retrieves a field from a document datum. You can chain `key` calls for nested field access. An optional default value can be provided for the case when the field is undefined.
+The `key` method retrieves a field from a document datum. You can chain `key` calls for nested field access. A non-undefined fallback removes `null` and `undefined` from the declared field result and adds the fallback's type. Omitting the fallback preserves the declared field type.
 
 ```typescript
 import { Schema } from "@antelopejs/interface-database";
@@ -75,11 +77,12 @@ interface User {
   name: string;
 }
 
-const post = await schema
+const blog = Schema.get<{ posts: Post; users: User }>("blog")!;
+const post = await blog
   .instance()
-  .table<Post>("posts")
+  .table("posts")
   .get("post-1")
-  .lookup(schema.instance().table<User>("users"), "authorId", "_id");
+  .lookup(blog.instance().table("users"), "authorId", "_id");
 
 // post.authorId is now the full User object
 console.log(post.authorId.name);

package/docs/1.query_types/9.valueproxy.md

@@ -200,6 +200,8 @@ const highest = scores.max();
 
 Available when the proxy wraps a record/object value.
 
+`key(field, fallback)` preserves the declared field type when the fallback is omitted or `undefined`. Otherwise, the proxy's value type is `Exclude<FieldType, undefined | null> | FallbackType`. The fallback may itself be a `ValueProxy`, so its value type participates in the result.
+
 ```typescript
 const email = user.key("email");
 const emailOrDefault = user.key("email", "none@example.com");

package/docs/2.operations/1.index.md

@@ -19,6 +19,7 @@ Tables live inside schema instances:
 Documents are the fundamental unit of data in AQL:
 
 - [4. CRUD Operations](./4.crud.md) - Insert, read, update, replace, and delete documents
+- [8. Atomic Mutations](./8.atomic_mutations.md) - Conditional single-record updates and deletes, with explicit outcomes
 
 ## Index Operations
 

package/docs/2.operations/2.database_management.md

@@ -107,7 +107,7 @@ if (schema) {
 
 ## Work with Tables
 
-Once you have a `SchemaInstance`, access tables by name. The generic type parameter provides type safety for your documents:
+Put the table-to-document mapping on `Schema`, then access tables by name. The generic parameter of `table()` is a key of that mapping, not a document type:
 
 ```typescript
 interface User {
@@ -124,11 +124,14 @@ interface Post {
   authorId: string;
 }
 
-const db = schema.instance();
-const users = db.table<User>("users");
-const posts = db.table<Post>("posts");
+const typedSchema = Schema.get<{ users: User; posts: Post }>("myapp")!;
+const db = typedSchema.instance();
+const users = db.table("users"); // Table<User>
+const posts = db.table("posts"); // Table<Post>
 ```
 
+Use the same mapping when declaring a schema: `new Schema<{ users: User; posts: Post }>("myapp", definition)`. This type argument describes the schema; it does not validate stored data.
+
 ## Multi-Tenant Pattern
 
 Schemas with multiple instances support multi-tenant architectures. Each tenant gets an isolated instance of the same schema:

package/docs/2.operations/3.table_operations.md

@@ -16,23 +16,46 @@ const users = db.table("users");
 
 ## Type-Safe Tables
 
-Provide a generic type parameter to get type-safe operations:
+Provide the table-to-document mapping to `Schema`, not to `table()`:
+
+```ts docs-check
+import { Schema } from "@antelopejs/interface-database";
 
-```typescript
 interface User {
   _id: string;
   name: string;
   email: string;
   status: string;
+  role: string;
+  createdAt: Date;
+  age: number;
 }
 
-const users = db.table<User>("users");
+const schema = new Schema<{ users: User }>("myapp", {
+  users: {
+    fields: {
+      name: "string",
+      email: "string",
+      status: "string",
+      role: "string",
+      createdAt: "date",
+      age: "number",
+    },
+    indexes: { role: {}, createdAt: {}, name: {} },
+  },
+});
+const users = schema.instance().table("users");
 
 // TypeScript now validates field names and types
-const user = await users.get("user-123"); // user is User | null
-const emails = await users.key("email"); // string[]
+export async function readUser() {
+  const user = await users.get("user-123"); // Declared as User
+  const emails = await users.key("email"); // string[]
+  return { user, emails };
+}
 ```
 
+`get()` declares `SingleSelection<User>`, so awaiting it is typed as `User`, not `User | null`. This declaration does not guarantee that a row exists: a provider may return `null` for a missing key. Check the result before accessing fields. `Schema`'s generic mapping describes documents but does not validate database contents.
+
 ## Basic Operations
 
 ### Retrieve All Documents

package/docs/2.operations/7.lookup.md

@@ -37,12 +37,12 @@ interface User {
   email: string;
 }
 
-const schema = Schema.get("blog")!;
+const schema = Schema.get<{ posts: Post; users: User }>("blog")!;
 const db = schema.instance();
 
 const postsWithAuthors = await db
-  .table<Post>("posts")
-  .lookup(db.table<User>("users"), "authorId", "_id");
+  .table("posts")
+  .lookup(db.table("users"), "authorId", "_id");
 
 // Result type: { _id: string, title: string, authorId: User }
 for (const post of postsWithAuthors) {
@@ -68,9 +68,12 @@ interface Product {
   price: number;
 }
 
-const ordersWithProducts = await db
-  .table<Order>("orders")
-  .lookup(db.table<Product>("products"), "productIds", "_id");
+const shop = Schema.get<{ orders: Order; products: Product }>(
+  "shop",
+)!.instance();
+const ordersWithProducts = await shop
+  .table("orders")
+  .lookup(shop.table("products"), "productIds", "_id");
 
 // Result type: { ..., productIds: Product[] }
 for (const order of ordersWithProducts) {
@@ -85,6 +88,9 @@ for (const order of ordersWithProducts) {
 Lookup works seamlessly with filters, sorting, and other stream operations:
 
 ```typescript
+// The shop schema also declares customers and orders.createdAt.
+const db = Schema.get("shop")!.instance();
+
 // Filter before lookup
 const recentWithCustomers = await db
   .table("orders")
@@ -92,10 +98,11 @@ const recentWithCustomers = await db
   .lookup(db.table("customers"), "customerId", "_id");
 
 // Lookup on a single document
-const post = await db
-  .table<Post>("posts")
+const blog = Schema.get<{ posts: Post; users: User }>("blog")!.instance();
+const post = await blog
+  .table("posts")
   .get("post-1")
-  .lookup(db.table<User>("users"), "authorId", "_id");
+  .lookup(blog.table("users"), "authorId", "_id");
 ```
 
 ## Lookup vs Join

package/docs/3.results/4.table_changes.md

@@ -89,7 +89,7 @@ const users = schema.instance().table("users");
 const posts = schema.instance().table("posts");
 ```
 
-For type-safe access, provide a generic type parameter:
+For type-safe access, provide the table mapping when declaring or retrieving the schema. `table()` infers the document type from the table name:
 
 ```typescript
 interface User {
@@ -99,7 +99,8 @@ interface User {
   age: number;
 }
 
-const users = schema.instance().table<User>("users");
+const typedSchema = Schema.get<{ users: User }>("myapp")!;
+const users = typedSchema.instance().table("users"); // Table<User>
 ```
 
 For more details on table operations, see [Table Operations](../2.operations/3.table_operations.md).

package/docs/3.results/6.value_changes.md

@@ -36,9 +36,7 @@ import { Schema } from "@antelopejs/interface-database";
 const schema = Schema.get("myapp")!;
 const users = schema.instance().table("users");
 
-const changes = await users.changes();
-
-for (const change of changes) {
+for await (const change of users.changes()) {
   switch (change.changeType) {
     case "added":
       console.log("New document:", change.newValue);
@@ -56,9 +54,7 @@ for (const change of changes) {
 ## Monitor a Single Document
 
 ```typescript
-const userChanges = await users.get("user-123").changes();
-
-for (const change of userChanges) {
+for await (const change of users.get("user-123").changes()) {
   if (change.changeType === "modified") {
     console.log("User updated:", change.newValue);
   } else if (change.changeType === "removed") {

package/docs/index.md

@@ -4,6 +4,14 @@
 
 The Database interface provides AQL (Antelope Query Language), a database-agnostic query API. Each module implements this generic interface with the database engine of its choice. AQL offers a chainable, type-safe query builder that works identically across all supported backends, so your application code remains portable regardless of the underlying database.
 
+## Import Paths
+
+Import `Schema`, `Query`, `Table`, `Datum`, `Stream`, and `ValueProxy` from `@antelopejs/interface-database` in an AntelopeJS module. This entry point registers schemas with the bound provider and installs query execution (`run()`, `then()`, `cursor()`, and async iteration).
+
+Supporting types have dedicated paths: import `Changes`, `DeepPartial`, `ExtractType`, and `Value` from `@antelopejs/interface-database/common`, and `FieldType`, `TableDefinition`, and `IndexDefinition` from `@antelopejs/interface-database/schema`. Atomic mutation types are available from the package root and `/atomic`.
+
+`@antelopejs/interface-database/staged-query` is the build-only entry point for tools that construct and inspect query stages without the AntelopeJS runtime. Its schema does not register with a provider, and its queries expose `build()` but no execution methods when loaded on their own. Do not `await` a build-only query expecting database results. The runtime entry point augments the same staged classes; keep build-only consumers separate from runtime imports when that isolation matters.
+
 ## Documentation Structure
 
 - [**1. Query Types**](./1.query_types/1.index.md) - Detailed reference for each query type:

package/docs/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true,
+    "composite": false,
+    "incremental": false,
+    "paths": {
+      "@antelopejs/interface-database": ["../src/index.ts"],
+      "@antelopejs/interface-database/*": ["../src/*"]
+    }
+  },
+  "include": ["../src/**/*.ts", "./**/*.ts"]
+}

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@antelopejs/interface-database",
-  "version": "0.1.9",
-  "description": "AntelopeJS interface for database-agnostic query operations",
+  "version": "0.1.10",
+  "description": "AQL, the AntelopeJS database-agnostic query builder: schemas, CRUD, joins, aggregations and change feeds",
   "keywords": [
     "antelopejs",
+    "aql",
     "database",
-    "interface"
+    "interface",
+    "query-builder"
   ],
+  "homepage": "https://interfaces.antelopejs.com/docs/database",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/interface-database/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -110,9 +116,9 @@
     "knip": "knip"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.13.4",
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/tooling-configs": "^0.0.6",
+    "@antelopejs/core": "^1.16.0",
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/tooling-configs": "^0.0.9",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -132,7 +138,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0"
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
   "antelopeJs": {