@antelopejs/interface-database 0.1.3 → 0.1.5

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

@@ -0,0 +1,92 @@
+# 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,234 @@
+# 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.

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

@@ -0,0 +1,82 @@
+# Query
+
+The `Query<T>` class is the base class for all query types in the AQL system. It implements `PromiseLike<T>`, so queries can be awaited directly, and provides cursor-based async iteration for streaming results.
+
+## Class Definition
+
+```typescript
+class Query<T> extends StagedObject implements PromiseLike<T> {
+  run(): Promise<T>;
+  then<TResult1, TResult2>(
+    onfulfilled?: (value: T) => TResult1 | PromiseLike<TResult1>,
+    onrejected?: (reason: any) => TResult2 | PromiseLike<TResult2>,
+  ): PromiseLike<TResult1 | TResult2>;
+  cursor(): AsyncGenerator<T extends Array<infer T1> ? T1 : T, void, unknown>;
+  [Symbol.asyncIterator](): AsyncGenerator<...>;
+}
+```
+
+## Execute a Query
+
+### `run()`
+
+Execute the query pipeline and return the result as a promise.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = await schema.instance().table("users").run();
+```
+
+### Direct `await`
+
+Since `Query` implements `PromiseLike`, you can await it directly without calling `run()`:
+
+```typescript
+const users = await schema.instance().table("users");
+```
+
+Both approaches are equivalent. Use whichever reads better in context.
+
+## Async Iteration
+
+### `cursor()`
+
+Return an `AsyncGenerator` that yields results one at a time. This is useful for processing large result sets without loading everything into memory.
+
+```typescript
+const cursor = schema.instance().table("users").cursor();
+
+let result = await cursor.next();
+while (!result.done) {
+  console.log("User:", result.value);
+  result = await cursor.next();
+}
+```
+
+### `for await...of`
+
+The `[Symbol.asyncIterator]()` method enables the `for await...of` syntax:
+
+```typescript
+for await (const user of schema.instance().table("users")) {
+  console.log("Processing:", user.name);
+}
+```
+
+## Query Composition
+
+Queries use lazy evaluation. Operations are recorded as pipeline stages and only execute when `run()`, `then()`, or iteration begins. This means you can build queries incrementally:
+
+```typescript
+const usersTable = schema.instance().table("users");
+
+// Build different queries from the same base
+const activeUsers = usersTable.filter((u) => u.key("status").eq("active"));
+const inactiveUsers = usersTable.filter((u) => u.key("status").eq("inactive"));
+
+// Execute them independently
+const active = await activeUsers;
+const inactive = await inactiveUsers;
+```