@antelopejs/interface-database 0.1.3 → 0.1.5

package/docs/2.operations/4.crud.md

@@ -0,0 +1,214 @@
+# CRUD Operations
+
+CRUD operations (Create, Read, Update, Delete) form the foundation of document management in AQL. All examples assume a schema is already defined and an instance is available.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+```
+
+## Create Documents
+
+### Insert a Single Document
+
+```typescript
+const ids = await users.insert({
+  name: "Alice Johnson",
+  email: "alice@example.com",
+  status: "active",
+  createdAt: new Date(),
+});
+
+console.log("Inserted ID:", ids[0]);
+```
+
+### Insert Multiple Documents
+
+```typescript
+const ids = await users.insert([
+  { name: "Bob", email: "bob@example.com", status: "active" },
+  { name: "Carol", email: "carol@example.com", status: "active" },
+]);
+
+console.log("Inserted IDs:", ids);
+```
+
+### Upsert (Insert or Update)
+
+Use the `conflict` option to handle documents that already exist:
+
+```typescript
+// Update existing fields, keep unmentioned fields
+await users.insert(
+  { _id: "user-123", name: "Updated Name", lastSeen: new Date() },
+  { conflict: "update" },
+);
+
+// Replace the entire document
+await users.insert(
+  { _id: "user-123", name: "Replaced", email: "new@example.com" },
+  { conflict: "replace" },
+);
+```
+
+## Read Documents
+
+### Get by Primary Key
+
+```typescript
+const user = await users.get("user-123");
+
+if (user) {
+  console.log("Found:", user.name);
+} else {
+  console.log("User not found");
+}
+```
+
+### Get by Secondary Index
+
+```typescript
+const admins = await users.getAll("admin", "role");
+console.log(`Found ${admins.length} admins`);
+```
+
+### Get by Range
+
+```typescript
+const recent = await users.between(
+  "createdAt",
+  new Date("2024-01-01"),
+  new Date(),
+);
+```
+
+### Filter Documents
+
+```typescript
+// Filter with a predicate function
+const active = await users.filter((user) =>
+  user.key("status").eq("active").and(user.key("age").ge(18)),
+);
+```
+
+### Select Specific Fields
+
+```typescript
+// Keep only listed fields
+const profiles = await users.pluck("_id", "name", "avatar");
+
+// Remove sensitive fields
+const safe = await users.without("password", "ssn");
+```
+
+### Order and Paginate
+
+```typescript
+const page1 = await users.orderBy("createdAt", "desc").slice(0, 10);
+const page2 = await users.orderBy("createdAt", "desc").slice(10, 10);
+```
+
+### Stream Results
+
+For large result sets, use async iteration to process documents one at a time:
+
+```typescript
+for await (const user of users) {
+  console.log("Processing:", user.name);
+}
+```
+
+## Update Documents
+
+### Update a Single Document
+
+The `update` method modifies specified fields while preserving all other fields.
+
+```typescript
+const count = await users.get("user-123").update({
+  status: "active",
+  lastLogin: new Date(),
+});
+
+if (count === 1) {
+  console.log("User updated");
+}
+```
+
+### Update with Computed Values
+
+Pass a function to compute new values based on current ones:
+
+```typescript
+await users.get("user-123").update((user) => ({
+  loginCount: user.key("loginCount").add(1),
+  lastLogin: new Date(),
+}));
+```
+
+### Update Multiple Documents
+
+```typescript
+const count = await users
+  .getAll("inactive", "status")
+  .update({ status: "active" });
+
+console.log(`Activated ${count} users`);
+```
+
+## Replace Documents
+
+The `replace` method substitutes the entire document. Fields not included in the replacement are removed.
+
+```typescript
+const count = await users.get("user-123").replace({
+  _id: "user-123",
+  name: "Alice Updated",
+  email: "alice.new@example.com",
+  status: "active",
+  updatedAt: new Date(),
+});
+```
+
+## Delete Documents
+
+### Delete a Single Document
+
+```typescript
+const count = await users.get("user-123").delete();
+
+if (count === 1) {
+  console.log("User deleted");
+}
+```
+
+### Delete Multiple Documents
+
+```typescript
+const count = await users
+  .filter((user) => user.key("status").eq("inactive"))
+  .delete();
+
+console.log(`Deleted ${count} inactive users`);
+```
+
+## Batch Operations
+
+For large-scale inserts, batch documents to manage memory and throughput:
+
+```typescript
+const documents = Array.from({ length: 10000 }, (_, i) => ({
+  index: i,
+  value: `Item ${i}`,
+  createdAt: new Date(),
+}));
+
+const batchSize = 1000;
+for (let i = 0; i < documents.length; i += batchSize) {
+  const batch = documents.slice(i, i + batchSize);
+  await schema.instance().table("items").insert(batch);
+  console.log(`Inserted batch ${Math.floor(i / batchSize) + 1}`);
+}
+```

package/docs/2.operations/5.indexes.md

@@ -0,0 +1,110 @@
+# Index Management
+
+Indexes improve query performance by enabling the database to locate documents quickly based on indexed fields. In AQL, indexes are defined as part of the schema definition.
+
+## Define Indexes in a Schema
+
+Indexes are declared in the `indexes` property of each table definition:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = new Schema("myapp", {
+  users: {
+    fields: { name: "string", email: "string", role: "string", age: "number" },
+    indexes: {
+      email: {}, // Simple index on the "email" field
+      role: {}, // Simple index on the "role" field
+      name_age: { fields: ["name", "age"] }, // Compound index
+    },
+  },
+});
+```
+
+### `IndexDefinition`
+
+```typescript
+interface IndexDefinition {
+  fields?: string[]; // Fields for compound indexes (omit for single-field)
+  multi?: boolean; // Whether this is a multi-valued index
+}
+```
+
+When `fields` is omitted, the index name is used as the field name. For compound indexes, provide the `fields` array explicitly.
+
+## Use Indexes for Queries
+
+### `getAll()` with an Index
+
+Retrieve documents by index value:
+
+```typescript
+const db = schema.instance();
+const users = db.table("users");
+
+// Query by the "role" index
+const admins = await users.getAll("admin", "role");
+
+// Query multiple values
+const targets = await users.getAll(["admin", "moderator"], "role");
+```
+
+### `between()` with an Index
+
+Retrieve documents where the index value falls within a range:
+
+```typescript
+const results = await users.between("age", 18, 65);
+```
+
+### `orderBy()` with an Index
+
+Sort results using an indexed field for better performance:
+
+```typescript
+const sorted = await users.orderBy("email", "asc");
+const newest = await users.orderBy("createdAt", "desc");
+```
+
+## Compound Indexes
+
+Compound indexes span multiple fields. Define them with the `fields` array:
+
+```typescript
+const schema = new Schema("blog", {
+  posts: {
+    fields: {
+      category: "string",
+      publishedAt: "date",
+      title: "string",
+    },
+    indexes: {
+      category_date: { fields: ["category", "publishedAt"] },
+    },
+  },
+});
+```
+
+Compound indexes support prefix-based lookups. You can query by the first field alone or by both fields together.
+
+## Multi Indexes
+
+Set `multi: true` for fields that contain arrays. The database creates an index entry for each element in the array, enabling lookups by any single element:
+
+```typescript
+const schema = new Schema("content", {
+  articles: {
+    fields: { tags: ["string"] },
+    indexes: {
+      tags: { multi: true },
+    },
+  },
+});
+```
+
+## Index Design Guidelines
+
+- **Index fields used in `getAll()` and `between()` calls** for best performance.
+- **Compound indexes** are useful when you frequently filter or sort by multiple fields together.
+- **Avoid over-indexing.** Each index adds storage overhead and slows down writes.
+- **Filter early** in your query chain to reduce the number of documents processed.

