@starkeep/query-orchestrator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Koller, Pedro Pinto, Craig Schroeder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @starkeep/query-orchestrator
+
+Search shared data records via a thin orchestrator over the storage adapter. Today's surface covers type filtering, a `createdAt` date range, and cursor pagination; metadata joins, full-text search, and sync-eligibility filtering are not implemented.
+
+## Installation
+
+```bash
+pnpm add @starkeep/query-orchestrator
+```
+
+## Usage
+
+```ts
+import { createUnifiedIndex } from "@starkeep/query-orchestrator";
+
+const unifiedIndex = createUnifiedIndex({
+  databaseAdapter: myDatabaseAdapter,
+});
+
+// Filter by type and/or date range, paginate with cursor.
+const searchResult = await unifiedIndex.search({
+  types: ["jpg", "png"],
+  dateRange: { start: someHlc, end: laterHlc },
+  limit: 50,
+});
+
+for (const item of searchResult.items) {
+  console.log(item.dataRecord.id);
+}
+
+// Fetch a single record by id.
+const singleItem = await unifiedIndex.getWithMetadata(recordId);
+```
+
+## API
+
+### Factory
+
+| Function | Description |
+|---|---|
+| `createUnifiedIndex(options)` | Creates a `UnifiedIndex` over a `DatabaseAdapter`. |
+| `planQuery(query, databaseAdapter)` | Translates an `IndexQuery` into a planned `Query` for the adapter. |
+
+### `UnifiedIndex`
+
+| Method | Description |
+|---|---|
+| `search(query)` | Query data records with type filter, date range, and pagination. |
+| `getWithMetadata(recordId)` | Retrieve a single data record by id. Returns `{ dataRecord }` — no metadata is joined in today's implementation. |
+
+### Key Types
+
+| Type | Description |
+|---|---|
+| `IndexQuery` | `{ types?, dateRange?, limit?, cursor? }`. |
+| `IndexItem` | `{ dataRecord }`. |
+| `IndexResult` | Paginated search result with `items`, `nextCursor`, and `hasMore`. |
+
+## Testing
+
+```bash
+pnpm --filter @starkeep/query-orchestrator test
+```

package/dist/index.cjs

