@antelopejs/interface-database 0.1.4 → 0.1.6

package/docs/2.operations/8.atomic_mutations.md

@@ -0,0 +1,71 @@
+# Atomic single-record mutations
+
+`Table.atomicMutation(id, request)` checks one immutable, instance-scoped record identity and one condition inside the database mutation. It returns `Query<AtomicMutationOutcome>`. It does not provide multi-record transactions, a lock service, receipts, or external-effect coordination.
+
+Generic `filter(...).update(...)` and `filter(...).delete()` do **not** promise this guarantee. Use a direct `schema.instance(instanceId).table(tableId)` with one literal string identity. The default instance is supported; `CROSS_INSTANCE`, filtered selections, expression keys, cursors, and upserts are not.
+
+## Compare a revision
+
+Public types are exported from `@antelopejs/interface-database` and `@antelopejs/interface-database/atomic`. An update checks the current revision and installs the patch and next revision together. A delete checks the revision inside the deletion.
+
+```ts
+const outcome = await table.atomicMutation(recordId, {
+  type: "update",
+  revisionField: "revision",
+  expectedRevision: observed.revision,
+  nextRevision: freshRevision,
+  patch: { title: "Updated title" },
+});
+
+const deletion = await table.atomicMutation(recordId, {
+  type: "delete",
+  revisionField: "revision",
+  expectedRevision: observed.revision,
+});
+```
+
+Revision tokens are nonempty strings. Each update must install a changed token that the caller guarantees has never been used for that identity. All writers of protected state must advance the revision; otherwise a successful comparison does not prove that the observed state is current. Initialize new records with fresh revisions and use a new identity for each incarnation, including recreation after deletion.
+
+`expectedRevision: { kind: "missing" }` matches an **absent revision field on an existing record**. It does not match a stored `null`, an empty string, or a missing record. An update can use this expectation to bootstrap legacy data atomically; a delete can use it when the domain permits deleting an unversioned record. A backend that cannot distinguish absence from null must reject this expectation rather than weaken it. In PostgreSQL, declared SQL columns collapse this distinction; an overflow JSON field can preserve it. Review mapper serialization before choosing revision storage.
+
+## Patch semantics
+
+The patch replaces each supplied top-level field. Nested objects and arrays replace their entire previous values; they do not merge recursively. Unspecified fields remain unchanged, and `null` stores null rather than removing the field. There is no unset operation.
+
+Patches contain only constant strings, booleans, finite numbers, null, valid Dates, dense arrays, and plain objects. Undefined, functions, query proxies, cycles, and operator/path field names are rejected. The patch cannot contain `id`, `_id`, the revision field, or adapter-owned scope fields. Adapters must preserve their normal Date storage representation without interpreting objects that resemble query stages as executable expressions.
+
+## Delete by one observed scalar
+
+`deleteIfEqual` provides a narrower condition for domains where one field equality is sufficient, such as deletion of an expired record whose observed timestamp remains unchanged.
+
+```ts
+const outcome = await table.atomicMutation(recordId, {
+  type: "deleteIfEqual",
+  field: "lastSeenAt",
+  expectedValue: observed.lastSeenAt,
+});
+```
+
+`expectedValue` accepts a string, finite number, boolean, or valid Date. Equality is exact and type-sensitive, with Dates compared by their stored instant; scalar equality must not match an array containing that scalar. Missing fields never match. Null, objects, arrays, identity fields, and scope fields are not supported.
+
+This variant does not check or advance a revision and does not prevent ABA: a value can change and later return to its observed value. The domain must prove that equality alone authorizes deletion. It is not a substitute for revision checks on state transitions.
+
+## Handle all outcomes
+
+| Outcome       | Meaning                                                                                                              |
+| ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `applied`     | The adapter received definitive acknowledgement that the one mutation applied.                                       |
+| `not-applied` | The adapter received definitive acknowledgement that the target was missing or its scope or condition did not match. |
+| `unknown`     | The adapter cannot determine whether the mutation applied, including acknowledgement loss.                           |
+
+Definitive validation and unsupported-operation errors throw. Neither an exception nor `unknown` means mismatch. The interface rejects invalid adapter results, including `undefined`, zero, and generic modified counts, with `AtomicMutationUnsupportedError`; adapters must reject unsupported stages explicitly. There is no fallback to generic filtered writes and no separate capability probe. Use an adapter whose implementation has been verified before relying on this API.
+
+The interface and adapter must not automatically retry an uncertain mutation. Do not repeat external effects or infer failure from a later mismatch. Domain-specific recovery can reconcile durable evidence and receipts, but a fresh read alone cannot prove whether an earlier operation or external effect occurred. Any deliberate replay requires a domain proof and does not turn `not-applied` into evidence about the original attempt.
+
+## Adapter contract
+
+The canonical terminal stage is `{ stage: "atomicMutation", options: undefined, args: [id, request] }`, immediately after `schema`, `instance`, and `table`. `AtomicMutation<T>` is the union of `AtomicUpdate<T>`, `AtomicDelete<T>`, and `AtomicDeleteIfEqual<T>`.
+
+Adapters can reuse `ValidateAtomicMutation(id, request, protectedFields)` and `ValidateAtomicMutationTable(prefixStages)`. They must additionally validate the terminal envelope and schema-specific restrictions. Scope, immutable identity, and the revision or equality condition must participate in the target-local native mutation, not only an earlier selection or identity subquery. Backend tests must prove contention, scope isolation, missing/null distinction, top-level replacement, and acknowledgement-loss behavior.
+
+This API remains unpublished during adapter and consumer verification. Package metadata alone does not establish capability; do not infer support from the unchanged development package version.

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

