@xnetjs/data 0.0.2 → 0.1.0

package/dist/database/index.d.ts

@@ -0,0 +1,882 @@
+export { a as CELL_PREFIX, C as CellValue, d2 as CloneSchemaOptions, d3 as CloneSchemaResult, d4 as CloneSourceData, aY as ConvertContext, aZ as ConvertedCell, cY as CreateDatabaseSchemaResolverOptions, ag as CreateExtensionFieldOptions, a0 as CreateFieldOptions, h as CreateRowOptions, a2 as CreateSelectOptionOptions, ao as CreateViewOptions, bz as CsvExportOptions, bk as CsvParseOptions, cN as DATABASE_SCHEMA_NAMESPACE, cO as DATABASE_SCHEMA_PREFIX, aH as DEFAULT_DATABASE_SCHEMA_VERSION, aV as DatabaseDocumentModel, k as DatabaseRowNode, cQ as DatabaseSchemaMetadata, D as DateRange, cX as DocFetcher, af as EnsureExtensionOptions, by as ExportRow, bC as ExportedColumn, bB as ExportedJSON, O as FIELD_TYPES, L as FieldConfig, N as FieldNode, K as FieldType, F as FileRef, cf as FilterableRow, b6 as FormulaRow, b4 as FormulaService, b7 as FormulaValidationResult, ct as GroupAggregates, cr as GroupConfig, cq as GroupableRow, bm as InferredColumn, bA as JsonExportOptions, bn as JsonParseOptions, M as MAX_KEY_LENGTH, cP as MAX_VERSION_HISTORY, c4 as OPERATORS_BY_TYPE, c5 as OPERATOR_LABELS, bj as ParsedCSV, bl as ParsedJSON, cB as QueryOptions, cC as QueryResult, Q as QueryRowsOptions, j as QueryRowsResult, cA as QueryableRow, R as RICHTEXT_PREFIX, b3 as RollupContext, b2 as RollupRow, cs as RowGroup, P as SELECT_COLORS, cS as SchemaVersionEntry, S as SelectOptionNode, aG as SetupDatabaseResult, cl as SortableRow, cR as StoredColumn, a1 as UpdateFieldOptions, ap as UpdateViewOptions, cT as VersionBumpType, an as ViewNode, aP as addDefaultTableView, aO as addDefaultTitleColumn, cj as addOrToggleSort, bW as addViewSort, a_ as aggregate, V as autoColor, b0 as batchComputeRollups, cJ as buildDatabaseSchema, aJ as buildSchemaFromFields, cD as buildSchemaIRI, cH as bumpSchemaVersion, c as cellKey, aX as cellValueToText, s as checkNeedsRebalancing, bU as clearViewFilters, bY as clearViewSorts, c_ as cloneColumns, c$ as cloneSampleRows, cZ as cloneSchema, cp as collapseAllGroups, b as columnIdFromKey, cd as combineFiltersAnd, ce as combineFiltersOr, y as compareSortKeys, a$ as computeRollup, aW as convertCellValue, cc as createAnyOfFilter, bH as createColumn, br as createCsvBlob, cU as createDatabaseSchemaResolver, cb as createEqualsFilter, ac as createExtensionField, a6 as createField, cv as createFilterQuery, b5 as createFormulaService, cI as createInitialSchemaMetadata, bw as createJsonBlob, aL as createNodeDatabaseSchemaResolver, cx as createPaginatedQuery, l as createRow, aj as createSelectOption, ch as createSort, cw as createSortQuery, cK as createVersionEntry, bP as createView, as as createViewNode, bJ as deleteColumn, ae as deleteExtensionField, a8 as deleteField, aT as deleteMeta, I as deleteRichTextCell, n as deleteRow, al as deleteSelectOption, bR as deleteView, au as deleteViewNode, bs as downloadCsv, bx as downloadJson, bL as duplicateColumn, aa as duplicateField, bS as duplicateView, av as duplicateViewNode, aE as effectiveFieldSortKey, ab as ensureSchemaExtension, bp as escapeCSV, cu as executeQuery, co as expandAllGroups, bo as exportToCsv, bt as exportToJson, bu as exportToJsonArray, bv as exportToNdjson, cV as extractSchemaFromDoc, aI as fieldsToStoredColumns, ca as filterRows, cy as flattenGroups, bq as formatValue, f as fromCellProperties, d0 as generateColumnIdMap, v as generateSortKey, w as generateSortKeyWithJitter, d7 as getAggregationResultType, bE as getColumn, bF as getColumnIndex, bD as getColumns, aU as getDatabaseDocumentModel, aK as getDatabaseSchemaIRI, ai as getDatabaseSelectOptions, d5 as getEmptyValue, a4 as getField, a3 as getFields, aR as getMeta, c8 as getOperatorLabel, c6 as getOperatorsForType, B as getRichTextCell, H as getRichTextColumnIds, J as getRichTextPlainText, o as getRow, cW as getSchemaIRIFromDoc, ah as getSelectOptions, bG as getTitleColumn, a5 as getTitleField, cz as getTotalFromGroups, cM as getVersionBumpType, bN as getView, bO as getViewByType, ar as getViewNode, aq as getViewNodes, bM as getViews, cm as groupRows, ba as guessColumnType, G as hasRichTextColumns, E as hasRichTextContent, c1 as hideColumn, bd as inferColumnTypes, bf as inferColumnsFromRows, bg as inferTypeFromValues, aM as initializeDatabaseDoc, Y as isAutoFieldType, i as isCellKey, g as isCellValue, X as isComputedFieldType, aN as isDatabaseDocInitialized, cF as isDatabaseSchemaIRI, d as isDateRange, T as isFieldType, e as isFileRef, W as isNodeStoreFieldType, d6 as isNumericAggregation, U as isSelectColor, c7 as isValidOperator, x as isValidSortKey, Z as isYDocFieldType, a9 as moveField, p as moveRow, am as moveSelectOption, aw as moveView, A as needsRebalancing, c9 as operatorRequiresValue, b8 as parseCSV, b9 as parseCSVLine, cE as parseDatabaseSchemaIRI, be as parseJSON, bc as parseRow, bb as parseValue, cG as parseVersion, cL as pruneVersionHistory, q as queryRows, r as rebalanceDatabase, z as rebalanceSortKeys, d1 as remapViewColumnIds, ck as removeSort, bX as removeViewSort, ad as renameExtensionField, bK as reorderColumn, c2 as reorderViewColumns, c3 as setColumnWidth, aB as setFieldHidden, aS as setMeta, aD as setViewFieldOrder, aC as setViewFieldWidth, bT as setViewFilters, bZ as setViewGroupBy, ax as setViewNodeFilters, az as setViewNodeGroupBy, ay as setViewNodeSorts, bV as setViewSorts, b$ as setVisibleColumns, aF as setupDatabase, aQ as setupNewDatabase, c0 as showColumn, cg as sortRows, t as toCellProperties, bh as toColumnDefinitions, _ as toFieldNode, $ as toSelectOptionNode, b_ as toggleGroupCollapsed, cn as toggleGroupCollapsedState, ci as toggleSortDirection, aA as toggleViewGroupCollapsed, u as updateCell, m as updateCells, bI as updateColumn, a7 as updateField, ak as updateSelectOption, bQ as updateView, at as updateViewNode, bi as validateJsonData, b1 as validateRollupConfig } from '../clone-C0Jhk2UN.js';
+import { m as FilterGroup, c as ColumnDefinition, C as ColumnType, V as ViewType, p as SortConfig } from '../view-types-DSde-uT_.js';
+export { d as ColumnConfig, B as ColumnSummaryResult, I as DEFAULT_ROW_HEIGHT, D as DateColumnConfig, D as DateFieldConfig, E as EmptyConfig, b as FileColumnConfig, b as FileFieldConfig, n as FilterCondition, o as FilterOperator, F as FormulaColumnConfig, F as FormulaFieldConfig, N as NumberColumnConfig, N as NumberFieldConfig, H as ROW_HEIGHTS, G as ROW_HEIGHT_PX, R as RelationColumnConfig, R as RelationFieldConfig, g as RollupAggregation, a as RollupColumnConfig, a as RollupFieldConfig, M as RowHeight, u as SUMMARY_FUNCTIONS_BY_TYPE, f as SelectColor, S as SelectColumnConfig, e as SelectOption, A as SummaryColumnLike, y as SummaryFunction, z as SummaryRow, T as TextColumnConfig, T as TextFieldConfig, l as ViewConfig, L as asRowHeight, x as computeColumnSummary, j as isAutoColumnType, h as isComputedColumnType, w as isFilledValue, r as isFilterCondition, q as isFilterGroup, i as isNodeStoreColumnType, k as isYDocColumnType, t as requiresDateColumn, K as resolveRowHeightPx, J as rowHeightLabel, v as summaryFunctionLabel, s as supportsGrouping } from '../view-types-DSde-uT_.js';
+import '../types-S-BJAKyK.js';
+import '@xnetjs/core';
+import '@xnetjs/crypto';
+import '@xnetjs/sqlite';
+import '@xnetjs/sync';
+import '../store-DtIDjk7c.js';
+import 'yjs';
+
+/**
+ * @xnetjs/data - Query router for automatic local/hub query routing.
+ *
+ * Determines whether to execute queries locally (in-memory) or on the hub
+ * server based on dataset size and query complexity.
+ */
+
+/**
+ * Query source: where the query will be executed.
+ */
+type QuerySource = 'local' | 'hub' | 'hybrid';
+/**
+ * Configuration for the query router.
+ */
+type QueryRouterConfig = {
+    /** Max rows for local queries (default: 10,000) */
+    localThreshold: number;
+    /** Max rows for hybrid queries (default: 100,000) */
+    hybridThreshold: number;
+    /** Force hub for complex filters (default: true) */
+    complexFilterToHub: boolean;
+    /** Force hub for full-text search (default: true) */
+    searchToHub: boolean;
+    /** Max conditions before filter is considered complex (default: 5) */
+    complexFilterThreshold: number;
+};
+/**
+ * Result of routing decision.
+ */
+type QueryRouterResult = {
+    source: QuerySource;
+    reason: string;
+};
+/**
+ * Options for routing decision.
+ */
+type RouteOptions = {
+    rowCount: number;
+    filters?: FilterGroup;
+    search?: string;
+    hasHubConnection: boolean;
+};
+declare const DEFAULT_ROUTER_CONFIG: QueryRouterConfig;
+/**
+ * Query router that determines optimal query execution location.
+ *
+ * Routing logic:
+ * 1. Full-text search always goes to hub (FTS5)
+ * 2. Complex filters go to hub for SQL efficiency
+ * 3. Small datasets (< 10K) stay local
+ * 4. Medium datasets (10K-100K) use hybrid approach
+ * 5. Large datasets (> 100K) go to hub
+ * 6. Falls back to local if no hub connection
+ */
+declare class QueryRouter {
+    private config;
+    constructor(config?: Partial<QueryRouterConfig>);
+    /**
+     * Determine where to execute a query.
+     */
+    route(options: RouteOptions): QueryRouterResult;
+    /**
+     * Check if a filter is complex enough to warrant hub execution.
+     *
+     * A filter is considered complex if:
+     * - It has more than N conditions (default: 5)
+     * - It has nested groups
+     */
+    isComplexFilter(filter: FilterGroup): boolean;
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): QueryRouterConfig;
+    /**
+     * Update configuration.
+     */
+    setConfig(config: Partial<QueryRouterConfig>): void;
+}
+/**
+ * Create a query router with optional configuration.
+ */
+declare function createQueryRouter(config?: Partial<QueryRouterConfig>): QueryRouter;
+
+/**
+ * @xnetjs/data - LRU row cache for hybrid queries.
+ *
+ * Caches recently fetched rows to avoid re-fetching from the hub.
+ * Uses LRU (Least Recently Used) eviction policy.
+ */
+/**
+ * A cached database row.
+ */
+type CachedRow<T = Record<string, unknown>> = {
+    id: string;
+    databaseId: string;
+    sortKey: string;
+    cells: T;
+    createdAt: number;
+    createdBy: string;
+};
+/**
+ * Configuration for the row cache.
+ */
+type RowCacheConfig = {
+    /** Maximum number of rows to cache (default: 10,000) */
+    maxSize: number;
+    /** Maximum age of cached rows in ms (default: 5 minutes) */
+    maxAge: number;
+};
+/**
+ * Cache statistics.
+ */
+type CacheStats = {
+    size: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+};
+declare const DEFAULT_CACHE_CONFIG: RowCacheConfig;
+/**
+ * LRU cache for database rows.
+ *
+ * Features:
+ * - LRU eviction when at capacity
+ * - TTL-based expiration
+ * - Per-database invalidation
+ * - Cache statistics
+ */
+declare class RowCache<T = Record<string, unknown>> {
+    private cache;
+    private config;
+    private stats;
+    constructor(config?: Partial<RowCacheConfig>);
+    /**
+     * Get a row from the cache.
+     * Returns undefined if not found or expired.
+     */
+    get(id: string): CachedRow<T> | undefined;
+    /**
+     * Get multiple rows from the cache.
+     * Returns only the rows that are found and not expired.
+     */
+    getMany(ids: string[]): Map<string, CachedRow<T>>;
+    /**
+     * Add a row to the cache.
+     */
+    set(id: string, row: CachedRow<T>): void;
+    /**
+     * Add multiple rows to the cache.
+     */
+    setMany(rows: CachedRow<T>[]): void;
+    /**
+     * Check if a row is in the cache (and not expired).
+     */
+    has(id: string): boolean;
+    /**
+     * Invalidate a single row.
+     */
+    invalidate(id: string): void;
+    /**
+     * Invalidate multiple rows.
+     */
+    invalidateMany(ids: string[]): void;
+    /**
+     * Invalidate all rows for a database.
+     */
+    invalidateDatabase(databaseId: string): void;
+    /**
+     * Clear all cached rows.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Get the current size of the cache.
+     */
+    get size(): number;
+    /**
+     * Get the hit rate (hits / total requests).
+     */
+    get hitRate(): number;
+    /**
+     * Prune expired entries.
+     * Call periodically to free memory.
+     */
+    prune(): number;
+    /**
+     * Get all cached row IDs for a database.
+     */
+    getIdsForDatabase(databaseId: string): string[];
+}
+/**
+ * Create a row cache with optional configuration.
+ */
+declare function createRowCache<T = Record<string, unknown>>(config?: Partial<RowCacheConfig>): RowCache<T>;
+
+/**
+ * Formula expression parser.
+ *
+ * Parses formula expressions into an AST for evaluation.
+ * Supports arithmetic, comparison, logical operators, function calls,
+ * and column references using {{columnId}} syntax.
+ */
+type ASTNode = LiteralNode | ReferenceNode | BinaryNode | UnaryNode | CallNode | ConditionalNode;
+interface LiteralNode {
+    type: 'literal';
+    value: unknown;
+}
+interface ReferenceNode {
+    type: 'reference';
+    columnId: string;
+    property?: string;
+}
+interface BinaryNode {
+    type: 'binary';
+    operator: string;
+    left: ASTNode;
+    right: ASTNode;
+}
+interface UnaryNode {
+    type: 'unary';
+    operator: string;
+    operand: ASTNode;
+}
+interface CallNode {
+    type: 'call';
+    name: string;
+    args: ASTNode[];
+}
+interface ConditionalNode {
+    type: 'conditional';
+    condition: ASTNode;
+    then: ASTNode;
+    else: ASTNode;
+}
+declare class FormulaParser {
+    private pos;
+    private expr;
+    private lastMatch;
+    /**
+     * Parse a formula expression into an AST.
+     *
+     * @example
+     * ```typescript
+     * const parser = new FormulaParser()
+     * const ast = parser.parse('{{price}} * {{quantity}}')
+     * ```
+     */
+    parse(expression: string): ASTNode;
+    private parseExpression;
+    private parseOr;
+    private parseAnd;
+    private parseEquality;
+    private parseComparison;
+    private parseAdditive;
+    /**
+     * Match a single '&' but not '&&'.
+     */
+    private matchSingleAmpersand;
+    private parseMultiplicative;
+    private parseUnary;
+    private parsePrimary;
+    private parseNumber;
+    private parseString;
+    private parseIdentifier;
+    private peek;
+    private peekNext;
+    private check;
+    private match;
+    private matchAny;
+    private expect;
+    private skipWhitespace;
+    private isDigit;
+    private isAlpha;
+    private isAlphaNumeric;
+}
+
+/**
+ * Formula expression evaluator.
+ *
+ * Evaluates an AST against a row context to produce a value.
+ */
+
+/**
+ * Context for evaluating a formula.
+ */
+interface EvalContext {
+    /** Get column value for current row */
+    getValue: (columnId: string) => unknown;
+    /** Get column definition */
+    getColumn: (columnId: string) => ColumnDefinition | undefined;
+}
+/**
+ * Evaluate an AST node against a context.
+ *
+ * @example
+ * ```typescript
+ * const context = {
+ *   getValue: (id) => row.cells[id],
+ *   getColumn: (id) => columns.find(c => c.id === id)
+ * }
+ * const result = evaluate(ast, context)
+ * ```
+ */
+declare function evaluate(node: ASTNode, context: EvalContext): unknown;
+/**
+ * Safely evaluate a formula, catching errors.
+ */
+declare function safeEvaluate(node: ASTNode, context: EvalContext): {
+    value: unknown;
+    error?: string;
+};
+
+/**
+ * Built-in formula functions.
+ *
+ * Provides a library of functions for use in formula expressions:
+ * - Math: ABS, ROUND, FLOOR, CEIL, MIN, MAX, SUM, AVG, POW, SQRT
+ * - Text: CONCAT, UPPER, LOWER, TRIM, LENGTH, SUBSTRING, REPLACE, LEFT, RIGHT
+ * - Logic: IF, AND, OR, NOT, COALESCE, ISBLANK
+ * - Date: NOW, TODAY, DATE, YEAR, MONTH, DAY, DATEADD, DATEDIFF
+ * - Array: CONTAINS, COUNT, FIRST, LAST, JOIN, UNIQUE
+ */
+type FormulaFunction = (...args: unknown[]) => unknown;
+declare const FUNCTIONS: Record<string, FormulaFunction>;
+/**
+ * Check if a function name is valid.
+ */
+declare function isValidFunction(name: string): boolean;
+/**
+ * Get a function by name.
+ */
+declare function getFunction(name: string): FormulaFunction | undefined;
+/**
+ * Get all available function names.
+ */
+declare function getFunctionNames(): string[];
+
+/**
+ * Formula dependency tracking and circular detection.
+ *
+ * Extracts column dependencies from formulas and detects circular references.
+ */
+
+/**
+ * Extract column dependencies from a formula expression.
+ *
+ * @example
+ * ```typescript
+ * const deps = extractDependencies('{{price}} * {{quantity}}')
+ * // ['price', 'quantity']
+ * ```
+ */
+declare function extractDependencies(expression: string): string[];
+interface CircularCheckResult {
+    hasCircular: boolean;
+    cycle?: string[];
+}
+/**
+ * Check for circular dependencies between formula columns.
+ *
+ * @example
+ * ```typescript
+ * const result = detectCircularDependencies(columns)
+ * if (result.hasCircular) {
+ *   console.log('Circular dependency:', result.cycle)
+ * }
+ * ```
+ */
+declare function detectCircularDependencies(columns: ColumnDefinition[]): CircularCheckResult;
+/**
+ * Check if adding a formula would create a circular dependency.
+ *
+ * @example
+ * ```typescript
+ * const wouldCycle = wouldCreateCircular('total', '{{subtotal}} + {{tax}}', columns)
+ * ```
+ */
+declare function wouldCreateCircular(columnId: string, expression: string, columns: ColumnDefinition[]): boolean;
+interface DependencyGraph {
+    /** columnId -> column IDs it depends on */
+    columnDeps: Map<string, string[]>;
+    /** columnId -> column IDs that depend on it */
+    reverseDeps: Map<string, string[]>;
+}
+/**
+ * Build a dependency graph for all columns.
+ *
+ * @example
+ * ```typescript
+ * const graph = buildDependencyGraph(columns)
+ * const affectedColumns = graph.reverseDeps.get('price') // Columns that depend on price
+ * ```
+ */
+declare function buildDependencyGraph(columns: ColumnDefinition[]): DependencyGraph;
+/**
+ * Get all columns that need recomputing when a column changes.
+ * Traverses the dependency graph to find all affected columns.
+ *
+ * @example
+ * ```typescript
+ * const affected = getAffectedColumns('price', graph)
+ * // Returns all columns that depend on 'price' (directly or indirectly)
+ * ```
+ */
+declare function getAffectedColumns(changedColumnId: string, graph: DependencyGraph): string[];
+/**
+ * Get the evaluation order for formula columns.
+ * Returns columns in topological order (dependencies first).
+ *
+ * @example
+ * ```typescript
+ * const order = getEvaluationOrder(columns)
+ * // Evaluate formulas in this order to ensure dependencies are computed first
+ * ```
+ */
+declare function getEvaluationOrder(columns: ColumnDefinition[]): ColumnDefinition[];
+
+/**
+ * Computed value cache for rollups and formulas.
+ *
+ * Provides efficient caching with LRU eviction, TTL expiration,
+ * and dependency-based invalidation.
+ */
+/**
+ * A cached computed value entry.
+ */
+interface ComputedCacheEntry {
+    /** The computed value */
+    value: unknown;
+    /** When the value was computed (timestamp) */
+    computedAt: number;
+    /** Hash of inputs used to compute (for validation) */
+    inputHash: string;
+    /** Row IDs this value depends on */
+    dependencies: string[];
+}
+/**
+ * Configuration for the computed cache.
+ */
+interface ComputedCacheConfig {
+    /** Maximum entries in memory cache */
+    maxSize: number;
+    /** Maximum age before recompute (ms) */
+    maxAge: number;
+}
+/**
+ * Cache statistics.
+ */
+interface ComputedCacheStats {
+    /** Number of entries in cache */
+    size: number;
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+    /** Number of evictions */
+    evictions: number;
+    /** Number of invalidations */
+    invalidations: number;
+}
+/**
+ * Default cache configuration.
+ */
+declare const DEFAULT_COMPUTED_CACHE_CONFIG: ComputedCacheConfig;
+/**
+ * In-memory cache for computed column values.
+ *
+ * Features:
+ * - LRU eviction when at capacity
+ * - TTL-based expiration
+ * - Dependency-based invalidation
+ * - Cache statistics
+ *
+ * @example
+ * ```typescript
+ * const cache = new ComputedCache()
+ *
+ * // Store a computed value
+ * cache.set('row-1', 'total', {
+ *   value: 100,
+ *   computedAt: Date.now(),
+ *   inputHash: 'abc123',
+ *   dependencies: ['row-2', 'row-3']
+ * })
+ *
+ * // Retrieve
+ * const entry = cache.get('row-1', 'total')
+ *
+ * // Invalidate when a dependency changes
+ * cache.invalidate('row-2')
+ * ```
+ */
+declare class ComputedCache {
+    private config;
+    private memory;
+    private dependencyIndex;
+    private accessOrder;
+    private stats;
+    constructor(config?: ComputedCacheConfig);
+    /**
+     * Get a cached computed value.
+     * Returns null if not found or expired.
+     */
+    get(rowId: string, columnId: string): ComputedCacheEntry | null;
+    /**
+     * Store a computed value.
+     */
+    set(rowId: string, columnId: string, entry: ComputedCacheEntry): void;
+    /**
+     * Check if a value exists and is valid.
+     */
+    has(rowId: string, columnId: string): boolean;
+    /**
+     * Invalidate all computed values that depend on a row.
+     */
+    invalidate(rowId: string): void;
+    /**
+     * Invalidate a specific computed value.
+     */
+    invalidateCell(rowId: string, columnId: string): void;
+    /**
+     * Invalidate all computed values for a database.
+     */
+    invalidateDatabase(_databaseId: string): void;
+    /**
+     * Clear all cached values.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): ComputedCacheStats;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    private cacheKey;
+    private isExpired;
+    private evictOldest;
+    private updateAccessOrder;
+    private removeFromAccessOrder;
+}
+/**
+ * Create a new ComputedCache instance.
+ */
+declare function createComputedCache(config?: Partial<ComputedCacheConfig>): ComputedCache;
+/**
+ * Batch invalidate for bulk operations.
+ */
+declare function batchInvalidate(cache: ComputedCache, rowIds: string[]): void;
+/**
+ * Compute a hash for input values.
+ * Used to detect when cached values are stale.
+ */
+declare function computeInputHash(values: Record<string, unknown>): string;
+/**
+ * Check if a cached entry is still valid based on current inputs.
+ */
+declare function isEntryValid(entry: ComputedCacheEntry, currentInputs: Record<string, unknown>): boolean;
+
+/**
+ * Template type definitions for database templates.
+ *
+ * Templates provide pre-built database structures that can be
+ * instantiated to create new databases.
+ */
+
+/**
+ * A database template definition.
+ */
+interface DatabaseTemplate {
+    /** Unique template ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Icon (emoji or icon name) */
+    icon: string;
+    /** Category for organization */
+    category: TemplateCategory;
+    /** Column definitions */
+    columns: TemplateColumn[];
+    /** View definitions */
+    views: TemplateView[];
+    /** Optional sample data rows */
+    sampleData?: TemplateSampleRow[];
+    /** Template metadata */
+    metadata: TemplateMetadata;
+}
+/**
+ * Template categories for organization.
+ */
+type TemplateCategory = 'project-management' | 'crm' | 'inventory' | 'content' | 'personal' | 'education' | 'finance' | 'custom';
+/**
+ * Column definition within a template.
+ * Uses placeholder IDs that are remapped on instantiation.
+ */
+interface TemplateColumn {
+    /** Placeholder ID (will be remapped on instantiation) */
+    id: string;
+    /** Column name */
+    name: string;
+    /** Column type */
+    type: ColumnType;
+    /** Type-specific configuration */
+    config: Record<string, unknown>;
+    /** Whether this is the title column */
+    isTitle?: boolean;
+    /** Default width in pixels */
+    width?: number;
+}
+/**
+ * View definition within a template.
+ */
+interface TemplateView {
+    /** Placeholder ID */
+    id: string;
+    /** View name */
+    name: string;
+    /** View type */
+    type: ViewType;
+    /** Visible column IDs (placeholders) */
+    visibleColumns: string[];
+    /** Filter configuration */
+    filters?: FilterGroup;
+    /** Sort configuration */
+    sorts?: SortConfig[];
+    /** Group by column ID (placeholder) */
+    groupBy?: string;
+    /** Column widths */
+    columnWidths?: Record<string, number>;
+}
+/**
+ * Sample data row within a template.
+ */
+interface TemplateSampleRow {
+    /** Cell values keyed by column placeholder ID */
+    cells: Record<string, unknown>;
+}
+/**
+ * Template metadata.
+ */
+interface TemplateMetadata {
+    /** Template version */
+    version: string;
+    /** Author DID (for user templates) */
+    author?: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last updated timestamp */
+    updatedAt: string;
+    /** Usage count (for popularity sorting) */
+    usageCount?: number;
+    /** Tags for search */
+    tags: string[];
+}
+/**
+ * Options for instantiating a template.
+ */
+interface InstantiateOptions {
+    /** Include sample data rows (default: true) */
+    includeSampleData?: boolean;
+    /** Override database name */
+    name?: string;
+}
+/**
+ * Result of instantiating a template.
+ */
+interface InstantiatedDatabase {
+    /** New database ID */
+    id: string;
+    /** Database name */
+    name: string;
+    /** Column definitions with real IDs */
+    columns: InstantiatedColumn[];
+    /** View definitions with real IDs */
+    views: InstantiatedView[];
+    /** Sample data rows with real IDs */
+    rows: InstantiatedRow[];
+    /** Mapping from template column IDs to real IDs */
+    columnIdMap: Map<string, string>;
+    /** Mapping from template view IDs to real IDs */
+    viewIdMap: Map<string, string>;
+}
+/**
+ * Instantiated column with real ID.
+ */
+interface InstantiatedColumn {
+    id: string;
+    name: string;
+    type: ColumnType;
+    config: Record<string, unknown>;
+    isTitle?: boolean;
+    width?: number;
+}
+/**
+ * Instantiated view with real ID.
+ */
+interface InstantiatedView {
+    id: string;
+    name: string;
+    type: ViewType;
+    visibleColumns: string[];
+    filters?: FilterGroup;
+    sorts?: SortConfig[];
+    groupBy?: string;
+    columnWidths?: Record<string, number>;
+}
+/**
+ * Instantiated row with real ID.
+ */
+interface InstantiatedRow {
+    id: string;
+    sortKey: string;
+    cells: Record<string, unknown>;
+}
+/**
+ * Options for saving a database as a template.
+ */
+interface SaveTemplateOptions {
+    /** Template name */
+    name: string;
+    /** Template description */
+    description: string;
+    /** Template icon (default: clipboard emoji) */
+    icon?: string;
+    /** Template category (default: custom) */
+    category?: TemplateCategory;
+    /** Include current data as sample data (default: false) */
+    includeSampleData?: boolean;
+    /** Maximum sample rows to include (default: 5) */
+    maxSampleRows?: number;
+    /** Tags for search */
+    tags?: string[];
+    /** Author DID */
+    authorDid?: string;
+}
+/**
+ * Database structure for creating a template.
+ */
+interface DatabaseForTemplate {
+    name: string;
+    columns: Array<{
+        id: string;
+        name: string;
+        type: ColumnType;
+        config: Record<string, unknown>;
+        isTitle?: boolean;
+        width?: number;
+    }>;
+    views: Array<{
+        id: string;
+        name: string;
+        type: ViewType;
+        visibleColumns: string[];
+        filters?: FilterGroup;
+        sorts?: SortConfig[];
+        groupBy?: string;
+        columnWidths?: Record<string, number>;
+    }>;
+    rows: Array<{
+        id: string;
+        sortKey: string;
+        cells: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * Built-in database templates.
+ *
+ * Provides ready-to-use templates for common use cases:
+ * - Project Tracker
+ * - Task List
+ * - CRM Contacts
+ * - Inventory Tracker
+ * - Content Calendar
+ * - Reading List
+ * - Expense Tracker
+ * - Course Planner
+ */
+
+declare const BUILTIN_TEMPLATES: DatabaseTemplate[];
+/**
+ * Get templates by category.
+ */
+declare function getTemplatesByCategory(category: TemplateCategory): DatabaseTemplate[];
+/**
+ * Search templates by name, description, or tags.
+ */
+declare function searchTemplates(query: string): DatabaseTemplate[];
+/**
+ * Get a template by ID.
+ */
+declare function getTemplateById(id: string): DatabaseTemplate | undefined;
+/**
+ * Get all template categories with counts.
+ */
+declare function getTemplateCategoryCounts(): Record<TemplateCategory, number>;
+
+/**
+ * Template instantiation - create a new database from a template.
+ *
+ * Handles:
+ * - Remapping placeholder IDs to real IDs
+ * - Creating column definitions
+ * - Creating view definitions
+ * - Optionally including sample data
+ */
+
+/**
+ * Create a new database from a template.
+ *
+ * @example
+ * const template = getTemplateById('project-tracker')
+ * const db = instantiateTemplate(template, { includeSampleData: true })
+ */
+declare function instantiateTemplate(template: DatabaseTemplate, options?: InstantiateOptions): InstantiatedDatabase;
+/**
+ * Create an empty database template.
+ * Useful for "start from scratch" option.
+ */
+declare function createEmptyTemplate(): DatabaseTemplate;
+/**
+ * Create an empty database (instantiated).
+ */
+declare function createEmptyDatabase(name?: string): InstantiatedDatabase;
+
+/**
+ * Save database as template.
+ *
+ * Converts an existing database structure into a reusable template.
+ * Handles:
+ * - Converting real IDs to stable placeholder IDs
+ * - Optionally including sample data
+ * - Sanitizing sensitive values
+ */
+
+/**
+ * Create a template from an existing database.
+ *
+ * @example
+ * const template = createTemplateFromDatabase(database, {
+ *   name: 'My Template',
+ *   description: 'A custom template',
+ *   tags: ['custom', 'project']
+ * })
+ */
+declare function createTemplateFromDatabase(database: DatabaseForTemplate, options: SaveTemplateOptions): DatabaseTemplate;
+/**
+ * Remove sensitive data from values for template sample data.
+ */
+declare function sanitizeValueForTemplate(value: unknown): unknown;
+/**
+ * Validate a template structure.
+ */
+declare function validateTemplate(template: DatabaseTemplate): {
+    valid: boolean;
+    errors: string[];
+};
+
+export { type ASTNode, BUILTIN_TEMPLATES, type CacheStats, type CachedRow, type CircularCheckResult, ColumnDefinition, ColumnType, ComputedCache, type ComputedCacheConfig, type ComputedCacheEntry, type ComputedCacheStats, DEFAULT_CACHE_CONFIG, DEFAULT_COMPUTED_CACHE_CONFIG, DEFAULT_ROUTER_CONFIG, type DatabaseForTemplate, type DatabaseTemplate, type DependencyGraph, type EvalContext, FUNCTIONS, FilterGroup, type FormulaFunction, FormulaParser, type InstantiateOptions, type InstantiatedColumn, type InstantiatedDatabase, type InstantiatedRow, type InstantiatedView, QueryRouter, type QueryRouterConfig, type QueryRouterResult, type QuerySource, type RouteOptions, RowCache, type RowCacheConfig, type SaveTemplateOptions, SortConfig, type TemplateCategory, type TemplateColumn, type TemplateMetadata, type TemplateSampleRow, type TemplateView, ViewType, batchInvalidate, buildDependencyGraph, computeInputHash, createComputedCache, createEmptyDatabase, createEmptyTemplate, createQueryRouter, createRowCache, createTemplateFromDatabase, detectCircularDependencies, evaluate, extractDependencies, getAffectedColumns, getEvaluationOrder, getFunction, getFunctionNames, getTemplateById, getTemplateCategoryCounts, getTemplatesByCategory, instantiateTemplate, isEntryValid, isValidFunction, safeEvaluate, sanitizeValueForTemplate, searchTemplates, validateTemplate, wouldCreateCircular };