@antelopejs/interface-database 0.1.3 → 0.1.4

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;
+```

package/docs/1.query_types/8.datum.md

@@ -0,0 +1,102 @@
+# Datum
+
+The `Datum<T>` class represents a single value in the query system. It extends `Query<T>` and provides methods for accessing fields, applying transformations, and performing foreign key lookups on individual values.
+
+## Class Definition
+
+```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]>;
+  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<...>;
+  pluck(...fields: string[]): Datum<Partial<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.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+
+// Access a field
+const name = await users.get("user-123").key("name");
+
+// Access a nested field
+const city = await users.get("user-123").key("address").key("city");
+
+// Provide a default value
+const phone = await users.get("user-123").key("phone", "N/A");
+```
+
+## Default Values
+
+The `default` method provides a fallback value when the datum is null or undefined.
+
+```typescript
+const user = await users.get("maybe-missing").default({
+  _id: "guest",
+  name: "Guest User",
+  role: "visitor",
+});
+```
+
+## Transform with `do()`
+
+The `do` method applies a transformation function to the datum. The callback receives a `ValueProxy<T>` that provides operators for building expressions.
+
+```typescript
+const formatted = await users.get("user-123").do((user) => ({
+  displayName: user.key("name"),
+  contact: user.key("email"),
+  hasPhone: user.key("phone").ne(undefined),
+}));
+```
+
+## Foreign Key Lookup
+
+The `lookup` method replaces a foreign key field with the referenced document from another table.
+
+```typescript
+interface Post {
+  _id: string;
+  title: string;
+  authorId: string;
+}
+
+interface User {
+  _id: string;
+  name: string;
+}
+
+const post = await schema
+  .instance()
+  .table<Post>("posts")
+  .get("post-1")
+  .lookup(schema.instance().table<User>("users"), "authorId", "_id");
+
+// post.authorId is now the full User object
+console.log(post.authorId.name);
+```
+
+## Field Selection
+
+The `pluck` method selects specific fields from a document datum, discarding the rest.
+
+```typescript
+const profile = await users.get("user-123").pluck("name", "email", "avatar");
+```
+
+## Type Casting
+
+The `cast` method changes the TypeScript type of the datum without performing any runtime conversion. Use this when you know the actual type differs from what the compiler infers.
+
+```typescript
+const raw = users.get("user-123").cast<{ name: string; role: string }>();
+```

package/docs/1.query_types/9.valueproxy.md

@@ -0,0 +1,230 @@
+# ValueProxy
+
+The `ValueProxy<T>` class acts as a proxy to a database value. Operations on a ValueProxy are not executed immediately but are recorded as query stages. ValueProxy objects appear inside callback functions for `map`, `filter`, `do`, `update`, `join`, and other query methods.
+
+## Class Definition
+
+ValueProxy provides type-specific methods based on the underlying value type. The available operations are organized by category.
+
+## Create a ValueProxy
+
+ValueProxy instances are created automatically when you use callback-based query methods. You can also create one from a constant value:
+
+```typescript
+import { ValueProxy } from "@antelopejs/interface-database";
+
+const constant = ValueProxy.constant(42);
+const strConst = ValueProxy.constant("hello");
+```
+
+## General Operations
+
+These methods are available on all ValueProxy types.
+
+### `default(value)`
+
+Return the given value if the proxy is null.
+
+```typescript
+const phone = user.key("phone").default("N/A");
+```
+
+### `eq(value)` / `ne(value)`
+
+Equality and inequality comparison.
+
+```typescript
+const isActive = user.key("status").eq("active");
+const isNotAdmin = user.key("role").ne("admin");
+```
+
+### `and(value)` / `or(value)` / `not()`
+
+Logical operators for combining boolean expressions.
+
+```typescript
+const canAccess = user.key("active").and(user.key("verified"));
+const isSpecial = user.key("role").eq("admin").or(user.key("plan").eq("premium"));
+const isInactive = user.key("active").not();
+```
+
+### `cast<U>()`
+
+Change the TypeScript type without runtime conversion.
+
+## Number Operations
+
+Available when the proxy wraps a numeric value.
+
+### Arithmetic
+
+```typescript
+const next = age.add(1);
+const diff = total.sub(discount);
+const doubled = price.mul(2);
+const half = amount.div(2);
+const remainder = count.mod(10);
+```
+
+### Rounding
+
+```typescript
+const rounded = score.round();
+const ceiling = value.ceil();
+const floored = value.floor();
+```
+
+### Bitwise
+
+```typescript
+const bitwiseAnd = flags.band(0xff);
+const bitwiseOr = flags.bor(0x01);
+const bitwiseXor = flags.bxor(mask);
+const bitwiseNot = flags.bnot();
+const shifted = flags.blshift(2);
+const unshifted = flags.brshift(2);
+const signPreserved = flags.brshiftPreserveSign(2);
+```
+
+## Comparison Operations
+
+Available for `number`, `string`, and `Date` proxy values.
+
+```typescript
+const isAdult = age.gt(17);
+const isMinor = age.le(17);
+const isRecent = date.ge(new Date("2024-01-01"));
+const isBefore = date.lt(deadline);
+```
+
+| Method   | Description            |
+| -------- | ---------------------- |
+| `gt(v)`  | Greater than           |
+| `ge(v)`  | Greater than or equal  |
+| `lt(v)`  | Less than              |
+| `le(v)`  | Less than or equal     |
+
+## Date Operations
+
+Available when the proxy wraps a `Date` value. All date component methods accept an optional `timezone` parameter.
+
+### Arithmetic
+
+```typescript
+const threeDaysLater = created.add(3 * 24 * 60 * 60);
+const elapsed = now.sub(created); // difference in seconds
+```
+
+### Components
+
+```typescript
+const y = created.year();
+const m = created.month();
+const d = created.day();
+const dow = created.dayofweek();
+const doy = created.dayofyear();
+const h = created.hours();
+const min = created.minutes();
+const sec = created.seconds();
+const tod = created.timeofday(); // seconds since midnight
+const epoch = created.epoch();   // seconds since UNIX epoch
+```
+
+### Range Check
+
+```typescript
+const inRange = created.during(
+  ValueProxy.constant(new Date("2024-01-01")),
+  ValueProxy.constant(new Date("2025-01-01")),
+);
+```
+
+## String Operations
+
+Available when the proxy wraps a `string` value.
+
+```typescript
+const upper = name.upcase();
+const lower = name.downcase();
+const parts = email.split("@");
+const full = first.concat(last);
+const len = name.strlen();
+const matches = email.match("^.*@gmail\\.com$");
+```
+
+| Method              | Description                    |
+| ------------------- | ------------------------------ |
+| `upcase()`          | Convert to uppercase           |
+| `downcase()`        | Convert to lowercase           |
+| `split(sep, max?)`  | Split by separator             |
+| `concat(other)`     | Concatenate with another string|
+| `strlen()`          | Number of Unicode codepoints   |
+| `match(regex)`      | Test against a regex pattern   |
+
+## Array Operations
+
+Available when the proxy wraps an array value.
+
+```typescript
+const first = tags.index(0);
+const hasAdmin = tags.includes("admin");
+const sub = tags.slice(0, 3);
+const upper = tags.map((t) => t.upcase());
+const long = tags.filter((t) => t.strlen().gt(5));
+const empty = tags.isempty();
+const len = tags.count();
+const total = scores.sum();
+const average = scores.avg();
+const lowest = scores.min();
+const highest = scores.max();
+```
+
+| Method           | Description                        |
+| ---------------- | ---------------------------------- |
+| `index(n)`       | Element at position `n`            |
+| `includes(val)`  | Check if the array contains a value|
+| `slice(s, e?)`   | Extract a sub-array                |
+| `map(fn)`        | Transform each element             |
+| `filter(fn)`     | Keep elements matching a predicate |
+| `isempty()`      | Check if the array is empty        |
+| `count()`        | Number of elements                 |
+| `sum()`          | Sum of numeric elements            |
+| `avg()`          | Average of numeric elements        |
+| `min()`          | Minimum of numeric elements        |
+| `max()`          | Maximum of numeric elements        |
+
+## Object Operations
+
+Available when the proxy wraps a record/object value.
+
+```typescript
+const email = user.key("email");
+const emailOrDefault = user.key("email", "none@example.com");
+const merged = user.merge({ lastSeen: new Date() });
+const fieldNames = user.keys();
+const fieldValues = user.values();
+const hasRequired = user.hasfields("email", "name");
+```
+
+| Method             | Description                          |
+| ------------------ | ------------------------------------ |
+| `key(k, def?)`     | Access a field, with optional default|
+| `merge(other)`     | Merge with another object            |
+| `keys()`           | Array of field names                 |
+| `values()`         | Array of field values                |
+| `hasfields(...fs)` | Check if all specified fields exist  |
+
+## Compose Expressions
+
+ValueProxy methods are chainable, enabling complex expressions within query callbacks:
+
+```typescript
+const result = await users.filter((user) =>
+  user.key("age").ge(18)
+    .and(user.key("status").eq("active"))
+    .and(
+      user.key("role").eq("admin")
+        .or(user.key("plan").eq("premium")),
+    ),
+);
+```

package/docs/2.operations/1.index.md

@@ -0,0 +1,34 @@
+# Operations
+
+This section covers practical operations you can perform with the AQL interface. These guides walk through schema management, table access, document CRUD, index usage, filtering, and foreign key lookups.
+
+## Schema and Instance Management
+
+AQL organizes data through schemas and instances:
+
+- [2. Schema Management](./2.database_management.md) - Define schemas, create and destroy instances
+
+## Table Access
+
+Tables live inside schema instances:
+
+- [3. Table Operations](./3.table_operations.md) - Access tables and work with their contents
+
+## Document Operations
+
+Documents are the fundamental unit of data in AQL:
+
+- [4. CRUD Operations](./4.crud.md) - Insert, read, update, replace, and delete documents
+
+## Index Operations
+
+Indexes accelerate queries by enabling efficient lookups:
+
+- [5. Index Management](./5.indexes.md) - Define secondary indexes in schema definitions
+
+## Query Operations
+
+Transform and filter data with the query builder:
+
+- [6. Filtering and Querying](./6.filtering.md) - Filter, compare, and transform documents
+- [7. Lookup](./7.lookup.md) - Foreign key joins and data population

package/docs/2.operations/2.database_management.md

@@ -0,0 +1,151 @@
+# Schema Management
+
+AQL organizes data through schemas and instances. A `Schema` defines the structure of your database (tables, fields, and indexes). Each schema can have multiple instances, and the underlying module implementation determines how instances map to physical storage.
+
+## Define a Schema
+
+Create a schema by providing an ID and a definition of tables with their fields and indexes:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = new Schema("myapp", {
+  users: {
+    fields: { name: "string", email: "string", role: "string" },
+    indexes: {
+      email: {},
+      role: {},
+    },
+  },
+  posts: {
+    fields: { title: "string", content: "string", authorId: "string" },
+    indexes: {
+      authorId: {},
+    },
+  },
+});
+```
+
+### `SchemaDefinition`
+
+A schema definition is a record mapping table names to their `TableDefinition`:
+
+```typescript
+interface TableDefinition {
+  fields: Record<string, FieldType>;
+  indexes: Record<string, IndexDefinition>;
+}
+
+interface IndexDefinition {
+  fields?: string[];  // For compound indexes
+  multi?: boolean;    // Multi-valued index
+}
+```
+
+## Create an Instance
+
+After defining a schema, create an instance to start working with data. The optional `id` parameter distinguishes multiple instances of the same schema.
+
+```typescript
+// Create the default instance
+await schema.createInstance();
+
+// Create a named instance
+await schema.createInstance("tenant-abc");
+```
+
+## Access an Instance
+
+Retrieve a `SchemaInstance` to access tables:
+
+```typescript
+// Default instance
+const db = schema.instance();
+
+// Named instance
+const tenantDb = schema.instance("tenant-abc");
+```
+
+To operate across every instance of the schema, pass the `CROSS_INSTANCE` sentinel:
+
+```typescript
+import { CROSS_INSTANCE } from "@antelopejs/interface-database";
+
+const everything = schema.instance(CROSS_INSTANCE).table("users");
+```
+
+## Destroy an Instance
+
+Remove an instance and its data:
+
+```typescript
+await schema.destroyInstance("tenant-abc");
+```
+
+## List Instances
+
+List the IDs of named instances of a schema:
+
+```typescript
+const ids = await schema.listInstances();
+// ["tenant-abc", "tenant-xyz"]
+```
+
+The default (unnamed) instance is not included.
+
+## Retrieve a Schema
+
+Use the static `Schema.get()` method to look up a previously defined schema by its ID:
+
+```typescript
+const schema = Schema.get("myapp");
+
+if (schema) {
+  const users = schema.instance().table("users");
+}
+```
+
+## Work with Tables
+
+Once you have a `SchemaInstance`, access tables by name. The generic type parameter provides type safety for your documents:
+
+```typescript
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+interface Post {
+  _id: string;
+  title: string;
+  content: string;
+  authorId: string;
+}
+
+const db = schema.instance();
+const users = db.table<User>("users");
+const posts = db.table<Post>("posts");
+```
+
+## Multi-Tenant Pattern
+
+Schemas with multiple instances support multi-tenant architectures. Each tenant gets an isolated instance of the same schema:
+
+```typescript
+const schema = new Schema("saas", {
+  projects: {
+    fields: { name: "string" },
+    indexes: {},
+  },
+});
+
+// Create one instance per tenant
+await schema.createInstance("tenant-1");
+await schema.createInstance("tenant-2");
+
+// Access tenant-specific data
+const tenant1Projects = schema.instance("tenant-1").table("projects");
+const tenant2Projects = schema.instance("tenant-2").table("projects");
+```