@antelopejs/interface-database 0.1.8 → 0.1.10

package/dist/tests/cross_instance.test.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const chai_1 = require("chai");
+const Database = __importStar(require("../staged-query"));
+const other_instance_1 = require("./helpers/other-instance");
+const buildFolder = node_path_1.default.resolve(__dirname, "..");
+const otherInstance = (0, other_instance_1.CreateOtherInstance)([buildFolder]);
+const Other = otherInstance(node_path_1.default.join(buildFolder, "staged-query", "index.js"));
+function OtherTable() {
+    return new Other.Schema("cross-instance-other", {
+        items: { fields: {}, indexes: {} },
+    })
+        .instance()
+        .table("items");
+}
+describe("Objects built by another interface instance", () => {
+    it("IsStream, IsDatum, IsQuery and IsValueProxy recognise them (data-api picks its query path with them)", PredicatesRecogniseOtherInstance);
+    it("are not instanceof this instance's classes (providers refuse sub-queries from another binding with it)", InstanceofStaysPerInstance);
+    it("share CROSS_INSTANCE with this instance (providers compare it with ===)", CrossInstanceIsShared);
+});
+function PredicatesRecogniseOtherInstance() {
+    const otherTable = OtherTable();
+    const otherDatum = otherTable.get("id");
+    const otherValue = Other.ValueProxy.constant(1);
+    (0, chai_1.expect)(Other.Stream).to.not.equal(Database.Stream);
+    (0, chai_1.expect)(Database.IsStream(otherTable)).to.equal(true);
+    (0, chai_1.expect)(Database.IsQuery(otherTable)).to.equal(true);
+    (0, chai_1.expect)(Database.IsDatum(otherTable)).to.equal(false);
+    (0, chai_1.expect)(Database.IsDatum(otherDatum)).to.equal(true);
+    (0, chai_1.expect)(Database.IsStream(otherDatum)).to.equal(false);
+    (0, chai_1.expect)(Database.IsValueProxy(otherValue)).to.equal(true);
+    (0, chai_1.expect)(Database.IsQuery(otherValue)).to.equal(false);
+    (0, chai_1.expect)(Database.IsStream({})).to.equal(false);
+    (0, chai_1.expect)(Database.IsStream(null)).to.equal(false);
+}
+function InstanceofStaysPerInstance() {
+    (0, chai_1.expect)(OtherTable() instanceof Database.Query).to.equal(false);
+    (0, chai_1.expect)(Other.ValueProxy.constant(1) instanceof Database.ValueProxy).to.equal(false);
+}
+function CrossInstanceIsShared() {
+    (0, chai_1.expect)(Other.CROSS_INSTANCE).to.equal(Database.CROSS_INSTANCE);
+}
+//# sourceMappingURL=cross_instance.test.js.map

package/dist/tests/cross_instance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross_instance.test.js","sourceRoot":"","sources":["../../src/tests/cross_instance.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/helpers/other-instance.d.ts

@@ -0,0 +1,13 @@
+type ModuleRequire = (request: string) => unknown;
+/**
+ * Evaluates built packages a second time, the way the core gives each
+ * provider binding its own copy of an interface: every file under `folders`
+ * is loaded again, with its own classes, symbols and registries, while
+ * anything else (interface-core, third-party dependencies) stays the copy
+ * already loaded.
+ *
+ * @param folders Build output folders to evaluate again
+ * @returns A `require` resolving into the second copy
+ */
+export declare function CreateOtherInstance(folders: string[]): ModuleRequire;
+export {};

package/dist/tests/helpers/other-instance.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateOtherInstance = CreateOtherInstance;
+const node_module_1 = __importDefault(require("node:module"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const internals = node_module_1.default;
+/**
+ * Evaluates built packages a second time, the way the core gives each
+ * provider binding its own copy of an interface: every file under `folders`
+ * is loaded again, with its own classes, symbols and registries, while
+ * anything else (interface-core, third-party dependencies) stays the copy
+ * already loaded.
+ *
+ * @param folders Build output folders to evaluate again
+ * @returns A `require` resolving into the second copy
+ */
+function CreateOtherInstance(folders) {
+    const owned = folders.map((folder) => (0, node_fs_1.realpathSync)(folder) + node_path_1.default.sep);
+    const modules = new Map();
+    const load = (filename, parent) => {
+        const cached = modules.get(filename);
+        if (cached) {
+            return cached.exports;
+        }
+        const loaded = new node_module_1.default(filename, parent);
+        loaded.filename = filename;
+        loaded.paths = internals._nodeModulePaths(node_path_1.default.dirname(filename));
+        loaded.require = ((request) => requireFrom(loaded, request));
+        modules.set(filename, loaded);
+        loaded.load(filename);
+        return loaded.exports;
+    };
+    const requireFrom = (parent, request) => {
+        const filename = internals._resolveFilename(request, parent);
+        const isOwned = owned.some((root) => filename.startsWith(root));
+        return isOwned
+            ? load(filename, parent)
+            : node_module_1.default.prototype.require.call(parent, request);
+    };
+    return (request) => requireFrom(module, request);
+}
+//# sourceMappingURL=other-instance.js.map

package/dist/tests/helpers/other-instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"other-instance.js","sourceRoot":"","sources":["../../../src/tests/helpers/other-instance.ts"],"names":[],"mappings":";;;;;AA2BA,kDA4BC;AAvDD,8DAAiC;AACjC,qCAAuC;AACvC,0DAA6B;AAa7B,MAAM,SAAS,GAAG,qBAAoC,CAAC;AAEvD;;;;;;;;;GASG;AACH,SAAgB,mBAAmB,CAAC,OAAiB;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAA,sBAAY,EAAC,MAAM,CAAC,GAAG,mBAAI,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,MAAM,IAAI,GAAG,CAAC,QAAgB,EAAE,MAAc,EAAW,EAAE;QACzD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,qBAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC5C,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC3B,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC,gBAAgB,CAAC,mBAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,OAAe,EAAE,EAAE,CACpC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAsB,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAoC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,MAAc,EAAE,OAAe,EAAW,EAAE;QAC/D,MAAM,QAAQ,GAAG,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAChE,OAAO,OAAO;YACZ,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC;YACxB,CAAC,CAAC,qBAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC;IAEF,OAAO,CAAC,OAAe,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC"}

package/docs/1.query_types/1.index.md

@@ -41,6 +41,20 @@ for await (const user of schema.instance().table("users")) {
 }
 ```
 
+## Recognize a Query Type
+
+`IsQuery`, `IsDatum`, `IsStream` and `IsValueProxy` tell what kind of staged object a value is:
+
+```typescript
+import { IsStream } from "@antelopejs/interface-database";
+
+function describe(query: unknown) {
+  return IsStream(query) ? "a sequence of documents" : "a single value";
+}
+```
+
+Each provider binding of the interface has its own copy of these classes, so a query built by a module bound to another database is not an `instanceof` this module's `Stream`. The predicates recognize it whichever copy built it. Keep `instanceof` for checking that a query was built for this module's own binding.
+
 ## Available Query Types
 
 - [**Table**](./2.table.md) - Represents a database table with insert, get, getAll, and between operations

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"]
+}