package/docs/2.operations/6.filtering.md

@@ -0,0 +1,172 @@
+# Filtering and Querying
+
+This guide covers techniques for selecting, comparing, and transforming documents using AQL's filter and ValueProxy capabilities.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+```
+
+## Basic Filtering
+
+Use the `filter` method with a predicate function. The callback receives a `ValueProxy<T>` representing each document.
+
+```typescript
+const active = await users.filter((user) => user.key("status").eq("active"));
+```
+
+## Comparison Operators
+
+### Equality and Inequality
+
+```typescript
+const admins = await users.filter((u) => u.key("role").eq("admin"));
+const nonAdmins = await users.filter((u) => u.key("role").ne("admin"));
+```
+
+### Numeric Comparisons
+
+```typescript
+const adults = await users.filter((u) => u.key("age").ge(18));
+const seniors = await users.filter((u) => u.key("age").gt(65));
+const young = await users.filter((u) => u.key("age").lt(18));
+const discounted = await users.filter((u) => u.key("age").le(25));
+```
+
+## Logical Operators
+
+Combine conditions with `and()`, `or()`, and `not()`:
+
+```typescript
+// AND
+const verified = await users.filter((u) =>
+  u.key("status").eq("active").and(u.key("emailVerified").eq(true)),
+);
+
+// OR
+const important = await users.filter((u) =>
+  u.key("role").eq("admin").or(u.key("plan").eq("premium")),
+);
+
+// NOT
+const standard = await users.filter((u) => u.key("plan").eq("premium").not());
+
+// Complex combinations
+const target = await users.filter((u) =>
+  u
+    .key("status")
+    .eq("active")
+    .and(u.key("plan").eq("premium").or(u.key("totalPurchases").gt(500))),
+);
+```
+
+## String Operations
+
+```typescript
+// Case-insensitive match
+const bobs = await users.filter((u) => u.key("name").downcase().eq("bob"));
+
+// Regex matching
+const gmailUsers = await users.filter((u) =>
+  u.key("email").match("@gmail\\.com$"),
+);
+
+// String concatenation in filter
+const fullNameMatch = await users.filter((u) =>
+  u.key("firstName").concat(u.key("lastName")).eq("JohnSmith"),
+);
+```
+
+## Date Filtering
+
+### Date Comparisons
+
+```typescript
+const newUsers = await users.filter((u) =>
+  u.key("createdAt").gt(new Date("2024-01-01")),
+);
+
+const q1Users = await users.filter((u) =>
+  u
+    .key("createdAt")
+    .ge(new Date("2024-01-01"))
+    .and(u.key("createdAt").lt(new Date("2024-04-01"))),
+);
+```
+
+### Date Components
+
+```typescript
+const thisYear = await users.filter((u) => u.key("createdAt").year().eq(2024));
+
+const morningLogins = await users.filter((u) =>
+  u.key("lastLogin").hours().lt(12),
+);
+```
+
+## Array Operations
+
+```typescript
+// Check array contents
+const jsPosts = await schema
+  .instance()
+  .table("posts")
+  .filter((post) => post.key("tags").includes("javascript"));
+
+// Check array length
+const wellTagged = await schema
+  .instance()
+  .table("posts")
+  .filter((post) => post.key("tags").count().gt(3));
+
+// Check if empty
+const untagged = await schema
+  .instance()
+  .table("posts")
+  .filter((post) => post.key("tags").isempty());
+```
+
+## Default Values in Filters
+
+Use `default()` to handle potentially null fields:
+
+```typescript
+const activeUsers = await users.filter((u) =>
+  u.key("active").default(false).eq(true),
+);
+
+const frequentVisitors = await users.filter((u) =>
+  u.key("visits").default(0).gt(10),
+);
+```
+
+## Ordering and Pagination
+
+```typescript
+// Sort ascending
+const byName = await users.orderBy("name", "asc");
+
+// Sort descending
+const newest = await users.orderBy("createdAt", "desc");
+
+// Paginate
+const page1 = await users.orderBy("createdAt").slice(0, 10);
+const page2 = await users.orderBy("createdAt").slice(10, 10);
+```
+
+## Performance Tips
+
+1. **Use `getAll()` and `between()` with indexes** instead of `filter()` when possible. Index-based lookups are significantly faster than full scans.
+2. **Filter early** in the query chain to reduce the dataset before applying transformations or aggregations.
+3. **Limit result sets** with `slice()` to avoid transferring unnecessary data.
+4. **Avoid complex computations** inside filter predicates when simpler alternatives exist.
+
+```typescript
+// Slower: full table scan with filter
+const slow = await users.filter((u) => u.key("email").eq("user@example.com"));
+
+// Faster: index-based lookup
+const fast = await users.getAll("user@example.com", "email");
+```

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

