@antelopejs/interface-database 0.1.3 → 0.1.4

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

@@ -0,0 +1,53 @@
+# Query Types
+
+AQL provides several query classes that form a hierarchy of capabilities. Each class encapsulates a different aspect of database interactions, from full table access down to individual value manipulation.
+
+## Query Type Hierarchy
+
+All query types inherit from `StagedObject`, which records operations as a pipeline of stages. The hierarchy is:
+
+```
+Query<T>
+├── Datum<T>
+│   └── SingleSelection<T>
+└── Stream<T>
+    └── Selection<T>
+        └── Table<T>
+
+ValueProxy<T> (used within query callbacks)
+```
+
+## Common Features
+
+All query types that extend `Query<T>` share these capabilities:
+
+- **`run()`** - Execute the query and return a `Promise<T>` with the result.
+- **`then()`** - `PromiseLike` support, so queries can be awaited directly.
+- **`cursor()`** - Return an `AsyncGenerator` for streaming results one at a time.
+- **`[Symbol.asyncIterator]()`** - Enable `for await...of` loops over query results.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+// Execute a query explicitly
+const result = await schema.instance().table("users").run();
+
+// Await the query directly (uses PromiseLike)
+const users = await schema.instance().table("users");
+
+// Iterate with async generator
+for await (const user of schema.instance().table("users")) {
+  console.log(user.name);
+}
+```
+
+## Available Query Types
+
+- [**Table**](./2.table.md) - Represents a database table with insert, get, getAll, and between operations
+- [**Selection**](./3.selection.md) - A set of documents supporting update, replace, and delete
+- [**SingleSelection**](./4.single_selection.md) - A single document with update, replace, delete, and change feed support
+- [**Stream**](./5.stream.md) - A sequence of results with map, filter, join, group, aggregate, and sort operations
+- [**Change Feeds**](./6.feed.md) - Real-time change notifications via the `changes()` method
+- [**Query**](./7.query.md) - The base class providing execution and async iteration
+- [**Datum**](./8.datum.md) - A single value with field access, transformation, and lookup capabilities
+- [**ValueProxy**](./9.valueproxy.md) - Proxy for in-query value operations (arithmetic, string, date, array, object)

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

@@ -0,0 +1,108 @@
+# Table
+
+The `Table<T>` class represents a database table and provides methods for inserting documents and retrieving them by primary key, secondary index, or range. It extends `Selection<T>`, inheriting all multi-document operations and stream capabilities.
+
+## Class Definition
+
+```typescript
+class Table<T> extends Selection<T> {
+  insert(obj: DeepPartial<T> | DeepPartial<T>[], options?: InsertOptions): Query<string[]>;
+  get(key: string): SingleSelection<T>;
+  getAll(keys: string | number | boolean | (string | number | boolean)[], index?: string): Selection<T>;
+  between<TK extends keyof T>(index: TK, low: T[TK], high: T[TK]): Selection<T>;
+}
+```
+
+## Access a Table
+
+Tables are accessed through a `SchemaInstance`. Define a schema, create an instance, then call `table()`:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = new Schema("myapp", {
+  users: {
+    fields: { name: "string", email: "string" },
+    indexes: { email: {} },
+  },
+});
+
+await schema.createInstance();
+const users = schema.instance().table("users");
+```
+
+## Insert Documents
+
+The `insert` method adds one or more documents to the table and returns the generated IDs.
+
+```typescript
+// Insert a single document
+const ids = await users.insert({
+  name: "Alice Johnson",
+  email: "alice@example.com",
+});
+console.log("Inserted ID:", ids[0]);
+
+// Insert multiple documents
+const batchIds = await users.insert([
+  { name: "Bob", email: "bob@example.com" },
+  { name: "Carol", email: "carol@example.com" },
+]);
+
+// Insert with conflict handling
+const upsertIds = await users.insert(
+  { _id: "user-123", name: "Updated Name" },
+  { conflict: "update" },
+);
+```
+
+### `InsertOptions`
+
+| Option     | Type                     | Description                                         |
+| ---------- | ------------------------ | --------------------------------------------------- |
+| `conflict` | `"update" \| "replace"` | Behavior when a document with the same ID exists. |
+
+## Retrieve Documents
+
+### `get(key)`
+
+Retrieve a single document by its primary key. Returns a `SingleSelection<T>`.
+
+```typescript
+const user = await users.get("user-123");
+
+if (user) {
+  console.log("Found:", user.name);
+}
+```
+
+### `getAll(keys, index?)`
+
+Retrieve multiple documents by key values. When `index` is provided, the lookup uses the specified secondary index instead of the primary key.
+
+```typescript
+// By primary key
+const selected = await users.getAll(["user-1", "user-2", "user-3"]);
+
+// By secondary index
+const admins = await users.getAll("admin", "role");
+```
+
+### `between(index, low, high)`
+
+Retrieve documents where the specified index value falls within a range. The lower bound is inclusive, and the upper bound is exclusive.
+
+```typescript
+const recent = await users.between(
+  "createdAt",
+  new Date("2024-01-01"),
+  new Date(),
+);
+```
+
+## Inherited Methods
+
+Since `Table` extends `Selection`, which extends `Stream`, it inherits:
+
+- **Selection methods**: `update()`, `replace()`, `delete()` -- see [Selection](./3.selection.md)
+- **Stream methods**: `map()`, `filter()`, `orderBy()`, `count()`, `join()`, and more -- see [Stream](./5.stream.md)

