@f0rbit/corpus 0.1.7 → 0.1.9

package/dist/observations/client.d.ts

@@ -2,8 +2,8 @@
  * @module ObservationsClient
  * @description Centralized business logic for observations, built on storage adapters.
  */
-import type { MetadataClient, ObservationsClient } from '../types';
-import type { ObservationsStorage } from './storage';
+import type { MetadataClient, ObservationsClient } from "../types";
+import type { ObservationsStorage } from "./storage";
 /**
  * Creates an ObservationsClient from a storage adapter.
  * All business logic (validation, staleness, etc.) is centralized here.

package/dist/observations/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../observations/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAuB,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAEvF,OAAO,KAAK,EAAE,mBAAmB,EAAoB,MAAM,WAAW,CAAA;AAuBtE;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,cAAc,GACvB,kBAAkB,CAqGpB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../observations/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAuB,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAExF,OAAO,KAAK,EAAE,mBAAmB,EAAoB,MAAM,WAAW,CAAC;AA6BvE;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,GAAG,kBAAkB,CAiGrH"}

package/dist/observations/client.js

@@ -2,9 +2,16 @@
  * @module ObservationsClient
  * @description Centralized business logic for observations, built on storage adapters.
  */
-import { row_to_observation, row_to_meta, create_observation_row } from './storage';
-import { generate_observation_id } from './utils';
-import { ok, err } from '../types';
+import { row_to_observation, row_to_meta, create_observation_row } from "./storage";
+import { generate_observation_id } from "./utils";
+import { ok, err } from "../types";
+async function apply_version_filter(filter, store_id, version) {
+    if (typeof filter === "function")
+        return filter(store_id, version);
+    if (filter instanceof Set)
+        return filter.has(version);
+    return filter.includes(version);
+}
 /**
  * Convert client query opts to storage query opts.
  * Handles Date -> ISO string conversion.
@@ -19,7 +26,7 @@ function to_storage_opts(opts) {
         created_before: opts.created_before?.toISOString(),
         observed_after: opts.after?.toISOString(),
         observed_before: opts.before?.toISOString(),
-        limit: opts.limit
+        limit: opts.limit,
     };
 }
 /**
@@ -36,16 +43,16 @@ export function create_observations_client(storage, metadata) {
             const validation = type.schema.safeParse(opts.content);
             if (!validation.success) {
                 return err({
-                    kind: 'validation_error',
+                    kind: "validation_error",
                     cause: validation.error,
-                    message: validation.error.message
+                    message: validation.error.message,
                 });
             }
             const id = generate_observation_id();
             const row = create_observation_row(id, type.name, opts.source, validation.data, {
                 confidence: opts.confidence,
                 observed_at: opts.observed_at,
-                derived_from: opts.derived_from
+                derived_from: opts.derived_from,
             });
             const result = await storage.put_row(row);
             if (!result.ok)
@@ -58,7 +65,7 @@ export function create_observations_client(storage, metadata) {
                 ...(opts.confidence !== undefined && { confidence: opts.confidence }),
                 ...(opts.observed_at && { observed_at: opts.observed_at }),
                 created_at: new Date(row.created_at),
-                ...(opts.derived_from && { derived_from: opts.derived_from })
+                ...(opts.derived_from && { derived_from: opts.derived_from }),
             };
             return ok(observation);
         },
@@ -67,16 +74,16 @@ export function create_observations_client(storage, metadata) {
             if (!result.ok)
                 return result;
             if (!result.value) {
-                return err({ kind: 'observation_not_found', id });
+                return err({ kind: "observation_not_found", id });
             }
             return ok(row_to_observation(result.value));
         },
         async *query(opts = {}) {
             const storageOpts = to_storage_opts(opts);
             for await (const row of storage.query_rows(storageOpts)) {
-                if (!opts.include_stale) {
-                    const latest = await get_latest_version(row.source_store_id);
-                    if (latest && row.source_version !== latest)
+                if (opts.version_filter !== undefined) {
+                    const included = await apply_version_filter(opts.version_filter, row.source_store_id, row.source_version);
+                    if (!included)
                         continue;
                 }
                 yield row_to_observation(row);
@@ -85,9 +92,9 @@ export function create_observations_client(storage, metadata) {
         async *query_meta(opts = {}) {
             const storageOpts = to_storage_opts(opts);
             for await (const row of storage.query_rows(storageOpts)) {
-                if (!opts.include_stale) {
-                    const latest = await get_latest_version(row.source_store_id);
-                    if (latest && row.source_version !== latest)
+                if (opts.version_filter !== undefined) {
+                    const included = await apply_version_filter(opts.version_filter, row.source_store_id, row.source_version);
+                    if (!included)
                         continue;
                 }
                 yield row_to_meta(row);
@@ -98,7 +105,7 @@ export function create_observations_client(storage, metadata) {
             if (!result.ok)
                 return result;
             if (!result.value) {
-                return err({ kind: 'observation_not_found', id });
+                return err({ kind: "observation_not_found", id });
             }
             return ok(undefined);
         },
@@ -110,6 +117,6 @@ export function create_observations_client(storage, metadata) {
             if (!latest)
                 return false;
             return pointer.version !== latest;
-        }
+        },
     };
 }

package/dist/observations/types.d.ts

@@ -2,7 +2,7 @@
  * @module ObservationTypes
  * @description Type definitions for the observations feature.
  */
