@quereus/quereus 0.1.0

package/dist/src/util/plan-formatter.d.ts

@@ -0,0 +1,23 @@
+import type { ScalarPlanNode } from '../planner/nodes/plan-node.js';
+import type { ScalarType } from '../common/datatype.js';
+/**
+ * Convert a ScalarPlanNode to its string representation for use in plan descriptions.
+ */
+export declare function formatExpression(node: ScalarPlanNode): string;
+/**
+ * Convert multiple ScalarPlanNodes to a comma-separated string.
+ */
+export declare function formatExpressionList(nodes: readonly ScalarPlanNode[]): string;
+/**
+ * Format a scalar type to a simple string representation.
+ */
+export declare function formatScalarType(type: ScalarType): string;
+/**
+ * Format projection for display (expression with optional alias).
+ */
+export declare function formatProjection(expr: ScalarPlanNode, alias?: string): string;
+/**
+ * Format sort key for display.
+ */
+export declare function formatSortKey(expr: ScalarPlanNode, direction: 'asc' | 'desc', nulls?: 'first' | 'last'): string;
+//# sourceMappingURL=plan-formatter.d.ts.map

package/dist/src/util/plan-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-formatter.d.ts","sourceRoot":"","sources":["../../../src/util/plan-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAE7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAKzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,KAAK,GAAG,MAAM,EACzB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GACtB,MAAM,CAMR"}

package/dist/src/util/plan-formatter.js

