@antelopejs/interface-database 0.1.3 → 0.1.4

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

@@ -0,0 +1,137 @@
+# 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/3.results/1.index.md

@@ -0,0 +1,38 @@
+# Results
+
+AQL operations return structured result values that communicate what happened during execution. This section covers the result types produced by write operations and change feeds.
+
+## Result Types
+
+- [2. Insert Results](./2.write_results.md) - Return values from insert operations
+- [3. Index Definitions](./3.index_changes.md) - Index configuration in schema definitions
+- [4. Table Definitions](./4.table_changes.md) - Table structure and field types
+- [5. Schema and Instance Management](./5.database_changes.md) - Schema lifecycle and instance management
+- [6. Change Events](./6.value_changes.md) - Structure of change feed notifications
+
+## Common Patterns
+
+All AQL operations follow a consistent pattern:
+
+1. Build a query by chaining operations.
+2. Execute the query with `run()` or `await` to get the result.
+3. Process the structured result.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+
+// Insert returns an array of generated IDs
+const ids = await users.insert({ name: "Alice", email: "alice@example.com" });
+console.log("New ID:", ids[0]);
+
+// Update/delete return the number of affected documents
+const count = await users.get("user-123").update({ status: "active" });
+console.log(`Modified ${count} documents`);
+
+// Delete returns the number of deleted documents
+const deleted = await users.get("user-123").delete();
+console.log(`Deleted ${deleted} documents`);
+```

package/docs/3.results/2.write_results.md

@@ -0,0 +1,86 @@
+# Insert Results
+
+The `insert` method on `Table<T>` returns a `Query<string[]>` that resolves to an array of the generated or provided primary keys for the inserted documents.
+
+## Return Value
+
+```typescript
+// Insert returns string[] (the IDs of inserted documents)
+const ids: string[] = await users.insert({
+  name: "Alice",
+  email: "alice@example.com",
+});
+```
+
+## Examples
+
+### Single Document Insert
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+
+const ids = await users.insert({
+  name: "John Doe",
+  email: "john@example.com",
+});
+
+console.log("Inserted document ID:", ids[0]);
+```
+
+### Multiple Document Insert
+
+```typescript
+const ids = await users.insert([
+  { name: "Alice", email: "alice@example.com" },
+  { name: "Bob", email: "bob@example.com" },
+  { name: "Carol", email: "carol@example.com" },
+]);
+
+console.log(`Inserted ${ids.length} documents`);
+console.log("IDs:", ids);
+```
+
+### Insert with Conflict Handling
+
+Use the `conflict` option to control behavior when a document with the same primary key already exists:
+
+```typescript
+// Update matching fields on conflict
+const ids = await users.insert(
+  { _id: "user-123", name: "Updated Name", lastSeen: new Date() },
+  { conflict: "update" },
+);
+
+// Replace the entire document on conflict
+const ids2 = await users.insert(
+  { _id: "user-123", name: "Replaced", email: "new@example.com" },
+  { conflict: "replace" },
+);
+```
+
+## Update and Delete Results
+
+The `update`, `replace`, and `delete` methods return a `Query<number>` that resolves to the count of affected documents:
+
+```typescript
+// Update returns the number of modified documents
+const updated = await users.get("user-123").update({ status: "active" });
+console.log(`Modified: ${updated}`);
+
+// Replace returns the number of replaced documents
+const replaced = await users.get("user-123").replace({
+  _id: "user-123",
+  name: "New",
+  email: "new@example.com",
+});
+console.log(`Replaced: ${replaced}`);
+
+// Delete returns the number of deleted documents
+const deleted = await users
+  .filter((u) => u.key("status").eq("inactive"))
+  .delete();
+console.log(`Deleted: ${deleted}`);
+```

package/docs/3.results/3.index_changes.md