package/docs/1.query_types/3.selection.md

@@ -0,0 +1,94 @@
+# Selection
+
+The `Selection<T>` class represents a set of documents and provides methods for bulk mutation operations. It extends `Stream<T>`, inheriting all transformation, filtering, and aggregation capabilities.
+
+## Class Definition
+
+```typescript
+class Selection<T> extends Stream<T> {
+  update(document: DeepPartial<T>): Query<number>;
+  update<U>(document: (val: ValueProxy<T>) => U): Query<number>;
+  replace(document: DeepPartial<T>): Query<number>;
+  delete(): Query<number>;
+}
+```
+
+## Create a Selection
+
+Selections are produced by table methods such as `getAll()` and `between()`, or by chaining stream operations like `filter()`:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+
+// Selection from getAll
+const admins = users.getAll("admin", "role");
+
+// Selection from between
+const recentUsers = users.between("createdAt", new Date("2024-01-01"), new Date());
+```
+
+## Update Documents
+
+The `update` method modifies matching documents with the provided partial data. Fields not included in the update object remain unchanged. It returns the number of modified documents.
+
+```typescript
+// Update with a partial object
+const count = await users
+  .getAll("inactive", "status")
+  .update({ status: "active" });
+
+console.log(`Activated ${count} users`);
+
+// Update with a function for computed values
+await users
+  .getAll("active", "status")
+  .update((user) => ({
+    loginCount: user.key("loginCount").add(1),
+  }));
+```
+
+## Replace Documents
+
+The `replace` method substitutes entire documents with the provided data. Unlike `update`, all fields not present in the replacement are removed.
+
+```typescript
+const count = await users
+  .getAll("user-123")
+  .replace({
+    _id: "user-123",
+    name: "New Name",
+    email: "new@example.com",
+    role: "user",
+  });
+
+console.log(`Replaced ${count} documents`);
+```
+
+## Delete Documents
+
+The `delete` method removes all documents in the selection and returns the number of deleted documents.
+
+```typescript
+const count = await users
+  .getAll("inactive", "status")
+  .delete();
+
+console.log(`Deleted ${count} inactive users`);
+```
+
+## Inherited Methods
+
+Since `Selection` extends `Stream`, it inherits all stream operations:
+
+- Transformation: `map()`, `pluck()`, `without()`
+- Filtering: `filter()`
+- Aggregation: `count()`, `sum()`, `avg()`, `min()`, `max()`
+- Joining: `join()`, `joinInner()`, `lookup()`
+- Ordering: `orderBy()`, `slice()`, `nth()`
+- Grouping: `group()`
+- Deduplication: `distinct()`
+
+See [Stream](./5.stream.md) for complete details on these methods.

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

@@ -0,0 +1,121 @@
+# SingleSelection
+
+The `SingleSelection<T>` class represents a reference to a single document in a table. It extends `Datum<T>` and provides methods for updating, replacing, deleting, and monitoring changes to an individual document.
+
+## Class Definition
+
+```typescript
+class SingleSelection<T> extends Datum<T> {
+  update(document: DeepPartial<T>): Query<number>;
+  update<U>(document: (val: ValueProxy<T>) => U): Query<number>;
+  replace(document: DeepPartial<T>): Query<number>;
+  delete(): Query<number>;
+  changes(): Query<Changes<T>[]>;
+}
+```
+
+## Create a SingleSelection
+
+SingleSelection objects are produced by calling `get()` on a table:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+
+// Get a document by primary key
+const user = users.get("user-123");
+```
+
+## Read a Document
+
+Since `SingleSelection` extends `Datum`, you can execute it directly to retrieve the document value:
+
+```typescript
+const user = await users.get("user-123");
+
+if (user) {
+  console.log("Found:", user.name);
+}
+
+// Access specific fields
+const email = await users.get("user-123").key("email");
+console.log("Email:", email);
+
+// Transform with do()
+const display = await users.get("user-123").do((u) => ({
+  label: u.key("name"),
+  contact: u.key("email"),
+}));
+```
+
+## Update a Document
+
+The `update` method modifies fields in the document. Unmentioned fields remain unchanged. Returns the number of modified documents.
+
+```typescript
+// Update with a partial object
+const count = await users.get("user-123").update({
+  status: "active",
+  lastLogin: new Date(),
+});
+
+// Update with a function for computed values
+await users.get("user-123").update((user) => ({
+  loginCount: user.key("loginCount").add(1),
+  lastLogin: new Date(),
+}));
+```
+
+## Replace a Document
+
+The `replace` method substitutes the entire document with new data.
+
+```typescript
+const count = await users.get("user-123").replace({
+  _id: "user-123",
+  name: "New Name",
+  email: "new@example.com",
+  role: "user",
+});
+```
+
+## Delete a Document
+
+The `delete` method removes the document from the table.
+
+```typescript
+const count = await users.get("user-123").delete();
+
+if (count === 1) {
+  console.log("User deleted successfully");
+}
+```
+
+## Monitor Changes
+
+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) {
+  console.log("Type:", change.changeType); // "added" | "removed" | "modified"
+  console.log("Old:", change.oldValue);
+  console.log("New:", change.newValue);
+}
+```
+
+## Inherited Methods
+
+Since `SingleSelection` extends `Datum`, it inherits:
+
+- **`key()`** - Access a field by name
+- **`default()`** - Provide a fallback value for null
+- **`do()`** - Apply a transformation function
+- **`lookup()`** - Perform a foreign key lookup
+- **`pluck()`** - Select specific fields
+- **`cast()`** - Change the TypeScript type
+
+See [Datum](./8.datum.md) for complete details.

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

@@ -0,0 +1,237 @@
+# Stream
+
+The `Stream<T>` class represents a sequence of documents that can be transformed, filtered, joined, grouped, and aggregated. It extends `Query<T[]>` and serves as the foundation for collection-based operations in AQL.
+
+## Class Definition
+
+```typescript
+class Stream<T> extends Query<T[]> {
+  // Type casting
+  cast<U>(): Stream<U>;
+
+  // Field access
+  key<K extends keyof T>(key: K, def?: unknown): Stream<T[K]>;
+  default<U>(val: Value<U>): Stream<Exclude<T, undefined | null> | U>;
+
+  // Transformation
+  map<U>(mapper: (val: ValueProxy<T>) => U): Stream<ExtractType<U>>;
+  filter(predicate: (val: ValueProxy<T>) => ValueProxyOrValue<boolean>): this;
+  pluck(...fields: string[]): Stream<Partial<T>>;
+  without(...fields: string[]): Stream<Partial<T>>;
+
+  // Combining
+  union<U>(other: Stream<U>): Stream<T | U>;
+
+  // Joining
+  join<U, V>(right: Stream<U>, predicate, mapper): Stream<ExtractType<V>>;
+  joinInner<U, V>(right: Stream<U>, predicate, mapper): Stream<ExtractType<V>>;
+  lookup<U, TK extends keyof T>(right: Selection<U>, localKey: TK, otherKey: keyof U): Stream<...>;
+
+  // Grouping
+  group<U, K>(index: K, mapper: (stream: Stream<T>, group: ValueProxy) => U): Stream<ExtractType<U>>;
+
+  // Ordering and pagination
+  orderBy(index: string, direction?: "asc" | "desc"): this;
+  slice(offset: Value<number>, count?: Value<number>): this;
+  nth(n: Value<number>): Datum<T | null>;
+
+  // Aggregation
+  count(field?: keyof T): Datum<number>;
+  sum(field?: keyof T): Datum<number>;
+  avg(field?: keyof T): Datum<number>;
+  min(field?: keyof T): Datum<number>;
+  max(field?: keyof T): Datum<number>;
+  distinct(): Datum<T[]>;
+  distinct<TK extends keyof T>(field: TK): Stream<T[TK]>;
+
+  // Change feeds
+  changes(): Query<Changes<T>[]>;
+}
+```
+
+## Field Access
+
+Access a specific field from all documents in the stream with `key()`, or provide a default value for null fields with `default()`.
+
+```typescript
+const users = schema.instance().table("users");
+
+// Extract a single field
+const emails = await users.key("email");
+
+// Provide a default value
+const phones = await users.key("phone").default("N/A");
+```
+
+## Transform Data
+
+### `map()`
+
+Transform each document using a mapping function. The callback receives a `ValueProxy<T>` for constructing expressions.
+
+```typescript
+const profiles = await users.map((user) => ({
+  id: user.key("_id"),
+  displayName: user.key("name"),
+  contact: user.key("email"),
+}));
+```
+
+### `filter()`
+
+Select documents matching a predicate. The callback returns a boolean expression.
+
+```typescript
+const active = await users.filter((user) =>
+  user.key("status").eq("active")
+    .and(user.key("age").ge(18)),
+);
+```
+
+### `pluck()` and `without()`
+
+Select or exclude specific fields from all documents.
+
+```typescript
+// Keep only specific fields
+const slim = await users.pluck("_id", "name", "email");
+
+// Remove sensitive fields
+const safe = await users.without("password", "ssn");
+```
+
+## Combine Streams
+
+### `union()`
+
+Concatenate two streams without deduplication.
+
+```typescript
+const allPremium = await users
+  .filter((u) => u.key("plan").eq("premium"))
+  .union(
+    users.filter((u) => u.key("plan").eq("enterprise")),
+  );
+```
+
+## Join Data
+
+### `join()` - Left Join
+
+Perform a left join between two streams. Every document from the left stream appears in the result, with `null` for the right side when no match exists.
+
+```typescript
+const usersWithOrders = await users.join(
+  schema.instance().table("orders"),
+  (user, order) => order.key("userId").eq(user.key("_id")),
+  (user, order) => ({
+    userName: user.key("name"),
+    orderTotal: order.key("amount").default(0),
+  }),
+);
+```
+
+### `joinInner()` - Inner Join
+
+Perform an inner join. Only documents with matches on both sides appear in the result.
+
+```typescript
+const matched = await users.joinInner(
+  schema.instance().table("orders"),
+  (user, order) => order.key("userId").eq(user.key("_id")),
+  (user, order) => ({
+    userName: user.key("name"),
+    amount: order.key("amount"),
+  }),
+);
+```
+
+### `lookup()`
+
+Replace a foreign key field with the referenced document from another table. See [Lookup](../2.operations/7.lookup.md) for detailed usage.
+
+```typescript
+const postsWithAuthors = await schema
+  .instance()
+  .table("posts")
+  .lookup(schema.instance().table("users"), "authorId", "_id");
+```
+
+## Group Data
+
+The `group` method partitions the stream by an index value, then applies a mapping function to each group. The mapper receives the group's sub-stream and the group key.
+
+```typescript
+const statsByRole = await users.group("role", (stream, role) => ({
+  role: role,
+  total: stream.count(),
+  avgAge: stream.avg("age"),
+}));
+```
+
+## Order and Paginate
+
+### `orderBy()`
+
+Sort the stream by an index field.
+
+```typescript
+const sorted = await users.orderBy("name", "asc");
+const newest = await users.orderBy("createdAt", "desc");
+```
+
+### `slice()`
+
+Extract a subsection of the stream for pagination.
+
+```typescript
+const page1 = await users.orderBy("createdAt").slice(0, 10);
+const page2 = await users.orderBy("createdAt").slice(10, 10);
+```
+
+### `nth()`
+
+Retrieve a single document by its position in the stream. Returns a `Datum<T | null>`.
+
+```typescript
+const first = await users.orderBy("createdAt").nth(0);
+```
+
+## Aggregate Data
+
+Stream provides several aggregation methods that return a `Datum<number>`:
+
+```typescript
+const totalUsers = await users.count();
+const distinctEmails = await users.count("email");
+const totalSales = await schema.instance().table("orders").sum("amount");
+const avgOrder = await schema.instance().table("orders").avg("amount");
+const maxOrder = await schema.instance().table("orders").max("amount");
+const minOrder = await schema.instance().table("orders").min("amount");
+```
+
+### `distinct()`
+
+Retrieve deduplicated documents or distinct values of a specific field.
+
+```typescript
+// All distinct documents
+const unique = await users.distinct();
+
+// Distinct values of a field
+const roles = await users.distinct("role");
+```
+
+## Change Feeds
+
+The `changes` method subscribes to real-time change notifications on the stream.
+
+```typescript
+const changes = await users.changes();
+
+for (const change of changes) {
+  console.log(change.changeType, change.oldValue, change.newValue);
+}
+```
+
+See [Change Feeds](./6.feed.md) for more details.

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

@@ -0,0 +1,82 @@
+# Change Feeds
+
+Change feeds provide real-time notifications when documents are inserted, updated, or deleted. Both `Stream<T>` and `SingleSelection<T>` expose a `changes()` method that returns change events.
+
+## The Changes Interface
+
+```typescript
+interface Changes<T> {
+  changeType: "added" | "removed" | "modified";
+  oldValue?: T;
+  newValue?: T;
+}
+```
+
+| Property     | Description                                                        |
+| ------------ | ------------------------------------------------------------------ |
+| `changeType` | The type of change: `"added"`, `"removed"`, or `"modified"`.      |
+| `oldValue`   | The document value before the change. Undefined for new documents. |
+| `newValue`   | The document value after the change. Undefined for deletions.      |
+
+## Create a Change Feed
+
+Call `changes()` on any stream or single selection to subscribe to change events:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+
+// Monitor all changes to a table
+const allChanges = await users.changes();
+
+// Monitor changes to a specific document
+const userChanges = await users.get("user-123").changes();
+```
+
+## Process Change Events
+
+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;
+  }
+}
+```
+
+## Use with Async Iteration
+
+Since `changes()` returns a `Query`, you can use the cursor for streaming results:
+
+```typescript
+const feed = users.changes();
+
+for await (const batch of feed) {
+  for (const change of batch) {
+    console.log(`${change.changeType}:`, change.newValue ?? change.oldValue);
+  }
+}
+```
+
+## Use Cases
+
+Change feeds are well suited for:
+
+- **Real-time UI updates** - Push changes to connected clients as they happen.
+- **Event-driven architectures** - React to data changes with downstream processing.
+- **Audit logging** - Record every modification to a collection.
+- **Cache invalidation** - Clear or update caches when the underlying data changes.