-import type { ZodType } from 'zod';
+import type { ZodType } from "zod";
 /**
  * Universal address to versioned content within a corpus store.
  *
@@ -105,7 +105,46 @@ export type Observation<T = unknown> = {
  * @category Types
  * @group Observation Types
  */
-export type ObservationMeta = Omit<Observation<never>, 'content'>;
+export type ObservationMeta = Omit<Observation<never>, "content">;
+/**
+ * Options for creating a new observation.
+ *
+ * @category Types
+ * @group Observation Types
+ */
+export type ObservationPutOpts<T> = {
+    source: SnapshotPointer;
+    content: T;
+    confidence?: number;
+    observed_at?: Date;
+    derived_from?: SnapshotPointer[];
+};
+/**
+ * Filter for version-based observation filtering.
+ * - Set<string> or string[]: Include if version is in the collection
+ * - Function: Called with (store_id, version), return true to include
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * // Filter to specific versions
+ * const filter: VersionFilter = new Set(['v1', 'v2', 'v3'])
+ *
+ * // Or use an array
+ * const filter: VersionFilter = ['v1', 'v2', 'v3']
+ *
+ * // Or use a function for dynamic filtering
+ * const filter: VersionFilter = async (store_id, version) => {
+ *   const published = await db.query.published_reports.findFirst({
+ *     where: eq(published_reports.version, version)
+ *   });
+ *   return published !== null;
+ * };
+ * ```
+ */
+export type VersionFilter = Set<string> | string[] | ((store_id: string, version: string) => boolean | Promise<boolean>);
 /**
  * Query options for filtering observations.
  *
@@ -122,11 +161,10 @@ export type ObservationMeta = Omit<Observation<never>, 'content'>;
  *   limit: 100
  * }
  *
- * // Find all observations for a specific version
+ * // Filter to only published versions
  * const versionOpts: ObservationQueryOpts = {
  *   source_store: 'hansard',
- *   source_version: 'AZJx4vM',
- *   include_stale: true
+ *   version_filter: new Set(['v1', 'v2'])
  * }
  * ```
  */
@@ -139,34 +177,32 @@ export type ObservationQueryOpts = {
     before?: Date;
     created_after?: Date;
     created_before?: Date;
-    include_stale?: boolean;
     limit?: number;
     cursor?: string;
+    /**
+     * Filter observations by version.
+     * When provided, only observations whose source version passes the filter are included.
+     *
+     * - Set<string> or string[]: Include if version is in the collection
+     * - Function: Called with (store_id, version), return true to include
+     */
+    version_filter?: VersionFilter;
 };
 /**
- * Options for creating a new observation.
+ * Utility type to extract the content type from an ObservationTypeDef.
  *
  * @category Types
  * @group Observation Types
  *
  * @example
  * ```ts
- * const opts: ObservationPutOpts<EntityMention> = {
- *   source: { store_id: 'hansard', version: 'AZJx4vM', path: '$.speeches[0]' },
- *   content: { entity: 'Climate Change', entity_type: 'topic' },
- *   confidence: 0.95,
- *   observed_at: new Date(),
- *   derived_from: [{ store_id: 'raw_text', version: 'xyz789' }]
- * }
+ * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
+ *
+ * type EntityMention = InferObservationContent<typeof entity_mention>
+ * // => { entity: string; entity_type: 'person' | 'organization' | ... }
  * ```
  */
-export type ObservationPutOpts<T> = {
-    source: SnapshotPointer;
-    content: T;
-    confidence?: number;
-    observed_at?: Date;
-    derived_from?: SnapshotPointer[];
-};
+export type InferObservationContent<T> = T extends ObservationTypeDef<infer C> ? C : never;
 /**
  * Defines a typed observation schema.
  *
@@ -201,19 +237,4 @@ export type ObservationPutOpts<T> = {
  * ```
  */
 export declare function define_observation_type<T>(name: string, schema: ZodType<T>): ObservationTypeDef<T>;
-/**
- * Utility type to extract the content type from an ObservationTypeDef.
- *
- * @category Types
- * @group Observation Types
- *
- * @example
- * ```ts
- * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
- *
- * type EntityMention = InferObservationContent<typeof entity_mention>
- * // => { entity: string; entity_type: 'person' | 'organization' | ... }
- * ```
- */
-export type InferObservationContent<T> = T extends ObservationTypeDef<infer C> ? C : never;
 //# sourceMappingURL=types.d.ts.map

package/dist/observations/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../observations/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,MAAM,CAAA;QACb,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;CACF,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,UAAU,EAAE,IAAI,CAAA;IAChB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,cAAc,CAAC,EAAE,IAAI,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../observations/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,UAAU,EAAE,IAAI,CAAC;IACjB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAEzH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAElG"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@f0rbit/corpus",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"description": "A functional snapshotting library for TypeScript with versioned data storage, lineage tracking, and multiple backend support",
 	"module": "dist/index.js",
 	"main": "dist/index.js",