@kedem/okdb 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kedem/okdb",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A fast, type-oriented database — strong consistency and rich indexing at the core, with sync, vector embeddings, full-text search, and AI tooling built in. Designed for the AI era.",
   "license": "SEE LICENSE IN LICENSE",
   "engines": {

package/types/features/views.d.ts

@@ -37,6 +37,75 @@ export type OKDBReducerSpec =
     | { $ref: OKDBRefSpec }
     | OKDBCustomSpec;
 
+/** Allowed granularity values for preset:'time' bucket configs */
+export type OKDBBucketTimeGranularity = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * Bucket configuration for bucketed views.
+ * Use preset:'time' for time-series bucketing (JSON-serializable, works in synced envs).
+ * Use project for custom string-key bucketing (JS only, not usable in synced envs).
+ */
+export type OKDBBucketConfig =
+    | {
+          /** Dot path to the timestamp field on each source document (Unix ms or ISO string). */
+          field: string;
+          /** Time-based bucketing. Currently the only supported preset. */
+          preset: 'time';
+          /** Bucket size. One of: minute, hour, day, week, month, quarter, year. */
+          granularity: OKDBBucketTimeGranularity;
+      }
+    | {
+          /** Dot path to the grouping field on each source document. */
+          field: string;
+          /** Custom projection: maps a field value to a string bucket key. Not usable in synced environments. */
+          project: (value: unknown) => string;
+          /** Arbitrary label used in bucket keys and range queries. */
+          granularity: string;
+      };
+
+/** Options for views.range() */
+export interface OKDBBucketRangeOptions {
+    /** Lower bound. ISO string, epoch ms, or Date for time-preset views; bucket key string for custom-projection views. */
+    from?: string | number | Date | null;
+    /** Upper bound (inclusive). Same shape as from. */
+    to?: string | number | Date | null;
+    /** Must match the view's configured granularity if provided. */
+    granularity?: string;
+    /** When true, includes the bucket containing Date.now(). Default false. */
+    includePartial?: boolean;
+}
+
+/** A single entry in the array returned by views.range() */
+export interface OKDBBucketRangeEntry {
+    /** Canonical string key for this bucket (ISO date string for preset:'time'). */
+    bucketKey: string;
+    granularity: string;
+    /** Per-reducer aggregated values. Scalar → { value: N }; $countBy → { [groupKey]: { value: N } }. */
+    reducers: Record<string, OKDBScalarResult | OKDBCountByResult>;
+    /** Per-$ref sub-view aggregated values. */
+    refs: Record<string, Record<string, OKDBScalarResult | OKDBCountByResult>>;
+}
+
+/** Options for views.listBuckets() */
+export interface OKDBListBucketsOptions {
+    /** Required. Must equal the view's configured granularity. */
+    granularity: string;
+    from?: string | number | Date | null;
+    to?: string | number | Date | null;
+    /** Cap the number of results returned. */
+    limit?: number;
+    /** When true, returns latest-first. Default false (oldest-first). */
+    reverse?: boolean;
+}
+
+/** A single entry in the array returned by views.listBuckets() */
+export interface OKDBBucketEntry {
+    /** Canonical string key for this bucket. */
+    bucketKey: string;
+    /** Number of source documents that fall in this bucket. */
+    count: number;
+}
+
 /** View definition passed to views.create() */
 export interface OKDBViewDefinition {
     /** Source type. Must be registered in this environment. */
@@ -47,6 +116,12 @@ export interface OKDBViewDefinition {
     map?: OKDBViewMap;
     /** Required, non-empty. Maps output field names to reducer specs. */
     reduce: Record<string, OKDBReducerSpec>;
+    /**
+     * Optional. Enables per-bucket aggregation.
+     * Use preset:'time' for time-series bucketing (works over HTTP and in synced envs).
+     * Use project for custom string-key bucketing (JS SDK only, not syncable).
+     */
+    bucket?: OKDBBucketConfig;
 }
 
 /** Shape returned for a scalar reducer output ($count, $sum, $avg, $min, $max) */
@@ -71,6 +146,8 @@ export interface OKDBViewMeta {
     clock: number;
     error: { clock: number; key: string; error: string } | null;
     refs: Record<string, { state: string; clock: number; error: string | null }>;
+    /** Present on bucketed views. Tracks documents whose bucket field could not be parsed. */
+    bucketing?: { unbucketedCount: number };
 }
 
 /** Stored view definition returned by views.getDefinition() (includes name and createdAt) */
@@ -143,6 +220,22 @@ export declare class OKDBViews {
      */
     registerReducer(name: string, reducer: OKDBCustomReducer): void;
 
+    /**
+     * Query per-bucket aggregates for a bucketed view.
+     * Returns a sparse ordered array — only buckets with at least one document are included.
+     * Returns null if the view does not exist.
+     * Throws VIEW_NOT_BUCKETED if the view was not created with a bucket config.
+     */
+    range(name: string, options?: OKDBBucketRangeOptions): OKDBBucketRangeEntry[] | null;
+
+    /**
+     * List populated bucket keys for a bucketed view, with per-bucket document counts.
+     * options.granularity is required and must equal the view's configured granularity.
+     * Throws VIEW_NOT_FOUND if the view does not exist.
+     * Throws VIEW_NOT_BUCKETED if the view was not created with a bucket config.
+     */
+    listBuckets(name: string, options: OKDBListBucketsOptions): OKDBBucketEntry[];
+
     /** @internal Called by OKDB after sync to activate views that arrived from peers. */
     bootSyncedViews(): Promise<void>;
 }