@@ -0,0 +1,41 @@
+import { expressionToString } from './ast-stringify.js';
+import { SqlDataType } from '../common/types.js';
+/**
+ * Convert a ScalarPlanNode to its string representation for use in plan descriptions.
+ */
+export function formatExpression(node) {
+    return expressionToString(node.expression);
+}
+/**
+ * Convert multiple ScalarPlanNodes to a comma-separated string.
+ */
+export function formatExpressionList(nodes) {
+    return nodes.map(formatExpression).join(', ');
+}
+/**
+ * Format a scalar type to a simple string representation.
+ */
+export function formatScalarType(type) {
+    if (type.datatype !== undefined) {
+        return SqlDataType[type.datatype];
+    }
+    return SqlDataType[type.affinity];
+}
+/**
+ * Format projection for display (expression with optional alias).
+ */
+export function formatProjection(expr, alias) {
+    const exprStr = formatExpression(expr);
+    return alias && alias !== exprStr ? `${exprStr} AS ${alias}` : exprStr;
+}
+/**
+ * Format sort key for display.
+ */
+export function formatSortKey(expr, direction, nulls) {
+    const parts = [formatExpression(expr), direction.toUpperCase()];
+    if (nulls) {
+        parts.push(`NULLS ${nulls.toUpperCase()}`);
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=plan-formatter.js.map

package/dist/src/util/plan-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-formatter.js","sourceRoot":"","sources":["../../../src/util/plan-formatter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACpD,OAAO,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACpE,OAAO,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAChD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAoB,EAAE,KAAc;IACpE,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,KAAK,IAAI,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC5B,IAAoB,EACpB,SAAyB,EACzB,KAAwB;IAExB,MAAM,KAAK,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IAChE,IAAI,KAAK,EAAE,CAAC;QACX,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/dist/src/util/plugin-loader.d.ts

@@ -0,0 +1,20 @@
+import type { Database } from '../core/database.js';
+import type { PluginManifest } from '../vtab/manifest.js';
+import { type SqlValue } from '../common/types.js';
+/**
+ * Dynamically loads and registers a plugin module
+ *
+ * @param url The URL to the ES module (can be https:// or file:// URL)
+ * @param db The Database instance to register the module with
+ * @param config Configuration values to pass to the module
+ * @returns The plugin's manifest if available
+ */
+export declare function dynamicLoadModule(url: string, db: Database, config?: Record<string, SqlValue>): Promise<PluginManifest | undefined>;
+/**
+ * Validates that a URL is likely to be a valid plugin module
+ *
+ * @param url The URL to validate
+ * @returns true if the URL appears valid
+ */
+export declare function validatePluginUrl(url: string): boolean;
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/src/util/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../../src/util/plugin-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG/D;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACtC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,QAAQ,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAM,GACnC,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAyBrC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAkBtD"}

package/dist/src/util/plugin-loader.js

@@ -0,0 +1,57 @@
+import { StatusCode } from '../common/types.js';
+import { quereusError } from '../common/errors.js';
+/**
+ * Dynamically loads and registers a plugin module
+ *
+ * @param url The URL to the ES module (can be https:// or file:// URL)
+ * @param db The Database instance to register the module with
+ * @param config Configuration values to pass to the module
+ * @returns The plugin's manifest if available
+ */
+export async function dynamicLoadModule(url, db, config = {}) {
+    try {
+        // Add cache-busting timestamp for development
+        const moduleUrl = new URL(url);
+        if (moduleUrl.protocol === 'file:' || moduleUrl.hostname === 'localhost') {
+            moduleUrl.searchParams.set('t', Date.now().toString());
+        }
+        // Dynamic import with Vite ignore comment for bundler compatibility
+        const mod = await import(/* @vite-ignore */ moduleUrl.toString());
+        // Validate module structure
+        if (typeof mod.default !== 'function') {
+            quereusError(`Module at ${url} has no default export function`, StatusCode.FORMAT);
+        }
+        // Call the module's register function with the database and config
+        await mod.default(db, config);
+        // Return the manifest if available
+        return mod.manifest;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        quereusError(`Failed to load plugin from ${url}: ${message}`);
+    }
+}
+/**
+ * Validates that a URL is likely to be a valid plugin module
+ *
+ * @param url The URL to validate
+ * @returns true if the URL appears valid
+ */
+export function validatePluginUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Allow https:// and file:// protocols
+        if (!['https:', 'file:'].includes(parsed.protocol)) {
+            return false;
+        }
+        // Must end with .js or .mjs
+        if (!/\.(m?js)$/i.test(parsed.pathname)) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=plugin-loader.js.map

package/dist/src/util/plugin-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.js","sourceRoot":"","sources":["../../../src/util/plugin-loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,GAAW,EACX,EAAY,EACZ,SAAmC,EAAE;IAErC,IAAI,CAAC;QACJ,8CAA8C;QAC9C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,SAAS,CAAC,QAAQ,KAAK,OAAO,IAAI,SAAS,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YAC1E,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,oEAAoE;QACpE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;QAElE,4BAA4B;QAC5B,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACvC,YAAY,CAAC,aAAa,GAAG,iCAAiC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QACpF,CAAC;QAED,mEAAmE;QACnE,MAAM,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAE9B,mCAAmC;QACnC,OAAO,GAAG,CAAC,QAAsC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,YAAY,CAAC,8BAA8B,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC5C,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAE5B,uCAAuC;QACvC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpD,OAAO,KAAK,CAAC;QACd,CAAC;QAED,4BAA4B;QAC5B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,OAAO,KAAK,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/src/util/row-descriptor.d.ts

@@ -0,0 +1,35 @@
+import type { RowDescriptor, Attribute } from '../planner/nodes/plan-node.js';
+import type { Row } from '../common/types.js';
+/**
+ * Utility to build a RowDescriptor (attributeId → columnIndex mapping)
+ * for any relational plan node.
+ */
+export declare function buildRowDescriptor(attributes: Attribute[]): RowDescriptor;
+/**
+ * Creates OLD and NEW row descriptors for mutation operations.
+ * Returns descriptors where OLD columns are at indices 0..n-1 and NEW columns at n..2n-1
+ */
+export declare function buildOldNewRowDescriptors(oldAttributes: Attribute[], newAttributes: Attribute[]): {
+    oldRowDescriptor: RowDescriptor;
+    newRowDescriptor: RowDescriptor;
+    flatRowDescriptor: RowDescriptor;
+};
+/**
+ * Composes a flat row from OLD and NEW row values.
+ * Result format: [oldCol0, oldCol1, ..., oldColN, newCol0, newCol1, ..., newColN]
+ */
+export declare function composeOldNewRow(oldRow: Row | null, newRow: Row | null, columnCount: number): Row;
+/**
+ * Extracts NEW values from a flat OLD/NEW row
+ */
+export declare function extractNewRowFromFlat(flatRow: Row, columnCount: number): Row;
+/**
+ * Extracts OLD values from a flat OLD/NEW row
+ */
+export declare function extractOldRowFromFlat(flatRow: Row, columnCount: number): Row;
+/**
+ * Helper to build Attribute array from flatRowDescriptor for DML nodes.
+ * This is used by UpdateNode and DeleteNode to expose their flat row layout.
+ */
+export declare function buildAttributesFromFlatDescriptor(flatRowDescriptor: RowDescriptor): Attribute[];
+//# sourceMappingURL=row-descriptor.d.ts.map

package/dist/src/util/row-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-descriptor.d.ts","sourceRoot":"","sources":["../../../src/util/row-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAG9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,aAAa,CAMzE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,aAAa,EAAE,SAAS,EAAE,EAC1B,aAAa,EAAE,SAAS,EAAE,GACxB;IACF,gBAAgB,EAAE,aAAa,CAAC;IAChC,gBAAgB,EAAE,aAAa,CAAC;IAChC,iBAAiB,EAAE,aAAa,CAAC;CACjC,CAmBA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG,CAcjG;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG,CAE5E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG,CAE5E;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAAC,iBAAiB,EAAE,aAAa,GAAG,SAAS,EAAE,CAkB/F"}

package/dist/src/util/row-descriptor.js

@@ -0,0 +1,85 @@
+import { SqlDataType } from '../common/types.js';
+/**
+ * Utility to build a RowDescriptor (attributeId → columnIndex mapping)
+ * for any relational plan node.
+ */
+export function buildRowDescriptor(attributes) {
+    const descriptor = [];
+    attributes.forEach((attr, index) => {
+        descriptor[attr.id] = index;
+    });
+    return descriptor;
+}
+/**
+ * Creates OLD and NEW row descriptors for mutation operations.
+ * Returns descriptors where OLD columns are at indices 0..n-1 and NEW columns at n..2n-1
+ */
+export function buildOldNewRowDescriptors(oldAttributes, newAttributes) {
+    const oldRowDescriptor = [];
+    const newRowDescriptor = [];
+    const flatRowDescriptor = [];
+    // OLD attributes occupy indices 0..n-1
+    oldAttributes.forEach((attr, index) => {
+        oldRowDescriptor[attr.id] = index;
+        flatRowDescriptor[attr.id] = index;
+    });
+    // NEW attributes occupy indices n..2n-1
+    newAttributes.forEach((attr, index) => {
+        const flatIndex = oldAttributes.length + index;
+        newRowDescriptor[attr.id] = index;
+        flatRowDescriptor[attr.id] = flatIndex;
+    });
+    return { oldRowDescriptor, newRowDescriptor, flatRowDescriptor };
+}
+/**
+ * Composes a flat row from OLD and NEW row values.
+ * Result format: [oldCol0, oldCol1, ..., oldColN, newCol0, newCol1, ..., newColN]
+ */
+export function composeOldNewRow(oldRow, newRow, columnCount) {
+    const flatRow = new Array(columnCount * 2);
+    // Fill OLD section (indices 0..n-1)
+    for (let i = 0; i < columnCount; i++) {
+        flatRow[i] = oldRow ? oldRow[i] : null;
+    }
+    // Fill NEW section (indices n..2n-1)
+    for (let i = 0; i < columnCount; i++) {
+        flatRow[columnCount + i] = newRow ? newRow[i] : null;
+    }
+    return flatRow;
+}
+/**
+ * Extracts NEW values from a flat OLD/NEW row
+ */
+export function extractNewRowFromFlat(flatRow, columnCount) {
+    return flatRow.slice(columnCount, columnCount * 2);
+}
+/**
+ * Extracts OLD values from a flat OLD/NEW row
+ */
+export function extractOldRowFromFlat(flatRow, columnCount) {
+    return flatRow.slice(0, columnCount);
+}
+/**
+ * Helper to build Attribute array from flatRowDescriptor for DML nodes.
+ * This is used by UpdateNode and DeleteNode to expose their flat row layout.
+ */
+export function buildAttributesFromFlatDescriptor(flatRowDescriptor) {
+    const attributes = [];
+    for (const attrIdStr in flatRowDescriptor) {
+        const attrId = parseInt(attrIdStr);
+        const index = flatRowDescriptor[attrId];
+        attributes[index] = {
+            id: attrId,
+            name: `attr_${attrId}`,
+            type: {
+                typeClass: 'scalar',
+                affinity: SqlDataType.TEXT,
+                nullable: true,
+                isReadOnly: false
+            },
+            sourceRelation: 'unknown'
+        };
+    }
+    return attributes;
+}
+//# sourceMappingURL=row-descriptor.js.map

package/dist/src/util/row-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-descriptor.js","sourceRoot":"","sources":["../../../src/util/row-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/src/util/serialization.d.ts

@@ -0,0 +1,11 @@
+export declare function jsonStringify(obj: any, space?: string | number): string;
+/**
+ * Safely stringifies an object to JSON, converting BigInts to strings
+ * ending with 'n' to avoid serialization errors.
+ *
+ * @param obj The object to stringify.
+ * @param space Optional spacing argument for JSON.stringify.
+ * @returns JSON string representation.
+ */
+export declare function safeJsonStringify(obj: any, space?: string | number): string;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/src/util/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/util/serialization.ts"],"names":[],"mappings":"AAQA,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAkBvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAQ3E"}

package/dist/src/util/serialization.js

@@ -0,0 +1,41 @@
+/**
+ * Utility functions for safe serialization, particularly handling BigInt and Uint8Arrays.
+ */
+import { createLogger } from '../common/logger.js';
+const log = createLogger('util:serialization');
+const errorLog = log.extend('error');
+export function jsonStringify(obj, space) {
+    return JSON.stringify(obj, (_, value) => {
+        if (typeof value === 'bigint') {
+            // Convert to number if it's within safe integer limits for JSON
+            if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+                return Number(value);
+            }
+            // Otherwise, convert to string (without 'n' suffix for standard JSON)
+            return value.toString();
+        }
+        else if (value instanceof Uint8Array) {
+            return `0x${Buffer.from(value).toString('hex')}`; // Keep existing Uint8Array handling
+        }
+        return value;
+    }, space);
+}
+/**
+ * Safely stringifies an object to JSON, converting BigInts to strings
+ * ending with 'n' to avoid serialization errors.
+ *
+ * @param obj The object to stringify.
+ * @param space Optional spacing argument for JSON.stringify.
+ * @returns JSON string representation.
+ */
+export function safeJsonStringify(obj, space) {
+    try {
+        return jsonStringify(obj, space);
+    }
+    catch (e) {
+        // Fallback in case of unexpected stringify errors
+        errorLog("safeJsonStringify failed:", e);
+        return `[Unserializable Object: ${e instanceof Error ? e.message : String(e)}]`;
+    }
+}
+//# sourceMappingURL=serialization.js.map

package/dist/src/util/serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../../../src/util/serialization.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,GAAG,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;AAC/C,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAErC,MAAM,UAAU,aAAa,CAAC,GAAQ,EAAE,KAAuB;IAC7D,OAAO,IAAI,CAAC,SAAS,CACrB,GAAG,EACH,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QACZ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,gEAAgE;YAChE,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;gBAC1F,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,sEAAsE;YACtE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QACzB,CAAC;aAAM,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YACxC,OAAO,KAAK,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,oCAAoC;QACvF,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC,EACD,KAAK,CACL,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ,EAAE,KAAuB;IACjE,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,kDAAkD;QAClD,QAAQ,CAAC,2BAA2B,EAAE,CAAC,CAAC,CAAC;QACzC,OAAO,2BAA2B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;IAClF,CAAC;AACH,CAAC"}

package/dist/src/util/working-table-iterable.d.ts

@@ -0,0 +1,17 @@
+import type { Row } from '../common/types.js';
+import type { RuntimeContext } from '../runtime/types.js';
+import type { RowDescriptor } from '../planner/nodes/plan-node.js';
+/**
+ * A reusable async iterable for working table data that can be iterated multiple times.
+ * Similar to CachedIterable but for runtime-generated working table data.
+ * Used primarily in recursive CTE execution where the working table needs to be
+ * accessed multiple times during recursive iterations.
+ */
+export declare class WorkingTableIterable implements AsyncIterable<Row> {
+    private rows;
+    private rctx;
+    private rowDescriptor;
+    constructor(rows: Row[], rctx: RuntimeContext, rowDescriptor: RowDescriptor);
+    [Symbol.asyncIterator](): AsyncIterator<Row>;
+}
+//# sourceMappingURL=working-table-iterable.d.ts.map

package/dist/src/util/working-table-iterable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-table-iterable.d.ts","sourceRoot":"","sources":["../../../src/util/working-table-iterable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,aAAa,CAAC,GAAG,CAAC;IAE7D,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,aAAa;gBAFb,IAAI,EAAE,GAAG,EAAE,EACX,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,aAAa;IAG9B,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC;CAYnD"}

package/dist/src/util/working-table-iterable.js

@@ -0,0 +1,30 @@
+/**
+ * A reusable async iterable for working table data that can be iterated multiple times.
+ * Similar to CachedIterable but for runtime-generated working table data.
+ * Used primarily in recursive CTE execution where the working table needs to be
+ * accessed multiple times during recursive iterations.
+ */
+export class WorkingTableIterable {
+    rows;
+    rctx;
+    rowDescriptor;
+    constructor(rows, rctx, rowDescriptor) {
+        this.rows = rows;
+        this.rctx = rctx;
+        this.rowDescriptor = rowDescriptor;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (const row of this.rows) {
+            // Set up context for this row using the CTE row descriptor
+            this.rctx.context.set(this.rowDescriptor, () => row);
+            try {
+                yield row;
+            }
+            finally {
+                // Clean up context
+                this.rctx.context.delete(this.rowDescriptor);
+            }
+        }
+    }
+}
+//# sourceMappingURL=working-table-iterable.js.map

package/dist/src/util/working-table-iterable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-table-iterable.js","sourceRoot":"","sources":["../../../src/util/working-table-iterable.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAEvB;IACA;IACA;IAHT,YACS,IAAW,EACX,IAAoB,EACpB,aAA4B;QAF5B,SAAI,GAAJ,IAAI,CAAO;QACX,SAAI,GAAJ,IAAI,CAAgB;QACpB,kBAAa,GAAb,aAAa,CAAe;IAClC,CAAC;IAEJ,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC5B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC7B,2DAA2D;YAC3D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;YACrD,IAAI,CAAC;gBACJ,MAAM,GAAG,CAAC;YACX,CAAC;oBAAS,CAAC;gBACV,mBAAmB;gBACnB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC9C,CAAC;QACF,CAAC;IACF,CAAC;CACD"}

package/dist/src/vtab/best-access-plan.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Modern, type-safe replacement for xBestIndex API
+ * Provides better type safety, clearer intent, and extensibility for future optimizations
+ */
+import { type SqlDataType, type SqlValue } from '../common/types.js';
+/**
+ * Constraint operators that can be pushed down to virtual tables
+ */
+export type ConstraintOp = '=' | '>' | '>=' | '<' | '<=' | 'MATCH' | 'LIKE' | 'GLOB' | 'IS NULL' | 'IS NOT NULL';
+/**
+ * Column metadata provided to virtual tables for planning
+ */
+export interface ColumnMeta {
+    /** Column index in the table */
+    index: number;
+    /** Column name */
+    name: string;
+    /** SQL type information */
+    type: SqlDataType;
+    /** Whether this column is part of the primary key */
+    isPrimaryKey: boolean;
+    /** Whether this column has a unique constraint */
+    isUnique: boolean;
+}
+/**
+ * A predicate constraint extracted from WHERE clause
+ */
+export interface PredicateConstraint {
+    /** Column index this constraint applies to */
+    columnIndex: number;
+    /** Constraint operator */
+    op: ConstraintOp;
+    /** Constant value if this is a column-constant comparison */
+    value?: SqlValue;
+    /** Whether this constraint can be used by the virtual table */
+    usable: boolean;
+}
+/**
+ * Ordering specification for ORDER BY clauses
+ */
+export interface OrderingSpec {
+    /** Column index to order by */
+    columnIndex: number;
+    /** True for descending order, false for ascending */
+    desc: boolean;
+    /** Whether NULL values should come first or last */
+    nullsFirst?: boolean;
+}
+/**
+ * Request object passed to getBestAccessPlan containing query planning information
+ */
+export interface BestAccessPlanRequest {
+    /** Column metadata for the table */
+    columns: readonly ColumnMeta[];
+    /** Extracted predicate constraints from WHERE clause */
+    filters: readonly PredicateConstraint[];
+    /** Required ordering that ancestor nodes need (ORDER BY) */
+    requiredOrdering?: readonly OrderingSpec[];
+    /** LIMIT value known at plan time */
+    limit?: number | null;
+    /** Estimated rows hint from planner (may be unknown) */
+    estimatedRows?: number;
+}
+/**
+ * Result object returned by getBestAccessPlan describing the chosen query plan
+ */
+export interface BestAccessPlanResult {
+    /** Which filters were handled by the virtual table (parallel to filters array) */
+    handledFilters: readonly boolean[];
+    /** Optional JavaScript filter function for residual predicates */
+    residualFilter?: (row: any) => boolean;
+    /** Estimated cost in arbitrary virtual CPU units */
+    cost: number;
+    /** Estimated number of rows this plan will return */
+    rows: number | undefined;
+    /** Ordering guaranteed by this access plan */
+    providesOrdering?: readonly OrderingSpec[];
+    /** Whether this plan guarantees unique rows (helps DISTINCT optimization) */
+    isSet?: boolean;
+    /** Free-text explanation for debugging */
+    explains?: string;
+}
+/**
+ * Builder class for constructing access plan results
+ */
+export declare class AccessPlanBuilder {
+    private result;
+    /**
+     * Create a full table scan access plan
+     */
+    static fullScan(estimatedRows: number): AccessPlanBuilder;
+    /**
+     * Create an equality match access plan (index seek)
+     */
+    static eqMatch(matchedRows: number, indexCost?: number): AccessPlanBuilder;
+    /**
+     * Create a range scan access plan
+     */
+    static rangeScan(estimatedRows: number, indexCost?: number): AccessPlanBuilder;
+    /**
+     * Set the estimated cost of this access plan
+     */
+    setCost(cost: number): this;
+    /**
+     * Set the estimated number of rows
+     */
+    setRows(rows: number | undefined): this;
+    /**
+     * Set which filters are handled by this plan
+     */
+    setHandledFilters(handledFilters: readonly boolean[]): this;
+    /**
+     * Set the ordering provided by this plan
+     */
+    setOrdering(ordering: readonly OrderingSpec[]): this;
+    /**
+     * Set whether this plan produces unique rows
+     */
+    setIsSet(isSet: boolean): this;
+    /**
+     * Set an explanation for debugging
+     */
+    setExplanation(explanation: string): this;
+    /**
+     * Set a residual filter function
+     */
+    setResidualFilter(filter: (row: any) => boolean): this;
+    /**
+     * Build the final access plan result
+     */
+    build(): BestAccessPlanResult;
+}
+/**
+ * Validation function for access plan results
+ * Throws if the plan violates basic contracts
+ */
+export declare function validateAccessPlan(request: BestAccessPlanRequest, result: BestAccessPlanResult): void;
+/**
+ * Helper to convert old IndexConstraint to new PredicateConstraint
+ * @deprecated Use direct PredicateConstraint construction instead
+ */
+export declare function convertIndexConstraint(constraint: any, // Old IndexConstraint type
+value?: SqlValue): PredicateConstraint;
+//# sourceMappingURL=best-access-plan.d.ts.map

package/dist/src/vtab/best-access-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-access-plan.d.ts","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"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"}