@@ -0,0 +1,78 @@
+# Index Definitions
+
+In AQL, indexes are defined as part of the schema definition rather than created at runtime. The schema declaration specifies which fields to index and what type of index to use.
+
+## `IndexDefinition`
+
+```typescript
+interface IndexDefinition {
+  fields?: string[];  // Fields for compound indexes
+  multi?: boolean;    // Multi-valued index
+}
+```
+
+## Define Indexes
+
+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" },
+    indexes: {
+      email: {},                              // Simple index (field name = index name)
+      role: {},                               // Simple index
+      name_role: { fields: ["name", "role"] }, // Compound index
+    },
+  },
+});
+```
+
+### Simple Indexes
+
+When `fields` is omitted, the index name is used as the field name:
+
+```typescript
+indexes: {
+  email: {},  // Creates an index on the "email" field
+}
+```
+
+### Compound Indexes
+
+Provide the `fields` array for indexes spanning multiple fields:
+
+```typescript
+indexes: {
+  full_name: { fields: ["firstName", "lastName"] },
+}
+```
+
+### Multi Indexes
+
+Set `multi: true` for array fields where each element should be individually indexed:
+
+```typescript
+indexes: {
+  tags: { multi: true },
+}
+```
+
+## Use Indexes in Queries
+
+Once defined, indexes are available for `getAll()` and `between()` operations:
+
+```typescript
+const db = schema.instance();
+const users = db.table("users");
+
+// Lookup by secondary index
+const admins = await users.getAll("admin", "role");
+
+// Range query on an indexed field
+const recent = await users.between("createdAt", new Date("2024-01-01"), new Date());
+```
+
+For more details, see [Index Management](../2.operations/5.indexes.md).

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

@@ -0,0 +1,105 @@
+# Table Definitions
+
+In AQL, tables are defined as part of a schema. Each table definition specifies the fields and indexes for that table.
+
+## `TableDefinition`
+
+```typescript
+interface TableDefinition {
+  fields: Record<string, FieldType>;
+  indexes: Record<string, IndexDefinition>;
+}
+```
+
+### `FieldType`
+
+Field types describe the structure of each field:
+
+```typescript
+type FieldType =
+  | string                              // Primitive type name (e.g., "string", "number")
+  | Array<StringFieldType>              // Array of a given type
+  | { [subfield: string]: StringFieldType } // Nested object
+  | import("io-ts").Mixed;              // io-ts codec at the field root
+```
+
+A field can be described either with the string-token vocabulary (primitives, arrays, nested records) or with a single [io-ts](https://github.com/gcanti/io-ts) codec at the root of the field. Codecs are not mixed inside string-tree records — use io-ts combinators (`t.type`, `t.array`, …) to nest within a codec.
+
+```typescript
+import * as t from "io-ts";
+
+const Order = {
+  fields: {
+    id: "string",
+    status: t.union([t.literal("open"), t.literal("closed")]),
+    meta: t.type({ source: t.string, retries: t.number }),
+  },
+  indexes: {},
+};
+```
+
+## Define Tables in a Schema
+
+Tables are declared in the `SchemaDefinition` passed to the `Schema` constructor:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = new Schema("myapp", {
+  users: {
+    fields: {
+      name: "string",
+      email: "string",
+      age: "number",
+      address: {
+        street: "string",
+        city: "string",
+        zip: "string",
+      },
+      tags: ["string"],
+    },
+    indexes: {
+      email: {},
+      age: {},
+    },
+  },
+  posts: {
+    fields: {
+      title: "string",
+      content: "string",
+      authorId: "string",
+      publishedAt: "date",
+    },
+    indexes: {
+      authorId: {},
+      publishedAt: {},
+    },
+  },
+});
+```
+
+## Access Tables
+
+After creating a schema instance, access tables by name:
+
+```typescript
+await schema.createInstance();
+
+const users = schema.instance().table("users");
+const posts = schema.instance().table("posts");
+```
+
+For type-safe access, provide a generic type parameter:
+
+```typescript
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+  age: number;
+}
+
+const users = schema.instance().table<User>("users");
+```
+
+For more details on table operations, see [Table Operations](../2.operations/3.table_operations.md).