@@ -0,0 +1,135 @@
+# Lookup
+
+The `lookup` method performs a foreign key join, replacing a field in your documents with the referenced data from another table. It is available on both `Stream<T>` and `Datum<T>`.
+
+## Parameters
+
+| Parameter  | Type           | Description                                               |
+| ---------- | -------------- | --------------------------------------------------------- |
+| `other`    | `Selection<U>` | The table containing the referenced documents             |
+| `localKey` | `keyof T`      | The field in the current document holding the foreign key |
+| `otherKey` | `keyof U`      | The field in the other table to match against             |
+
+## Behavior
+
+The `lookup` method replaces the local key field with the populated data:
+
+- If the local key contains a **single value**, the field becomes a **single document** from the other table.
+- If the local key contains an **array of values**, the field becomes an **array of documents** from the other table.
+- TypeScript automatically tracks the type transformation.
+
+## One-to-One Relationship
+
+Replace a single foreign key with the referenced document:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+interface Post {
+  _id: string;
+  title: string;
+  authorId: string;
+}
+
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+}
+
+const schema = Schema.get("blog")!;
+const db = schema.instance();
+
+const postsWithAuthors = await db
+  .table<Post>("posts")
+  .lookup(db.table<User>("users"), "authorId", "_id");
+
+// Result type: { _id: string, title: string, authorId: User }
+for (const post of postsWithAuthors) {
+  console.log(`${post.title} by ${post.authorId.name}`);
+}
+```
+
+## One-to-Many Relationship
+
+Replace an array of foreign keys with an array of documents:
+
+```typescript
+interface Order {
+  _id: string;
+  customerId: string;
+  productIds: string[];
+  total: number;
+}
+
+interface Product {
+  _id: string;
+  name: string;
+  price: number;
+}
+
+const ordersWithProducts = await db
+  .table<Order>("orders")
+  .lookup(db.table<Product>("products"), "productIds", "_id");
+
+// Result type: { ..., productIds: Product[] }
+for (const order of ordersWithProducts) {
+  for (const product of order.productIds) {
+    console.log(`  - ${product.name}: $${product.price}`);
+  }
+}
+```
+
+## Combine with Other Operations
+
+Lookup works seamlessly with filters, sorting, and other stream operations:
+
+```typescript
+// Filter before lookup
+const recentWithCustomers = await db
+  .table("orders")
+  .filter((order) => order.key("createdAt").gt(new Date("2024-01-01")))
+  .lookup(db.table("customers"), "customerId", "_id");
+
+// Lookup on a single document
+const post = await db
+  .table<Post>("posts")
+  .get("post-1")
+  .lookup(db.table<User>("users"), "authorId", "_id");
+```
+
+## Lookup vs Join
+
+### Use `lookup` when:
+
+- You have a straightforward foreign key relationship.
+- You want the referenced data to replace the foreign key field.
+- You are working with one-to-one or one-to-many relationships.
+
+### Use `join` or `joinInner` when:
+
+- You need custom join predicates beyond simple equality.
+- You want to keep both original and joined data as separate fields.
+- You need to transform the result into a custom structure.
+
+### Comparison
+
+```typescript
+// Lookup: replaces the field
+const withLookup = await db
+  .table("orders")
+  .lookup(db.table("customers"), "customerId", "_id");
+// order.customerId is now the full customer object
+
+// Join: custom output structure
+const withJoin = await db.table("orders").joinInner(
+  db.table("customers"),
+  (order, customer) => order.key("customerId").eq(customer.key("_id")),
+  (order, customer) => ({
+    orderId: order.key("_id"),
+    orderTotal: order.key("total"),
+    customerName: customer.key("name"),
+  }),
+);
+// Result is a custom object with selected fields from both tables
+```

package/docs/2.operations/8.atomic_mutations.md

@@ -0,0 +1,71 @@
+# Atomic single-record mutations
+
+`Table.atomicMutation(id, request)` checks one immutable, instance-scoped record identity and one condition inside the database mutation. It returns `Query<AtomicMutationOutcome>`. It does not provide multi-record transactions, a lock service, receipts, or external-effect coordination.
+
+Generic `filter(...).update(...)` and `filter(...).delete()` do **not** promise this guarantee. Use a direct `schema.instance(instanceId).table(tableId)` with one literal string identity. The default instance is supported; `CROSS_INSTANCE`, filtered selections, expression keys, cursors, and upserts are not.
+
+## Compare a revision
+
+Public types are exported from `@antelopejs/interface-database` and `@antelopejs/interface-database/atomic`. An update checks the current revision and installs the patch and next revision together. A delete checks the revision inside the deletion.
+
+```ts
+const outcome = await table.atomicMutation(recordId, {
+  type: "update",
+  revisionField: "revision",
+  expectedRevision: observed.revision,
+  nextRevision: freshRevision,
+  patch: { title: "Updated title" },
+});
+
+const deletion = await table.atomicMutation(recordId, {
+  type: "delete",
+  revisionField: "revision",
+  expectedRevision: observed.revision,
+});
+```
+
+Revision tokens are nonempty strings. Each update must install a changed token that the caller guarantees has never been used for that identity. All writers of protected state must advance the revision; otherwise a successful comparison does not prove that the observed state is current. Initialize new records with fresh revisions and use a new identity for each incarnation, including recreation after deletion.
+
+`expectedRevision: { kind: "missing" }` matches an **absent revision field on an existing record**. It does not match a stored `null`, an empty string, or a missing record. An update can use this expectation to bootstrap legacy data atomically; a delete can use it when the domain permits deleting an unversioned record. A backend that cannot distinguish absence from null must reject this expectation rather than weaken it. In PostgreSQL, declared SQL columns collapse this distinction; an overflow JSON field can preserve it. Review mapper serialization before choosing revision storage.
+
+## Patch semantics
+
+The patch replaces each supplied top-level field. Nested objects and arrays replace their entire previous values; they do not merge recursively. Unspecified fields remain unchanged, and `null` stores null rather than removing the field. There is no unset operation.
+
+Patches contain only constant strings, booleans, finite numbers, null, valid Dates, dense arrays, and plain objects. Undefined, functions, query proxies, cycles, and operator/path field names are rejected. The patch cannot contain `id`, `_id`, the revision field, or adapter-owned scope fields. Adapters must preserve their normal Date storage representation without interpreting objects that resemble query stages as executable expressions.
+
+## Delete by one observed scalar
+
+`deleteIfEqual` provides a narrower condition for domains where one field equality is sufficient, such as deletion of an expired record whose observed timestamp remains unchanged.
+
+```ts
+const outcome = await table.atomicMutation(recordId, {
+  type: "deleteIfEqual",
+  field: "lastSeenAt",
+  expectedValue: observed.lastSeenAt,
+});
+```
+
+`expectedValue` accepts a string, finite number, boolean, or valid Date. Equality is exact and type-sensitive, with Dates compared by their stored instant; scalar equality must not match an array containing that scalar. Missing fields never match. Null, objects, arrays, identity fields, and scope fields are not supported.
+
+This variant does not check or advance a revision and does not prevent ABA: a value can change and later return to its observed value. The domain must prove that equality alone authorizes deletion. It is not a substitute for revision checks on state transitions.
+
+## Handle all outcomes
+
+| Outcome       | Meaning                                                                                                              |
+| ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `applied`     | The adapter received definitive acknowledgement that the one mutation applied.                                       |
+| `not-applied` | The adapter received definitive acknowledgement that the target was missing or its scope or condition did not match. |
+| `unknown`     | The adapter cannot determine whether the mutation applied, including acknowledgement loss.                           |
+
+Definitive validation and unsupported-operation errors throw. Neither an exception nor `unknown` means mismatch. The interface rejects invalid adapter results, including `undefined`, zero, and generic modified counts, with `AtomicMutationUnsupportedError`; adapters must reject unsupported stages explicitly. There is no fallback to generic filtered writes and no separate capability probe. Use an adapter whose implementation has been verified before relying on this API.
+
+The interface and adapter must not automatically retry an uncertain mutation. Do not repeat external effects or infer failure from a later mismatch. Domain-specific recovery can reconcile durable evidence and receipts, but a fresh read alone cannot prove whether an earlier operation or external effect occurred. Any deliberate replay requires a domain proof and does not turn `not-applied` into evidence about the original attempt.
+
+## Adapter contract
+
+The canonical terminal stage is `{ stage: "atomicMutation", options: undefined, args: [id, request] }`, immediately after `schema`, `instance`, and `table`. `AtomicMutation<T>` is the union of `AtomicUpdate<T>`, `AtomicDelete<T>`, and `AtomicDeleteIfEqual<T>`.
+
+Adapters can reuse `ValidateAtomicMutation(id, request, protectedFields)` and `ValidateAtomicMutationTable(prefixStages)`. They must additionally validate the terminal envelope and schema-specific restrictions. Scope, immutable identity, and the revision or equality condition must participate in the target-local native mutation, not only an earlier selection or identity subquery. Backend tests must prove contention, scope isolation, missing/null distinction, top-level replacement, and acknowledgement-loss behavior.
+
+This API remains unpublished during adapter and consumer verification. Package metadata alone does not establish capability; do not infer support from the unchanged development package version.