@@ -0,0 +1,80 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createUnifiedIndex: () => createUnifiedIndex,
+  planQuery: () => planQuery
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/query-planner.ts
+async function planQuery(query, _databaseAdapter) {
+  const filters = [];
+  if (query.types && query.types.length > 0) {
+    filters.push({ field: "type", operator: "in", value: query.types });
+  }
+  if (query.dateRange) {
+    filters.push({
+      field: "createdAt",
+      operator: "gte",
+      value: query.dateRange.start
+    });
+    filters.push({
+      field: "createdAt",
+      operator: "lte",
+      value: query.dateRange.end
+    });
+  }
+  const dataQuery = {
+    filters: filters.length > 0 ? filters : void 0,
+    limit: query.limit,
+    cursor: query.cursor
+  };
+  return { dataQuery };
+}
+
+// src/unified-index.ts
+function createUnifiedIndex(options) {
+  const { databaseAdapter } = options;
+  return {
+    async search(query) {
+      const { dataQuery } = await planQuery(query, databaseAdapter);
+      const dataResult = await databaseAdapter.query(dataQuery);
+      const items = dataResult.records.map((dataRecord) => ({ dataRecord }));
+      return {
+        items,
+        nextCursor: dataResult.nextCursor,
+        hasMore: dataResult.hasMore
+      };
+    },
+    async getWithMetadata(recordId) {
+      const record = await databaseAdapter.get(recordId);
+      if (!record) return null;
+      return { dataRecord: record };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createUnifiedIndex,
+  planQuery
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/query-planner.ts","../src/unified-index.ts"],"sourcesContent":["export type {\n  IndexQuery,\n  IndexItem,\n  IndexResult,\n  UnifiedIndex,\n} from \"./types.js\";\n\nexport { createUnifiedIndex, type CreateUnifiedIndexOptions } from \"./unified-index.js\";\nexport { planQuery, type PlannedQueries } from \"./query-planner.js\";\n","import type { DatabaseAdapter, Query, Filter } from \"@starkeep/storage-adapter\";\nimport type { IndexQuery } from \"./types.js\";\n\nexport interface PlannedQueries {\n  readonly dataQuery: Query;\n}\n\nexport async function planQuery(\n  query: IndexQuery,\n  _databaseAdapter: DatabaseAdapter,\n): Promise<PlannedQueries> {\n  const filters: Filter[] = [];\n\n  if (query.types && query.types.length > 0) {\n    filters.push({ field: \"type\", operator: \"in\", value: query.types });\n  }\n\n  if (query.dateRange) {\n    filters.push({\n      field: \"createdAt\",\n      operator: \"gte\",\n      value: query.dateRange.start,\n    });\n    filters.push({\n      field: \"createdAt\",\n      operator: \"lte\",\n      value: query.dateRange.end,\n    });\n  }\n\n  const dataQuery: Query = {\n    filters: filters.length > 0 ? filters : undefined,\n    limit: query.limit,\n    cursor: query.cursor,\n  };\n\n  return { dataQuery };\n}\n","import type { StarkeepId } from \"@starkeep/protocol-primitives\";\nimport type { DatabaseAdapter } from \"@starkeep/storage-adapter\";\nimport type { UnifiedIndex, IndexQuery, IndexItem, IndexResult } from \"./types.js\";\nimport { planQuery } from \"./query-planner.js\";\n\nexport interface CreateUnifiedIndexOptions {\n  readonly databaseAdapter: DatabaseAdapter;\n}\n\nexport function createUnifiedIndex(options: CreateUnifiedIndexOptions): UnifiedIndex {\n  const { databaseAdapter } = options;\n\n  return {\n    async search(query: IndexQuery): Promise<IndexResult> {\n      const { dataQuery } = await planQuery(query, databaseAdapter);\n      const dataResult = await databaseAdapter.query(dataQuery);\n\n      const items: IndexItem[] = dataResult.records.map((dataRecord) => ({ dataRecord }));\n\n      return {\n        items,\n        nextCursor: dataResult.nextCursor,\n        hasMore: dataResult.hasMore,\n      };\n    },\n\n    async getWithMetadata(recordId: StarkeepId): Promise<IndexItem | null> {\n      const record = await databaseAdapter.get(recordId);\n      if (!record) return null;\n      return { dataRecord: record };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOA,eAAsB,UACpB,OACA,kBACyB;AACzB,QAAM,UAAoB,CAAC;AAE3B,MAAI,MAAM,SAAS,MAAM,MAAM,SAAS,GAAG;AACzC,YAAQ,KAAK,EAAE,OAAO,QAAQ,UAAU,MAAM,OAAO,MAAM,MAAM,CAAC;AAAA,EACpE;AAEA,MAAI,MAAM,WAAW;AACnB,YAAQ,KAAK;AAAA,MACX,OAAO;AAAA,MACP,UAAU;AAAA,MACV,OAAO,MAAM,UAAU;AAAA,IACzB,CAAC;AACD,YAAQ,KAAK;AAAA,MACX,OAAO;AAAA,MACP,UAAU;AAAA,MACV,OAAO,MAAM,UAAU;AAAA,IACzB,CAAC;AAAA,EACH;AAEA,QAAM,YAAmB;AAAA,IACvB,SAAS,QAAQ,SAAS,IAAI,UAAU;AAAA,IACxC,OAAO,MAAM;AAAA,IACb,QAAQ,MAAM;AAAA,EAChB;AAEA,SAAO,EAAE,UAAU;AACrB;;;AC5BO,SAAS,mBAAmB,SAAkD;AACnF,QAAM,EAAE,gBAAgB,IAAI;AAE5B,SAAO;AAAA,IACL,MAAM,OAAO,OAAyC;AACpD,YAAM,EAAE,UAAU,IAAI,MAAM,UAAU,OAAO,eAAe;AAC5D,YAAM,aAAa,MAAM,gBAAgB,MAAM,SAAS;AAExD,YAAM,QAAqB,WAAW,QAAQ,IAAI,CAAC,gBAAgB,EAAE,WAAW,EAAE;AAElF,aAAO;AAAA,QACL;AAAA,QACA,YAAY,WAAW;AAAA,QACvB,SAAS,WAAW;AAAA,MACtB;AAAA,IACF;AAAA,IAEA,MAAM,gBAAgB,UAAiD;AACrE,YAAM,SAAS,MAAM,gBAAgB,IAAI,QAAQ;AACjD,UAAI,CAAC,OAAQ,QAAO;AACpB,aAAO,EAAE,YAAY,OAAO;AAAA,IAC9B;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,36 @@
+import { DataRecord, HLCTimestamp, StarkeepId } from '@starkeep/protocol-primitives';
+import { DatabaseAdapter, Query } from '@starkeep/storage-adapter';
+
+interface IndexQuery {
+    readonly types?: string[];
+    readonly dateRange?: {
+        readonly start: HLCTimestamp;
+        readonly end: HLCTimestamp;
+    };
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+interface IndexItem {
+    readonly dataRecord: DataRecord;
+}
+interface IndexResult {
+    readonly items: IndexItem[];
+    readonly nextCursor: string | null;
+    readonly hasMore: boolean;
+}
+interface UnifiedIndex {
+    search(query: IndexQuery): Promise<IndexResult>;
+    getWithMetadata(recordId: StarkeepId): Promise<IndexItem | null>;
+}
+
+interface CreateUnifiedIndexOptions {
+    readonly databaseAdapter: DatabaseAdapter;
+}
+declare function createUnifiedIndex(options: CreateUnifiedIndexOptions): UnifiedIndex;
+
+interface PlannedQueries {
+    readonly dataQuery: Query;
+}
+declare function planQuery(query: IndexQuery, _databaseAdapter: DatabaseAdapter): Promise<PlannedQueries>;
+
+export { type CreateUnifiedIndexOptions, type IndexItem, type IndexQuery, type IndexResult, type PlannedQueries, type UnifiedIndex, createUnifiedIndex, planQuery };

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { DataRecord, HLCTimestamp, StarkeepId } from '@starkeep/protocol-primitives';
+import { DatabaseAdapter, Query } from '@starkeep/storage-adapter';
+
+interface IndexQuery {
+    readonly types?: string[];
+    readonly dateRange?: {
+        readonly start: HLCTimestamp;
+        readonly end: HLCTimestamp;
+    };
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+interface IndexItem {
+    readonly dataRecord: DataRecord;
+}
+interface IndexResult {
+    readonly items: IndexItem[];
+    readonly nextCursor: string | null;
+    readonly hasMore: boolean;
+}
+interface UnifiedIndex {
+    search(query: IndexQuery): Promise<IndexResult>;
+    getWithMetadata(recordId: StarkeepId): Promise<IndexItem | null>;
+}
+
+interface CreateUnifiedIndexOptions {
+    readonly databaseAdapter: DatabaseAdapter;
+}
+declare function createUnifiedIndex(options: CreateUnifiedIndexOptions): UnifiedIndex;
+
+interface PlannedQueries {
+    readonly dataQuery: Query;
+}
+declare function planQuery(query: IndexQuery, _databaseAdapter: DatabaseAdapter): Promise<PlannedQueries>;
+
+export { type CreateUnifiedIndexOptions, type IndexItem, type IndexQuery, type IndexResult, type PlannedQueries, type UnifiedIndex, createUnifiedIndex, planQuery };

package/dist/index.js

@@ -0,0 +1,52 @@
+// src/query-planner.ts
+async function planQuery(query, _databaseAdapter) {
+  const filters = [];
+  if (query.types && query.types.length > 0) {
+    filters.push({ field: "type", operator: "in", value: query.types });
+  }
+  if (query.dateRange) {
+    filters.push({
+      field: "createdAt",
+      operator: "gte",
+      value: query.dateRange.start
+    });
+    filters.push({
+      field: "createdAt",
+      operator: "lte",
+      value: query.dateRange.end
+    });
+  }
+  const dataQuery = {
+    filters: filters.length > 0 ? filters : void 0,
+    limit: query.limit,
+    cursor: query.cursor
+  };
+  return { dataQuery };
+}
+
+// src/unified-index.ts
+function createUnifiedIndex(options) {
+  const { databaseAdapter } = options;
+  return {
+    async search(query) {
+      const { dataQuery } = await planQuery(query, databaseAdapter);
+      const dataResult = await databaseAdapter.query(dataQuery);
+      const items = dataResult.records.map((dataRecord) => ({ dataRecord }));
+      return {
+        items,
+        nextCursor: dataResult.nextCursor,
+        hasMore: dataResult.hasMore
+      };
+    },
+    async getWithMetadata(recordId) {
+      const record = await databaseAdapter.get(recordId);
+      if (!record) return null;
+      return { dataRecord: record };
+    }
+  };
+}
+export {
+  createUnifiedIndex,
+  planQuery
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/query-planner.ts","../src/unified-index.ts"],"sourcesContent":["import type { DatabaseAdapter, Query, Filter } from \"@starkeep/storage-adapter\";\nimport type { IndexQuery } from \"./types.js\";\n\nexport interface PlannedQueries {\n  readonly dataQuery: Query;\n}\n\nexport async function planQuery(\n  query: IndexQuery,\n  _databaseAdapter: DatabaseAdapter,\n): Promise<PlannedQueries> {\n  const filters: Filter[] = [];\n\n  if (query.types && query.types.length > 0) {\n    filters.push({ field: \"type\", operator: \"in\", value: query.types });\n  }\n\n  if (query.dateRange) {\n    filters.push({\n      field: \"createdAt\",\n      operator: \"gte\",\n      value: query.dateRange.start,\n    });\n    filters.push({\n      field: \"createdAt\",\n      operator: \"lte\",\n      value: query.dateRange.end,\n    });\n  }\n\n  const dataQuery: Query = {\n    filters: filters.length > 0 ? filters : undefined,\n    limit: query.limit,\n    cursor: query.cursor,\n  };\n\n  return { dataQuery };\n}\n","import type { StarkeepId } from \"@starkeep/protocol-primitives\";\nimport type { DatabaseAdapter } from \"@starkeep/storage-adapter\";\nimport type { UnifiedIndex, IndexQuery, IndexItem, IndexResult } from \"./types.js\";\nimport { planQuery } from \"./query-planner.js\";\n\nexport interface CreateUnifiedIndexOptions {\n  readonly databaseAdapter: DatabaseAdapter;\n}\n\nexport function createUnifiedIndex(options: CreateUnifiedIndexOptions): UnifiedIndex {\n  const { databaseAdapter } = options;\n\n  return {\n    async search(query: IndexQuery): Promise<IndexResult> {\n      const { dataQuery } = await planQuery(query, databaseAdapter);\n      const dataResult = await databaseAdapter.query(dataQuery);\n\n      const items: IndexItem[] = dataResult.records.map((dataRecord) => ({ dataRecord }));\n\n      return {\n        items,\n        nextCursor: dataResult.nextCursor,\n        hasMore: dataResult.hasMore,\n      };\n    },\n\n    async getWithMetadata(recordId: StarkeepId): Promise<IndexItem | null> {\n      const record = await databaseAdapter.get(recordId);\n      if (!record) return null;\n      return { dataRecord: record };\n    },\n  };\n}\n"],"mappings":";AAOA,eAAsB,UACpB,OACA,kBACyB;AACzB,QAAM,UAAoB,CAAC;AAE3B,MAAI,MAAM,SAAS,MAAM,MAAM,SAAS,GAAG;AACzC,YAAQ,KAAK,EAAE,OAAO,QAAQ,UAAU,MAAM,OAAO,MAAM,MAAM,CAAC;AAAA,EACpE;AAEA,MAAI,MAAM,WAAW;AACnB,YAAQ,KAAK;AAAA,MACX,OAAO;AAAA,MACP,UAAU;AAAA,MACV,OAAO,MAAM,UAAU;AAAA,IACzB,CAAC;AACD,YAAQ,KAAK;AAAA,MACX,OAAO;AAAA,MACP,UAAU;AAAA,MACV,OAAO,MAAM,UAAU;AAAA,IACzB,CAAC;AAAA,EACH;AAEA,QAAM,YAAmB;AAAA,IACvB,SAAS,QAAQ,SAAS,IAAI,UAAU;AAAA,IACxC,OAAO,MAAM;AAAA,IACb,QAAQ,MAAM;AAAA,EAChB;AAEA,SAAO,EAAE,UAAU;AACrB;;;AC5BO,SAAS,mBAAmB,SAAkD;AACnF,QAAM,EAAE,gBAAgB,IAAI;AAE5B,SAAO;AAAA,IACL,MAAM,OAAO,OAAyC;AACpD,YAAM,EAAE,UAAU,IAAI,MAAM,UAAU,OAAO,eAAe;AAC5D,YAAM,aAAa,MAAM,gBAAgB,MAAM,SAAS;AAExD,YAAM,QAAqB,WAAW,QAAQ,IAAI,CAAC,gBAAgB,EAAE,WAAW,EAAE;AAElF,aAAO;AAAA,QACL;AAAA,QACA,YAAY,WAAW;AAAA,QACvB,SAAS,WAAW;AAAA,MACtB;AAAA,IACF;AAAA,IAEA,MAAM,gBAAgB,UAAiD;AACrE,YAAM,SAAS,MAAM,gBAAgB,IAAI,QAAQ;AACjD,UAAI,CAAC,OAAQ,QAAO;AACpB,aAAO,EAAE,YAAY,OAAO;AAAA,IAC9B;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@starkeep/query-orchestrator",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starkeep-dev/starkeep-core.git",
+    "directory": "packages/query-orchestrator"
+  },
+  "homepage": "https://github.com/starkeep-dev/starkeep-core/tree/main/packages/query-orchestrator",
+  "dependencies": {
+    "@starkeep/storage-adapter": "0.1.0",
+    "@starkeep/protocol-primitives": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/"
+  }
+}