@kedem/okdb 1.0.4 → 1.1.0

package/types/features/views.d.ts

@@ -1,16 +1,148 @@
+/** Sift-style (MongoDB-compatible) filter object */
+export type OKDBFilter = Record<string, unknown>;
+
+/** Map operator specs */
+export type OKDBMapRefSpec = { $ref: [type: string, fkField: string, targetField: string] };
+export type OKDBMapConcatSpec = { $concat: string[] };
+export type OKDBMapCoalesceSpec = { $coalesce: string[] };
+export type OKDBMapFieldSpec = string | OKDBMapRefSpec | OKDBMapConcatSpec | OKDBMapCoalesceSpec;
+
+/** Declarative per-doc transform merged onto source docs before reducers run */
+export type OKDBViewMap = Record<string, OKDBMapFieldSpec>;
+
+/** Built-in reducer specs */
+export type OKDBCountSpec    = { $count: true;              items?: boolean };
+export type OKDBSumSpec      = { $sum: string;              items?: boolean };
+export type OKDBAvgSpec      = { $avg: string;              items?: boolean };
+export type OKDBMinSpec      = { $min: string;              items?: boolean };
+export type OKDBMaxSpec      = { $max: string;              items?: boolean };
+export type OKDBCountBySpec  = { $countBy: string;          items?: boolean };
+export type OKDBCustomSpec   = { [reducer: string]: unknown; items?: boolean };
+
+/** $ref sub-view aggregation */
+export interface OKDBRefSpec {
+    type:    string;
+    key:     string;
+    filter?: OKDBFilter;
+    reduce:  Record<string, OKDBReducerSpec>;
+}
+
+export type OKDBReducerSpec =
+    | OKDBCountSpec
+    | OKDBSumSpec
+    | OKDBAvgSpec
+    | OKDBMinSpec
+    | OKDBMaxSpec
+    | OKDBCountBySpec
+    | { $ref: OKDBRefSpec }
+    | OKDBCustomSpec;
+
+/** View definition passed to views.create() */
 export interface OKDBViewDefinition {
-    name: string;
-    sourceType: string;
-    targetType: string;
-    map?: string;
-    reduce?: string;
-    [key: string]: unknown;
+    /** Source type. Must be registered in this environment. */
+    type: string;
+    /** Optional sift-style filter. Only matching docs contribute to the view. */
+    filter?: OKDBFilter;
+    /** Optional declarative transform applied to each doc before reducers run. */
+    map?: OKDBViewMap;
+    /** Required, non-empty. Maps output field names to reducer specs. */
+    reduce: Record<string, OKDBReducerSpec>;
+}
+
+/** Shape returned for a scalar reducer output ($count, $sum, $avg, $min, $max) */
+export interface OKDBScalarResult {
+    value: number | null;
+    /** Present when items:true was set — returns the live source docs for this bucket */
+    items?: () => unknown[];
+}
+
+/** Shape returned for a $countBy reducer output */
+export type OKDBCountByResult = Record<string, OKDBScalarResult>;
+
+/** Shape returned for a $ref slot */
+export type OKDBRefResult = Record<string, OKDBScalarResult | OKDBCountByResult>;
+
+/** The full output object returned by views.get() */
+export type OKDBViewOutput = Record<string, OKDBScalarResult | OKDBCountByResult | OKDBRefResult>;
+
+/** View lifecycle meta returned by views.getMeta() */
+export interface OKDBViewMeta {
+    state: 'creating' | 'ready' | 'halted' | 'stopped' | 'resetting';
+    clock: number;
+    error: { clock: number; key: string; error: string } | null;
+    refs: Record<string, { state: string; clock: number; error: string | null }>;
+}
+
+/** Stored view definition returned by views.getDefinition() (includes name and createdAt) */
+export type OKDBStoredViewDefinition = OKDBViewDefinition & { name: string; createdAt: number };
+
+/** Options for views.remove() */
+export interface OKDBViewRemoveOptions {
+    /**
+     * How to handle indexes auto-created by this view.
+     * Required when the view owns indexes that would otherwise become orphaned.
+     * - 'drop'  — drop the index
+     * - 'keep'  — retain the index (it becomes unowned)
+     */
+    managedIndexes?: 'drop' | 'keep';
+}
+
+/** Custom reducer registration */
+export interface OKDBCustomReducer {
+    apply(state: unknown, before: unknown, after: unknown, opts: unknown): unknown;
 }
 
 export declare class OKDBViews {
-    register(definition: OKDBViewDefinition): Promise<void>;
-    unregister(name: string): Promise<void>;
-    get(name: string): OKDBViewDefinition | null;
-    list(): OKDBViewDefinition[];
+    /**
+     * Create a new materialized view. The source type must already be registered.
+     * Synchronously bootstraps existing documents then registers an incremental processor.
+     */
+    create(name: string, definition: OKDBViewDefinition): Promise<{ name: string }>;
+
+    /**
+     * Read the current view output. Synchronous and O(1).
+     * Returns null if the view does not exist.
+     */
+    get(name: string): OKDBViewOutput | null;
+
+    /**
+     * Get view lifecycle meta (state, clock, error).
+     * Returns null if the view does not exist.
+     */
+    getMeta(name: string): OKDBViewMeta | null;
+
+    /**
+     * Get the stored view definition.
+     * Returns null if the view does not exist.
+     */
+    getDefinition(name: string): Promise<OKDBStoredViewDefinition | null>;
+
+    /** List all view names in this environment. */
+    list(): Promise<string[]>;
+
+    /**
+     * Remove a view. Pass managedIndexes when the view owns auto-created indexes.
+     */
+    remove(name: string, options?: OKDBViewRemoveOptions): Promise<void>;
+
+    /** Clears all accumulated state and re-scans from scratch. */
+    rebuild(name: string): Promise<void>;
+
+    /** Pause the view. Writes that arrive while stopped are replayed on start(). */
+    stop(name: string): Promise<void>;
+
+    /**
+     * Resume a stopped (or halted) view.
+     * Optimistically catches up with new inserts; performs a full rebuild otherwise.
+     */
+    start(name: string): Promise<void>;
+
+    /**
+     * Register a custom reducer. Must be called before creating any view that uses it.
+     * The name must start with '$' and must not conflict with a built-in reducer.
+     */
+    registerReducer(name: string, reducer: OKDBCustomReducer): void;
+
+    /** @internal Called by OKDB after sync to activate views that arrived from peers. */
     bootSyncedViews(): Promise<void>;
 }