@antelopejs/interface-database 0.1.3 → 0.1.5

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,232 @@
+# 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");
+```

package/docs/2.operations/3.table_operations.md

@@ -0,0 +1,117 @@
+# Table Operations
+
+Tables are the primary containers for documents in AQL. They are accessed through a `SchemaInstance` and provide methods for inserting, retrieving, and querying documents.
+
+## Access a Table
+
+Retrieve a table reference from a schema instance:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const db = schema.instance();
+const users = db.table("users");
+```
+
+## Type-Safe Tables
+
+Provide a generic type parameter to get type-safe operations:
+
+```typescript
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+  status: string;
+}
+
+const users = db.table<User>("users");
+
+// TypeScript now validates field names and types
+const user = await users.get("user-123"); // user is User | null
+const emails = await users.key("email"); // string[]
+```
+
+## Basic Operations
+
+### Retrieve All Documents
+
+A table reference doubles as a stream of all its documents:
+
+```typescript
+const allUsers = await users;
+console.log(`Total users: ${allUsers.length}`);
+```
+
+### Retrieve by Primary Key
+
+```typescript
+const user = await users.get("user-123");
+
+if (user) {
+  console.log("Found:", user.name);
+}
+```
+
+### Retrieve by Secondary Index
+
+```typescript
+const admins = await users.getAll("admin", "role");
+```
+
+### Retrieve by Range
+
+```typescript
+const recent = await users.between(
+  "createdAt",
+  new Date("2024-01-01"),
+  new Date(),
+);
+```
+
+## Chain Operations
+
+Since `Table` extends `Selection` and `Stream`, you can chain any stream operation directly:
+
+```typescript
+// Filter and sort
+const activeByName = await users
+  .filter((u) => u.key("status").eq("active"))
+  .orderBy("name");
+
+// Paginate
+const page = await users.orderBy("createdAt").slice(0, 10);
+
+// Aggregate
+const count = await users.count();
+const avgAge = await users.avg("age");
+
+// Transform
+const names = await users.map((u) => u.key("name"));
+```
+
+## Insert Documents
+
+```typescript
+// Single document
+const ids = await users.insert({
+  name: "Alice",
+  email: "alice@example.com",
+  status: "active",
+});
+
+// Multiple documents
+const batchIds = await users.insert([
+  { name: "Bob", email: "bob@example.com", status: "active" },
+  { name: "Carol", email: "carol@example.com", status: "active" },
+]);
+
+// Upsert (update on conflict)
+await users.insert(
+  { _id: "user-123", name: "Updated" },
+  { conflict: "update" },
+);
+```
+
+For complete CRUD documentation, see [CRUD Operations](./4.crud.md).