@@ -6,8 +6,8 @@ In AQL, indexes are defined as part of the schema definition rather than created
 
 ```typescript
 interface IndexDefinition {
-  fields?: string[];  // Fields for compound indexes
-  multi?: boolean;    // Multi-valued index
+  fields?: string[]; // Fields for compound indexes
+  multi?: boolean; // Multi-valued index
 }
 ```
 
@@ -22,8 +22,8 @@ const schema = new Schema("myapp", {
   users: {
     fields: { name: "string", email: "string", role: "string" },
     indexes: {
-      email: {},                              // Simple index (field name = index name)
-      role: {},                               // Simple index
+      email: {}, // Simple index (field name = index name)
+      role: {}, // Simple index
       name_role: { fields: ["name", "role"] }, // Compound index
     },
   },
@@ -72,7 +72,11 @@ const users = db.table("users");
 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());
+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

@@ -17,10 +17,10 @@ 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
+  | 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
+  | 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.

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

@@ -14,11 +14,11 @@ interface Changes<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. |
+| 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
 

package/docs/index.md

@@ -25,6 +25,7 @@ The Database interface provides AQL (Antelope Query Language), a database-agnost
   - [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

package/package.json

@@ -1,30 +1,61 @@
 {
   "name": "@antelopejs/interface-database",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
     "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"
@@ -55,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",
@@ -83,34 +125,7 @@
   "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",
     "skills": [

package/skills/database-interface/SKILL.md

@@ -13,10 +13,34 @@ AQL is a lazy, chainable query builder. Every class here (`Schema`, `Table`, `Se
 
 ```ts
 // Root re-exports everything most consumers need:
-import { Schema, SchemaInstance, SchemaDefinition, Table, Selection, SingleSelection, Stream, Datum, Query, ValueProxy, ValueProxyOrValue, InstanceId, CROSS_INSTANCE } from "@antelopejs/interface-database";
+import {
+  Schema,
+  SchemaInstance,
+  SchemaDefinition,
+  Table,
+  Selection,
+  SingleSelection,
+  Stream,
+  Datum,
+  Query,
+  ValueProxy,
+  ValueProxyOrValue,
+  InstanceId,
+  CROSS_INSTANCE,
+} from "@antelopejs/interface-database";
 // Types only available via subpath (not re-exported at root):
-import { TableDefinition, IndexDefinition, FieldType } from "@antelopejs/interface-database/schema";
-import { Changes, DeepPartial, InsertOptions, Value, ExtractType } from "@antelopejs/interface-database/common";
+import {
+  TableDefinition,
+  IndexDefinition,
+  FieldType,
+} from "@antelopejs/interface-database/schema";
+import {
+  Changes,
+  DeepPartial,
+  InsertOptions,
+  Value,
+  ExtractType,
+} from "@antelopejs/interface-database/common";
 // Each root symbol is also importable from its own subpath (/schema, /selection, /stream, /datum, /query, /valueproxy) — equivalent alternatives, do not combine with the root import for the same symbol.
 ```
 
@@ -27,7 +51,12 @@ Add `@antelopejs/interface-database` to the module's `dependencies`; `@antelopej
 ```ts
 import { Schema } from "@antelopejs/interface-database";
 
-interface Novel { _id?: string; title: string; pageCount: number; available: boolean; }
+interface Novel {
+  _id?: string;
+  title: string;
+  pageCount: number;
+  available: boolean;
+}
 
 // Registers the schema with the provider. The generic maps table names to row types.
 const schema = new Schema<{ novels: Novel }>("library", {
@@ -39,12 +68,17 @@ const schema = new Schema<{ novels: Novel }>("library", {
 
 const novels = schema.instance().table("novels"); // default instance
 
-const ids = await novels.insert({ title: "The Glass Meridian", pageCount: 412, available: true }); // string[] of inserted ids
+const ids = await novels.insert({
+  title: "The Glass Meridian",
+  pageCount: 412,
+  available: true,
+}); // string[] of inserted ids
 const longNovels = await novels
   .filter((n) => n.key("pageCount").ge(300).and(n.key("available")))
-  .orderBy("pageCount", "desc");                    // await executes: Novel[]
+  .orderBy("pageCount", "desc"); // await executes: Novel[]
 await novels.get(ids[0]).update({ available: false }); // number of modified docs
-for await (const change of novels.changes()) {    // change feed via async iteration
+for await (const change of novels.changes()) {
+  // change feed via async iteration
   console.log(change.changeType, change.newValue); // "added" | "removed" | "modified"
 }
 ```