package/docs/3.results/5.database_changes.md

@@ -0,0 +1,96 @@
+# Schema and Instance Management
+
+This page covers the `Schema`, `SchemaInstance`, and related types that control database structure and lifecycle.
+
+## Schema
+
+The `Schema<T>` class defines the structure of a database and manages its instances.
+
+```typescript
+class Schema<T = any> extends StagedObject {
+  static get(id: string): Schema | undefined;
+  constructor(id: string, definition: SchemaDefinition);
+  instance(id?: InstanceId): SchemaInstance<T>;
+  createInstance(id?: string): Query<string>;
+  destroyInstance(id?: string): Query<void>;
+  listInstances(): Query<string[]>;
+}
+```
+
+### `SchemaDefinition`
+
+```typescript
+interface SchemaDefinition {
+  [tableName: string]: TableDefinition;
+}
+```
+
+### `InstanceId` and `CROSS_INSTANCE`
+
+```typescript
+const CROSS_INSTANCE: unique symbol;
+type InstanceId = string | typeof CROSS_INSTANCE;
+```
+
+`schema.instance(CROSS_INSTANCE)` returns a query stage that operates across every instance of the schema. Adapters skip the per-instance filter on read/update/delete and reject inserts.
+
+## Create and Manage Instances
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+// Define a schema
+const schema = new Schema("myapp", {
+  users: {
+    fields: { name: "string" },
+    indexes: {},
+  },
+});
+
+// Create the default instance
+const instanceId = await schema.createInstance();
+
+// Create a named instance
+await schema.createInstance("tenant-1");
+
+// Access instances
+const defaultDb = schema.instance();
+const tenantDb = schema.instance("tenant-1");
+
+// Destroy an instance
+await schema.destroyInstance("tenant-1");
+
+// List named instances
+const ids = await schema.listInstances();
+```
+
+## Retrieve a Schema
+
+Use `Schema.get()` to look up a previously defined schema anywhere in your application:
+
+```typescript
+const schema = Schema.get("myapp");
+
+if (schema) {
+  const db = schema.instance();
+  const users = db.table("users");
+}
+```
+
+## SchemaInstance
+
+The `SchemaInstance<T>` class represents a single instance of a schema. Its primary method is `table()`, which returns a `Table` for the specified table name.
+
+```typescript
+class SchemaInstance<T> extends StagedObject {
+  table<TK extends keyof T>(id: TK): Table<T[TK]>;
+}
+```
+
+```typescript
+const db = schema.instance();
+const users = db.table("users");
+const posts = db.table("posts");
+```
+
+For practical usage patterns, see [Schema Management](../2.operations/2.database_management.md).

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

@@ -0,0 +1,75 @@
+# Change Events
+
+The `Changes<T>` interface represents a change event emitted by change feeds. It includes the type of change and the document values before and after the change.
+
+## Interface Definition
+
+```typescript
+interface Changes<T> {
+  changeType: "added" | "removed" | "modified";
+  oldValue?: T;
+  newValue?: T;
+}
+```
+
+## Properties
+
+| Property     | Type                                     | Description                                          |
+| ------------ | ---------------------------------------- | ---------------------------------------------------- |
+| `changeType` | `"added" \| "removed" \| "modified"`    | The kind of change that occurred.                    |
+| `oldValue`   | `T \| undefined`                        | The document before the change. Undefined for inserts.|
+| `newValue`   | `T \| undefined`                        | The document after the change. Undefined for deletes. |
+
+## Determine the Change Type
+
+The `changeType` field indicates what happened:
+
+- **`"added"`** - A new document was inserted. `newValue` contains the document; `oldValue` is undefined.
+- **`"modified"`** - An existing document was updated. Both `oldValue` and `newValue` are present.
+- **`"removed"`** - A document was deleted. `oldValue` contains the deleted document; `newValue` is undefined.
+
+## Process Change Events
+
+```typescript
+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) {
+  switch (change.changeType) {
+    case "added":
+      console.log("New document:", change.newValue);
+      break;
+    case "modified":
+      console.log("Updated:", change.oldValue, "->", change.newValue);
+      break;
+    case "removed":
+      console.log("Deleted:", change.oldValue);
+      break;
+  }
+}
+```
+
+## Monitor a Single Document
+
+```typescript
+const userChanges = await users.get("user-123").changes();
+
+for (const change of userChanges) {
+  if (change.changeType === "modified") {
+    console.log("User updated:", change.newValue);
+  } else if (change.changeType === "removed") {
+    console.log("User deleted");
+  }
+}
+```
+
+## Use Cases
+
+- **Real-time notifications** - Push updates to connected clients when data changes.
+- **Audit logging** - Record every modification with before/after snapshots.
+- **Cache invalidation** - Clear or refresh caches when underlying data is modified.
+- **Event-driven workflows** - Trigger downstream processing based on data changes.

package/docs/index.md

@@ -0,0 +1,50 @@
+# Database Interface
+
+## Overview
+
+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.
+
+## Documentation Structure
+
+- [**1. Query Types**](./1.query_types/1.index.md) - Detailed reference for each query type:
+
+  - [Table](./1.query_types/2.table.md) - Table-level operations (insert, get, getAll, between)
+  - [Selection](./1.query_types/3.selection.md) - Multi-document operations (update, replace, delete)
+  - [SingleSelection](./1.query_types/4.single_selection.md) - Single-document operations
+  - [Stream](./1.query_types/5.stream.md) - Transformation, filtering, aggregation, joins, and grouping
+  - [Change Feeds](./1.query_types/6.feed.md) - Real-time change notifications
+  - [Query](./1.query_types/7.query.md) - Base query execution and async iteration
+  - [Datum](./1.query_types/8.datum.md) - Single-value manipulation
+  - [ValueProxy](./1.query_types/9.valueproxy.md) - In-query value operations (arithmetic, string, date, array, object)
+
+- [**2. Operations**](./2.operations/1.index.md) - Practical guides:
+
+  - [Schema Management](./2.operations/2.database_management.md) - Create and manage schema instances
+  - [Table Operations](./2.operations/3.table_operations.md) - Access and work with tables
+  - [CRUD Operations](./2.operations/4.crud.md) - Create, read, update, and delete documents
+  - [Index Management](./2.operations/5.indexes.md) - Define and use secondary indexes
+  - [Filtering and Querying](./2.operations/6.filtering.md) - Filter, compare, and transform data
+  - [Lookup](./2.operations/7.lookup.md) - Foreign key joins and data population
+
+- [**3. Results**](./3.results/1.index.md) - Result types and handling:
+  - [Insert Results](./3.results/2.write_results.md) - Results from insert operations
+  - [Index Definitions](./3.results/3.index_changes.md) - Index configuration in schema definitions
+  - [Table Definitions](./3.results/4.table_changes.md) - Table structure and field types
+  - [Schema and Instance Management](./3.results/5.database_changes.md) - Schema lifecycle and instance management
+  - [Change Events](./3.results/6.value_changes.md) - Change feed event structure
+
+## Features
+
+- Database-agnostic query interface
+- Consistent API across different database implementations
+- Type-safe operations using TypeScript generics
+- Schema-based database structure definition
+- Multi-instance support per schema
+- Secondary index support
+- Change feeds for real-time updates
+- Async iteration with cursor support
+- Chainable query builder with lazy evaluation
+
+## Database Interoperability
+
+AQL decouples your application logic from the database engine. The same query code works with any backend that implements the interface, such as MongoDB, RethinkDB, or other community-provided implementations. This reduces migration cost and keeps your code portable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-database",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "AntelopeJS interface for database-agnostic query operations",
   "keywords": [
     "antelopejs",
@@ -16,7 +16,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -110,6 +112,9 @@
     }
   },
   "antelopeJs": {
-    "test": "src/antelope.test.ts"
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   }
 }