@antelopejs/interface-database 0.1.3 → 0.1.5

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,82 @@
+# 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,51 @@
+# 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
+  - [Atomic Mutations](./2.operations/8.atomic_mutations.md) - Conditional single-record mutations and outcomes
+
+- [**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,28 +1,61 @@
 {
   "name": "@antelopejs/interface-database",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "AntelopeJS interface for database-agnostic query operations",
   "keywords": [
     "antelopejs",
-    "interface",
-    "database"
+    "database",
+    "interface"
   ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/interface-database.git"
   },
-  "license": "Apache-2.0",
-  "packageManager": "pnpm@10.6.5",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "atomic": [
+        "dist/atomic.d.ts"
+      ],
+      "common": [
+        "dist/common.d.ts"
+      ],
+      "datum": [
+        "dist/datum.d.ts"
+      ],
+      "query": [
+        "dist/query.d.ts"
+      ],
+      "schema": [
+        "dist/schema.d.ts"
+      ],
+      "selection": [
+        "dist/selection.d.ts"
+      ],
+      "stream": [
+        "dist/stream.d.ts"
+      ],
+      "valueproxy": [
+        "dist/valueproxy.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./atomic": {
+      "types": "./dist/atomic.d.ts",
+      "default": "./dist/atomic.js"
+    },
     "./common": {
       "types": "./dist/common.d.ts",
       "default": "./dist/common.js"
@@ -53,26 +86,37 @@
     },
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "rimraf dist && tsc",
-    "format": "biome format --write .",
-    "lint:fix": "biome check --write .",
-    "lint": "biome check .",
+    "format": "oxfmt .",
+    "lint:fix": "oxlint --fix",
+    "lint": "oxlint",
     "prepack": "pnpm run build",
     "release": "pnpm run lint && pnpm run prepack && release-it",
-    "test": "pnpm run build && ajs module test ."
+    "test": "pnpm run build && ajs module test .",
+    "format:check": "oxfmt --check .",
+    "knip": "knip"
   },
   "devDependencies": {
     "@antelopejs/interface-core": ">=0.0.3 <1.0.0",
-    "@biomejs/biome": "2.3.2",
+    "@antelopejs/tooling-configs": "^0.0.4",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
     "@types/semver": "^7.7.1",
     "chai": "^4.5.0",
+    "eslint-plugin-perfectionist": "^5.11.0",
     "fp-ts": "^2.16.0",
     "io-ts": "^2.2.0",
+    "knip": "^6.34.0",
     "mongodb-memory-server-core": "^11.0.1",
+    "oxfmt": "^0.66.0",
+    "oxlint": "1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
@@ -81,35 +125,11 @@
   "peerDependencies": {
     "@antelopejs/interface-core": ">=0.0.3 <1.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "typesVersions": {
-    "*": {
-      "common": [
-        "dist/common.d.ts"
-      ],
-      "datum": [
-        "dist/datum.d.ts"
-      ],
-      "query": [
-        "dist/query.d.ts"
-      ],
-      "schema": [
-        "dist/schema.d.ts"
-      ],
-      "selection": [
-        "dist/selection.d.ts"
-      ],
-      "stream": [
-        "dist/stream.d.ts"
-      ],
-      "valueproxy": [
-        "dist/valueproxy.d.ts"
-      ]
-    }
-  },
+  "packageManager": "pnpm@10.6.5",
   "antelopeJs": {
-    "test": "src/antelope.test.ts"
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   }
 }