@antelopejs/interface-database 0.1.7 → 0.1.8

package/README.md

@@ -1,5 +1,3 @@
-![Database](.github/social-card.png)
-
 # Interface Database
 
 <div align="center">

package/dist/antelope.test.js

@@ -11,7 +11,7 @@ exports.default = (0, config_1.defineConfig)({
             source: {
                 type: "package",
                 package: "@antelopejs/mongodb",
-                version: "1.3.0",
+                version: "1.3.1",
             },
         },
     },

package/dist/staged-query/schema.d.ts

@@ -13,6 +13,17 @@ export interface IndexDefinition {
      * Whether or not this is a multi index
      */
     multi?: boolean;
+    /**
+     * Whether this index must also serve queries that run across all instances
+     * ({@link CROSS_INSTANCE})
+     *
+     * When `true`, the driver also maintains an index usable by cross-instance
+     * queries. Defaults to `false`: the index is optimized for queries scoped to
+     * one instance, and cross-instance queries using it may be slow.
+     *
+     * This flag never changes query results, only performance.
+     */
+    crossInstance?: boolean;
 }
 export type StringFieldType = string | Array<StringFieldType> | {
     [subfield: string]: StringFieldType;
@@ -48,6 +59,10 @@ export interface SchemaDefinition {
 }
 /**
  * Sentinel instance id meaning "operate across all instances of the schema".
+ *
+ * Secondary indexes are optimized for queries scoped to one instance; set
+ * {@link IndexDefinition.crossInstance} on the indexes that cross-instance
+ * queries rely on.
  */
 export declare const CROSS_INSTANCE: unique symbol;
 /**

package/dist/staged-query/schema.js

@@ -6,6 +6,10 @@ const selection_1 = require("./selection");
 const common_1 = require("./common");
 /**
  * Sentinel instance id meaning "operate across all instances of the schema".
+ *
+ * Secondary indexes are optimized for queries scoped to one instance; set
+ * {@link IndexDefinition.crossInstance} on the indexes that cross-instance
+ * queries rely on.
  */
 exports.CROSS_INSTANCE = Symbol("antelopejs:cross-instance");
 /**

package/dist/staged-query/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/staged-query/schema.ts"],"names":[],"mappings":";;;AAAA,mCAAgC;AAChC,2CAAoC;AACpC,qCAAoD;AAwDpD;;GAEG;AACU,QAAA,cAAc,GAAkB,MAAM,CACjD,2BAA2B,CAC5B,CAAC;AAOF;;;;;GAKG;AACH,MAAa,MAGX,SAAQ,qBAAY;IAsBF;IACA;IAtBV,MAAM,CAAU,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;IAE3E;;;;;OAKG;IACI,MAAM,CAAC,GAAG,CACf,EAAU;QAEV,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAsC,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACH,YACkB,EAAU,EACV,UAAsB;QAEtC,KAAK,CAAC,IAAA,mBAAU,EAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAHpB,OAAE,GAAF,EAAE,CAAQ;QACV,eAAU,GAAV,UAAU,CAAY;QAGtC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACI,QAAQ,CAAC,EAAe;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,cAAiB,CAAA,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;OAKG;IACI,cAAc,CAAC,EAAW;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,aAAa,CAAA,EAAE,gBAAgB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;OAIG;IACI,eAAe,CAAC,EAAW;QAChC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,aAAW,CAAA,EAAE,iBAAiB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACI,aAAa;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,aAAe,CAAA,EAAE,eAAe,CAAC,CAAC;IACtD,CAAC;;AAtEH,wBAuEC;AAED;;GAEG;AACH,MAAa,cAAkB,SAAQ,qBAAY;IACjD;;;;;OAKG;IACI,KAAK,CAAqB,EAAM;QACrC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,iBAAY,CAAA,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACnD,CAAC;CACF;AAVD,wCAUC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/staged-query/schema.ts"],"names":[],"mappings":";;;AAAA,mCAAgC;AAChC,2CAAoC;AACpC,qCAAoD;AAoEpD;;;;;;GAMG;AACU,QAAA,cAAc,GAAkB,MAAM,CACjD,2BAA2B,CAC5B,CAAC;AAOF;;;;;GAKG;AACH,MAAa,MAGX,SAAQ,qBAAY;IAsBF;IACA;IAtBV,MAAM,CAAU,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;IAE3E;;;;;OAKG;IACI,MAAM,CAAC,GAAG,CACf,EAAU;QAEV,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAsC,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACH,YACkB,EAAU,EACV,UAAsB;QAEtC,KAAK,CAAC,IAAA,mBAAU,EAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAHpB,OAAE,GAAF,EAAE,CAAQ;QACV,eAAU,GAAV,UAAU,CAAY;QAGtC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACI,QAAQ,CAAC,EAAe;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,cAAiB,CAAA,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;OAKG;IACI,cAAc,CAAC,EAAW;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,aAAa,CAAA,EAAE,gBAAgB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;OAIG;IACI,eAAe,CAAC,EAAW;QAChC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,aAAW,CAAA,EAAE,iBAAiB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACI,aAAa;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,aAAe,CAAA,EAAE,eAAe,CAAC,CAAC;IACtD,CAAC;;AAtEH,wBAuEC;AAED;;GAEG;AACH,MAAa,cAAkB,SAAQ,qBAAY;IACjD;;;;;OAKG;IACI,KAAK,CAAqB,EAAM;QACrC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA,iBAAY,CAAA,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACnD,CAAC;CACF;AAVD,wCAUC"}

package/docs/2.operations/5.indexes.md

@@ -27,6 +27,7 @@ const schema = new Schema("myapp", {
 interface IndexDefinition {
   fields?: string[]; // Fields for compound indexes (omit for single-field)
   multi?: boolean; // Whether this is a multi-valued index
+  crossInstance?: boolean; // Also serve CROSS_INSTANCE queries efficiently
 }
 ```
 
@@ -102,6 +103,29 @@ const schema = new Schema("content", {
 });
 ```
 
+## Cross-Instance Indexes
+
+Indexes are optimized for queries scoped to one instance (`schema.instance(id)`). Queries run with `schema.instance(CROSS_INSTANCE)` can still use them, but may be slow. Set `crossInstance: true` on the indexes that cross-instance queries rely on, and the driver also maintains an index usable by those queries:
+
+```typescript
+const schema = new Schema("billing", {
+  invoices: {
+    fields: { status: "string" },
+    indexes: {
+      status: { crossInstance: true },
+    },
+  },
+});
+
+// Efficient on every instance at once
+await schema
+  .instance(CROSS_INSTANCE)
+  .table("invoices")
+  .getAll("unpaid", "status");
+```
+
+The flag defaults to `false`. It never changes query results, only performance. Each flagged index costs extra storage and write overhead, so only set it where cross-instance queries use the index.
+
 ## Index Design Guidelines
 
 - **Index fields used in `getAll()` and `between()` calls** for best performance.

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

@@ -8,6 +8,7 @@ In AQL, indexes are defined as part of the schema definition rather than created
 interface IndexDefinition {
   fields?: string[]; // Fields for compound indexes
   multi?: boolean; // Multi-valued index
+  crossInstance?: boolean; // Also serve CROSS_INSTANCE queries efficiently
 }
 ```
 
@@ -60,6 +61,16 @@ indexes: {
 }
 ```
 
+### Cross-Instance Indexes
+
+Set `crossInstance: true` when queries run with `CROSS_INSTANCE` use the index. The driver then also maintains an index usable across all instances. Without it, the index is optimized for queries scoped to one instance and cross-instance queries using it may be slow. Results are never affected:
+
+```typescript
+indexes: {
+  status: { crossInstance: true },
+}
+```
+
 ## Use Indexes in Queries
 
 Once defined, indexes are available for `getAll()` and `between()` operations:

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

@@ -34,6 +34,8 @@ 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.
 
+Secondary indexes are optimized for queries scoped to one instance. Set `crossInstance: true` in the `IndexDefinition` of the indexes that cross-instance queries rely on (see [Index Management](../2.operations/5.indexes.md)).
+
 ## Create and Manage Instances
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-database",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "AntelopeJS interface for database-agnostic query operations",
   "keywords": [
     "antelopejs",
@@ -110,8 +110,9 @@
     "knip": "knip"
   },
   "devDependencies": {
-    "@antelopejs/interface-core": ">=0.0.3 <1.0.0",
-    "@antelopejs/tooling-configs": "^0.0.4",
+    "@antelopejs/core": "^1.9.1",
+    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
+    "@antelopejs/tooling-configs": "^0.0.6",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -131,7 +132,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-core": ">=0.0.3 <1.0.0"
+    "@antelopejs/interface-core": ">=0.1.1 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
   "antelopeJs": {

package/skills/database-interface/SKILL.md

@@ -89,7 +89,7 @@ for await (const change of novels.changes()) {
 - **Callbacks receive `ValueProxy`, not values.** Functions passed to `filter`, `map`, `do`, `update(fn)`, `join`, `group` are recorded, then replayed by the backend. Only `ValueProxy` methods (`key`, `eq`, `ne`, `gt/ge/lt/le`, `and/or/not`, `add/sub/mul/div`, string/date/array/object helpers, `ValueProxy.constant`) become part of the query — plain JS (`if`, `===`, `Math.*`, template strings) does not travel. Exception: `group`'s mapper receives a staged `Stream` (the group's documents) as its first parameter and a `ValueProxy` (the index value) second — staged `Stream` methods also travel.
 - **Staged objects are immutable.** Each chained call returns a new object; a prefix like `novels.getAll(true, "available")` can be safely reused for several derived queries.
 - A provider module must be loaded in the project or startup fails with unresolved interface dependencies; queries themselves need no defensive "is the DB ready" checks (calls queue until the provider attaches).
-- `Schema` ids are persistent: changing an id leaves previous data inaccessible. `Schema.get(id)` retrieves a previously constructed schema. `instance()` with no argument is the default instance; pass `CROSS_INSTANCE` to query across all instances.
+- `Schema` ids are persistent: changing an id leaves previous data inaccessible. `Schema.get(id)` retrieves a previously constructed schema. `instance()` with no argument is the default instance; pass `CROSS_INSTANCE` to query across all instances. Indexes are optimized for per-instance queries; set `crossInstance: true` on the indexes that `CROSS_INSTANCE` queries use (performance only, results are unchanged).
 - Field types are string tokens (`"string"`, `"number"`, `"boolean"`, `"date"`, `"string[]"`, nested object literals) or a single io-ts codec at the field root — codecs are not mixed inside string-tree records.
 - Range semantics: `Table.between(index, low, high)` and `ValueProxy.during(left, right)` exclude the upper bound.
 - `insert` accepts one document or an array, with `{ conflict: "update" | "replace" }` as options; it resolves to the inserted ids.