@quereus/quereus 0.1.0

package/README.md

@@ -0,0 +1,228 @@
+# Quereus - A TypeScript SQL Query Processor
+
+<img src="docs/images/Quereus_colored_wide.svg" alt="Quereus Logo" height="150">
+
+Quereus is a feature-complete SQL query processor, inspired by SQLite but specifically designed for efficient in-memory data processing with a strong emphasis on the **virtual table** interface. It provides rich SQL query and constraint capabilities (joins, aggregates, subqueries, CTEs, window functions, constraints) over data sources exposed via the virtual table mechanism. Quereus has no persistent file storage, though one could be built as a virtual table module.
+
+## Project Goals
+
+*   **Virtual Table Centric**: Provide a robust and flexible virtual table API as the primary means of interacting with data sources. All tables are virtual tables.
+*   **In-Memory Focus**: Includes a comprehensive in-memory virtual table implementation (`MemoryTable`) with support for transactions and savepoints.
+*   **TypeScript & Modern JS**: Leverage TypeScript's type system and modern JavaScript features and idioms.
+*   **Async VTab Operations**: Virtual table data operations (reads/writes) are asynchronous. Cursors are implemented as async iterables.
+*   **Cross-Platform**: Target diverse Javascript runtime environments, including Node.js, browser, and React Native.
+*   **Minimal Dependencies**: Avoid heavy external dependencies where possible.
+*   **SQL Compatibility**: Comprehensive support for modern SQL features including joins, window functions, subqueries, CTEs, constraints, views, and advanced DML/DDL operations.
+*   **Key-Based Addressing**: All tables are addressed by their defined Primary Key. The concept of a separate, implicit `rowid` for addressing rows is not used (similar to SQLite's `WITHOUT ROWID` tables being the default and only mode).
+*   **Third Manifesto Friendly**: Embraces some of the principles of the [Third Manifesto](https://www.dcs.warwick.ac.uk/~hugh/TTM/DTATRM.pdf), such as allowing for empty keys. Utilizes algebraic planning.
+
+## Architecture Overview
+
+Quereus is built on a modern architecture based on partially immutable PlanNodes and an Instruction-based runtime with robust attribute-based context system.
+
+1.  **SQL Input**: The process starts with a SQL query string.
+2.  **Parser (`src/parser`)**:
+    *   **Lexer (`lexer.ts`)**: Tokenizes the raw SQL string.
+    *   **Parser (`parser.ts`)**: Builds an Abstract Syntax Tree (AST).
+3.  **Planner (`src/planner`)**:
+    *   Traverses the AST to construct a tree of immutable `PlanNode` objects representing the logical query structure.
+    *   Handles Common Table Expressions (CTEs) and Subqueries by converting them into relational `PlanNode`s.
+    *   Resolves table and function references using the Schema Manager.
+    *   Performs query planning, incorporating virtual table `xBestIndex` method and table schema statistics.
+    *   **Optimizer (`src/planner/optimizer`)**: Performs query optimization, including join reordering, predicate pushdown, and other optimizations.
+4.  **Runtime (`src/runtime`)**:
+    *   **Emitters (`src/runtime/emitters.ts`, `src/runtime/emit/`)**: Translate `PlanNode`s into a graph of `Instruction` objects.
+    *   **Scheduler (`src/runtime/scheduler.ts`)**: Manages the execution flow of the `Instruction` graph.
+    *   **Instructions**: JavaScript functions that operate on `RuntimeValue`s (which can be `SqlValue` or `AsyncIterable<Row>`). Async parameters are awaited.
+    *   Invokes virtual table methods (e.g., `xQuery` which returns `AsyncIterable<Row>`, `xUpdate`) to interact with data.
+    *   Calls User-Defined Functions (UDFs) and aggregate functions.
+    *   Handles transaction and savepoint control.
+5.  **Virtual Tables (`src/vtab`)**:
+    *   The core data interface. Modules implement `VirtualTableModule`.
+    *   `MemoryTable` (`vtab/memory/table.ts`) is a key implementation using `digitree`.
+6.  **Schema Management (`src/schema`)**: Manages schemas, tables, columns, functions.
+7.  **User-Defined Functions (`src/func`)**: Support for custom JS functions in SQL.
+8.  **Core API (`src/core`)**: `Database`, `Statement` classes.
+
+## Source File Layout
+
+The project is organized into the following main directories:
+
+*   `src/common`: Foundational types, constants, and error classes.
+*   `src/core`: High-level API classes (`Database`, `Statement`).
+*   `src/parser`: SQL lexing, parsing, and AST definitions.
+*   `src/planner`: Building and optimizing `PlanNode` trees from AST.
+*   `src/runtime`: Emission, scheduling, and execution of runtime `Instruction`s.
+*   `src/schema`: Management of database schemas.
+*   `src/vtab`: Virtual table interface and implementations (including `memory`).
+*   `src/func`: User-defined functions.
+*   `src/util`: General utility functions.
+*   `docs`: Project documentation.
+
+## Logging
+
+Quereus uses the [`debug`](https://github.com/debug-js/debug) library for internal logging. This allows for fine-grained control over log output based on namespaces, which correspond to the different modules of the system (e.g., `planner`, `runtime`, `vtab:memory`).
+
+To enable logging during development or troubleshooting, set the `DEBUG` environment variable. Examples:
+
+```bash
+# Enable all Quereus logs
+DEBUG=quereus:*
+
+# Enable all virtual table logs
+DEBUG=quereus:vtab:*
+
+# Enable VDBE runtime logs and any warnings/errors from other modules
+DEBUG=quereus:runtime,quereus:*:warn,quereus:*:error
+
+# Enable everything EXCEPT verbose runtime logs
+DEBUG=*,-quereus:runtime
+```
+
+### Developer Usage
+
+To add logging within a module:
+
+1.  **Import the logger factory:**
+    ```typescript
+    import { createLogger } from '../common/logger.js'; // Adjust path as needed
+
+    const log = createLogger('my-module:sub-feature');
+    ```
+
+2.  **Log messages:** Use the logger instance like `console.log`, utilizing format specifiers (`%s`, `%d`, `%j`, `%O`) for better performance and readability.
+    ```typescript
+    log('Processing item ID %d', itemId);
+    log('Current state: %O', complexObject);
+    ```
+
+3.  **(Optional) Create specialized loggers for levels:** You can use `.extend()` for specific levels like warnings or errors, which allows finer control via the `DEBUG` variable.
+    ```typescript
+    const warnLog = log.extend('warn');
+    const errorLog = log.extend('error');
+
+    warnLog('Potential issue detected: %s', issueDescription);
+    if (errorCondition) {
+      errorLog('Operation failed: %O', errorObject);
+      // It's often still good practice to throw an actual Error here
+    }
+    ```
+
+## Documentation
+
+* [Usage Guide](docs/usage.md): Detailed usage examples and API reference
+* [SQL Reference Guide](docs/sql.md): Detailed SQL reference guide
+* [Functions](docs/functions.md): Details on the built-in functions
+* [Window Function Architecture](docs/window-functions.md): Details on the window function architecture and implementation.
+* [Memory Tables](docs/memory-table.md): Implementation details of the built-in MemoryTable module
+* [Date/Time Handling](docs/datetime.md): Details on date/time parsing, functions, and the Temporal API.
+* [Runtime](docs/runtime.md): Details on the runtime and opcodes.
+* [Error Handling](docs/error.md): Details on the error handling and status codes.
+* [TODO List](docs/todo.md): Planned features and improvements
+
+## Key Design Decisions
+
+*   **Federated / VTab-Centric**: All tables are virtual tables.
+*   **Async Core**: Core operations are asynchronous. Cursors are `AsyncIterable<Row>`.
+*   **Key-Based Addressing**: Rows are identified by their defined Primary Key. No separate implicit `rowid`.
+*   **Relational Orthogonality**: Any statement that results in a relation can be used anywhere that expects a relation value, including mutating statements with RETURNING clauses.
+*   **JavaScript Types**: Uses standard JavaScript types (`number`, `string`, `bigint`, `boolean`, `Uint8Array`, `null`) internally.
+*   **Object-Based API**: Uses classes (`Database`, `Statement`) to represent resources with lifecycles, rather than handles.
+*   **Transient Schema**: Schema information is primarily in-memory; persistence is not a goal. Emission of schema SQL export is supported.
+*   **Bags vs Sets Distinction**: Explicit type-level distinction between relations that guarantee unique rows (sets) and those that allow duplicates (bags), enabling sophisticated optimizations and maintaining algebraic correctness in line with Third Manifesto principles.
+*   **Attribute-Based Context System**: Robust column reference resolution using stable attribute IDs eliminates architectural fragilities and provides deterministic context lookup across plan transformations.
+
+## Major variations from SQLite
+
+*   Uses `CREATE TABLE ... USING module(...)` syntax (no CREATE VIRTUAL TABLE).
+*   **Default NOT NULL Columns**: Following Third Manifesto principles, columns default to NOT NULL unless explicitly specified otherwise. This behavior can be controlled via `pragma default_column_nullability = 'nullable'` to restore SQL standard behavior. This design choice helps avoid the "billion-dollar mistake" of NULL by default.
+*   `PRAGMA default_vtab_module` can be used.
+*   Supports `ASC`/`DESC` qualifiers on PRIMARY KEY column definitions.
+*   Async core execution.
+*   **No Rowids / `WITHOUT ROWID` by Default**: All tables are addressed by their Primary Key, similar to SQLite's `WITHOUT ROWID` tables being the only mode. The `WITHOUT ROWID` clause is not used.
+*   **Implicit Primary Key Behavior**: When no explicit PRIMARY KEY is defined, Quereus includes all columns in the primary key. This differs from SQLite which uses the first INTEGER column or an implicit rowid. This design choice ensures predictable behavior and avoids potential confusion with SQLite's implicit rules.
+*   No plans for:
+    *   Triggers
+    *   Persistent file storage (can be a VTab module)
+
+## Current Status
+
+Quereus is a feature-complete SQL query processor with a modern planner and instruction-based runtime architecture. The engine successfully handles complex SQL workloads including joins, window functions, subqueries, CTEs, constraints, and comprehensive DML/DDL operations.
+
+**Current capabilities include:**
+*   **Complete JOIN support** - INNER, LEFT, RIGHT, CROSS joins with proper NULL padding
+*   **Advanced window functions** - Ranking, aggregates, and frame specifications
+*   **Full constraint system** - NOT NULL, CHECK constraints with operation-specific triggers  
+*   **Comprehensive subqueries** - Scalar, correlated, EXISTS, and IN subqueries
+*   **Relational orthogonality** - INSERT/UPDATE/DELETE with RETURNING can be used as table sources
+*   **Complete set operations** - UNION, INTERSECT, EXCEPT with proper deduplication
+*   **Robust transaction support** - Multi-level savepoints and rollback
+*   **Rich built-in function library** - Scalar, aggregate, window, JSON, and date/time functions
+
+**Titan Optimizer Implementation Status:**
+*   ✅ **Phase 0 - Groundwork**: Foundational infrastructure complete with cost models, constraint analysis, shared caching utilities, and development standards
+*   ✅ **xBestIndex Refactor**: Modern type-safe BestAccessPlan API replacing legacy SQLite-style interfaces  
+*   ✅ **Phase 1 - Core Framework**: Complete rule registration system, trace framework, physical property utilities, statistics provider abstraction, emitter metadata, and golden plan test harness
+*   ✅ **Phase 2 - Cache & Visualize**: Intelligent materialization advisory, async stream utilities, and PlanViz CLI tool for visual plan inspection
+*   ✅ **Phase 2.5 - Generic Tree Rewriting**: Abstract `withChildren()` method eliminating manual node handling and preserving attribute IDs
+*   ✅ **Phase 3 - Constant Folding**: Functional safety flags, runtime-based evaluation, and expression boundary optimization
+*   🔄 **Phase 1.5 - Access Path Selection**: Seek/range scan infrastructure and access path selection rules  
+*   📋 **Upcoming**: Advanced optimization rules, join algorithms, and performance tooling
+
+**Current development focus:**
+*   **Access Path Selection** - Physical seek/range scan nodes and optimization rules
+*   **Phase 3 Polishing** - Plan validation, constant folding, execution metrics, and development tooling
+*   **Advanced Optimization Rules** - Predicate pushdown, join reordering, and cost-based transformations
+
+See the [Titan Optimizer Documentation](docs/titan-optimizer.md) for detailed implementation progress and [Optimizer Conventions](docs/optimizer-conventions.md) for the rules and conventions used, as well as [Planner framework README](src/planner/framework/README.md) for optimizer framework details.
+[TODO List](docs/todo.md) has remaining priorities.
+
+## Testing
+
+The tests are located in `test/*.spec.ts` and are driven by Mocha with ts-node/esm.
+
+```bash
+yarn test
+```
+
+Quereus employs a multi-faceted testing strategy:
+
+1.  **SQL Logic Tests (`test/logic/`)**:
+    *   Inspired by SQLite's own testing methodology.
+    *   Uses simple text files (`*.sqllogic`) containing SQL statements and their expected JSON results (using `→` marker) or expected error messages (using `-- error:` directive).
+    *   Driven by a Mocha test runner (`test/logic.spec.ts`) that executes the SQL against a fresh `Database` instance for each file.
+    *   **Configurable Diagnostics**: On unexpected failures, the test runner provides clean error messages by default with optional detailed diagnostics controlled by environment variables:
+        *   `QUEREUS_TEST_VERBOSE=true` - Show execution progress during tests
+        *   `QUEREUS_TEST_SHOW_PLAN=true` - Include query plan in diagnostics
+        *   `QUEREUS_TEST_SHOW_PROGRAM=true` - Include instruction program in diagnostics
+        *   `QUEREUS_TEST_SHOW_STACK=true` - Include full stack trace in diagnostics
+        *   `QUEREUS_TEST_SHOW_TRACE=true` - Include execution trace in diagnostics
+    *   This helps pinpoint failures at the Parser, Planner, or Runtime layer while keeping output manageable.
+    *   Provides comprehensive coverage of SQL features: basic CRUD, complex expressions, all join types, window functions, aggregates, subqueries, CTEs, constraints, transactions, set operations, views, and error handling.
+
+2.  **Property-Based Tests (`test/property.spec.ts`)**:
+    *   Uses the `fast-check` library to generate a wide range of inputs for specific, tricky areas.
+    *   Focuses on verifying fundamental properties and invariants that should hold true across many different values.
+    *   Currently includes tests for:
+        *   **Collation Consistency**: Ensures `ORDER BY` results match the behavior of the `compareSqlValues` utility for `BINARY`, `NOCASE`, and `RTRIM` collations across various strings.
+        *   **Numeric Affinity**: Verifies that comparisons (`=`, `<`) in SQL handle mixed types (numbers, strings, booleans, nulls) consistently with SQLite's affinity rules, using `compareSqlValues` as the reference.
+        *   **JSON Roundtrip**: Confirms that arbitrary JSON values survive being processed by `json_quote()` and `json_extract('$')` without data loss or corruption.
+
+3.  **Performance Sentinels (Planned)**:
+    *   Micro-benchmarks for specific scenarios (e.g., bulk inserts, complex queries) to catch performance regressions.
+
+4.  **CI Integration (Planned)**:
+    *   Utilize GitHub Actions (or similar) to run test suites automatically, potentially with different configurations (quick checks, full runs, browser environment).
+
+This layered approach aims for broad coverage via the logic tests while using property tests to explore edge cases in specific subsystems more thoroughly.
+
+## Supported Built-in Functions
+
+*   **Scalar:** `lower`, `upper`, `length`, `substr`/`substring`, `abs`, `round`, `coalesce`, `nullif`, `like`, `glob`, `typeof`
+*   **Aggregate:** `count`, `sum`, `avg`, `min`, `max`, `group_concat`, `json_group_array`, `json_group_object`
+*   **Window Functions:** Complete implementation with `row_number`, `rank`, `dense_rank`, `ntile` (ranking); `count`, `sum`, `avg`, `min`, `max` with OVER clause (aggregates); Full frame specification support (`ROWS BETWEEN`, `UNBOUNDED PRECEDING/FOLLOWING`); `NULLS FIRST/LAST` ordering
+*   **Date/Time:** `date`, `time`, `datetime`, `julianday`, `strftime` (supports common formats and modifiers)
+*   **JSON:** `json_valid`, `json_type`, `json_extract`, `json_quote`, `json_array`, `json_object`, `json_insert`, `json_replace`, `json_set`, `json_remove`, `json_array_length`, `json_patch`
+*   **Query Analysis:** `query_plan`, `scheduler_program`, `execution_trace` (debugging and performance analysis)
+
+

package/dist/src/common/constants.d.ts

@@ -0,0 +1,49 @@
+export declare enum FunctionFlags {
+    UTF8 = 1,
+    DETERMINISTIC = 2048,
+    DIRECTONLY = 524288,
+    INNOCUOUS = 2097152
+}
+export declare enum VTabConfig {
+    CONSTRAINT_SUPPORT = 1,
+    INNOCUOUS = 2,
+    DIRECTONLY = 3,
+    USES_ALL_SCHEMAS = 4
+}
+export declare enum IndexConstraintOp {
+    EQ = 2,
+    GT = 4,
+    LE = 8,
+    LT = 16,
+    GE = 32,
+    MATCH = 64,
+    LIKE = 65,// Requires a LIKE implementation or delegation
+    GLOB = 66,// Requires a GLOB implementation or delegation
+    REGEXP = 67,// Requires a REGEXP implementation or delegation
+    NE = 68,
+    ISNOT = 69,
+    ISNOTNULL = 70,
+    ISNULL = 71,
+    IS = 72,
+    LIMIT = 73,
+    OFFSET = 74,
+    IN = 75,
+    FUNCTION = 150
+}
+/**
+ * Defines how to resolve a constraint conflict.
+ * These correspond to SQLite's ON CONFLICT clauses.
+ */
+export declare enum ConflictResolution {
+    ROLLBACK = 1,
+    ABORT = 2,// Default
+    FAIL = 3,
+    IGNORE = 4,
+    REPLACE = 5
+}
+export declare enum ChangesetOperation {
+    DELETE = 9,
+    INSERT = 18,
+    UPDATE = 23
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/common/constants.ts"],"names":[],"mappings":"AACA,oBAAY,aAAa;IACxB,IAAI,IAAI;IAIR,aAAa,OAAc;IAC3B,UAAU,SAAc;IACxB,SAAS,UAAc;CAEvB;AAGD,oBAAY,UAAU;IACrB,kBAAkB,IAAI;IACtB,SAAS,IAAI;IACb,UAAU,IAAI;IACd,gBAAgB,IAAI;CACpB;AAGD,oBAAY,iBAAiB;IAC5B,EAAE,IAAI;IACN,EAAE,IAAI;IACN,EAAE,IAAI;IACN,EAAE,KAAK;IACP,EAAE,KAAK;IACP,KAAK,KAAK;IACV,IAAI,KAAK,CAAE,+CAA+C;IAC1D,IAAI,KAAK,CAAE,+CAA+C;IAC1D,MAAM,KAAK,CAAE,iDAAiD;IAC9D,EAAE,KAAK;IACP,KAAK,KAAK;IACV,SAAS,KAAK;IACd,MAAM,KAAK;IACX,EAAE,KAAK;IACP,KAAK,KAAK;IACV,MAAM,KAAK;IACX,EAAE,KAAK;IACP,QAAQ,MAAM;CACd;AAED;;;GAGG;AACH,oBAAY,kBAAkB;IAC7B,QAAQ,IAAI;IACZ,KAAK,IAAI,CAAK,UAAU;IACxB,IAAI,IAAI;IACR,MAAM,IAAI;IACV,OAAO,IAAI;CACX;AAGD,oBAAY,kBAAkB;IAC7B,MAAM,IAAI;IACV,MAAM,KAAK;IACX,MAAM,KAAK;CACX"}

package/dist/src/common/constants.js

@@ -0,0 +1,62 @@
+// Constants for function flags (matching C API where sensible)
+export var FunctionFlags;
+(function (FunctionFlags) {
+    FunctionFlags[FunctionFlags["UTF8"] = 1] = "UTF8";
+    // UTF16LE = 2, // Decide if UTF16 support is needed internally
+    // UTF16BE = 3,
+    // UTF16 = 4,
+    FunctionFlags[FunctionFlags["DETERMINISTIC"] = 2048] = "DETERMINISTIC";
+    FunctionFlags[FunctionFlags["DIRECTONLY"] = 524288] = "DIRECTONLY";
+    FunctionFlags[FunctionFlags["INNOCUOUS"] = 2097152] = "INNOCUOUS";
+    // Add others if needed (SUBTYPE, etc.)
+})(FunctionFlags || (FunctionFlags = {}));
+// Constants for VTable configuration
+export var VTabConfig;
+(function (VTabConfig) {
+    VTabConfig[VTabConfig["CONSTRAINT_SUPPORT"] = 1] = "CONSTRAINT_SUPPORT";
+    VTabConfig[VTabConfig["INNOCUOUS"] = 2] = "INNOCUOUS";
+    VTabConfig[VTabConfig["DIRECTONLY"] = 3] = "DIRECTONLY";
+    VTabConfig[VTabConfig["USES_ALL_SCHEMAS"] = 4] = "USES_ALL_SCHEMAS";
+})(VTabConfig || (VTabConfig = {}));
+// Constants for VTable constraint operators
+export var IndexConstraintOp;
+(function (IndexConstraintOp) {
+    IndexConstraintOp[IndexConstraintOp["EQ"] = 2] = "EQ";
+    IndexConstraintOp[IndexConstraintOp["GT"] = 4] = "GT";
+    IndexConstraintOp[IndexConstraintOp["LE"] = 8] = "LE";
+    IndexConstraintOp[IndexConstraintOp["LT"] = 16] = "LT";
+    IndexConstraintOp[IndexConstraintOp["GE"] = 32] = "GE";
+    IndexConstraintOp[IndexConstraintOp["MATCH"] = 64] = "MATCH";
+    IndexConstraintOp[IndexConstraintOp["LIKE"] = 65] = "LIKE";
+    IndexConstraintOp[IndexConstraintOp["GLOB"] = 66] = "GLOB";
+    IndexConstraintOp[IndexConstraintOp["REGEXP"] = 67] = "REGEXP";
+    IndexConstraintOp[IndexConstraintOp["NE"] = 68] = "NE";
+    IndexConstraintOp[IndexConstraintOp["ISNOT"] = 69] = "ISNOT";
+    IndexConstraintOp[IndexConstraintOp["ISNOTNULL"] = 70] = "ISNOTNULL";
+    IndexConstraintOp[IndexConstraintOp["ISNULL"] = 71] = "ISNULL";
+    IndexConstraintOp[IndexConstraintOp["IS"] = 72] = "IS";
+    IndexConstraintOp[IndexConstraintOp["LIMIT"] = 73] = "LIMIT";
+    IndexConstraintOp[IndexConstraintOp["OFFSET"] = 74] = "OFFSET";
+    IndexConstraintOp[IndexConstraintOp["IN"] = 75] = "IN";
+    IndexConstraintOp[IndexConstraintOp["FUNCTION"] = 150] = "FUNCTION";
+})(IndexConstraintOp || (IndexConstraintOp = {}));
+/**
+ * Defines how to resolve a constraint conflict.
+ * These correspond to SQLite's ON CONFLICT clauses.
+ */
+export var ConflictResolution;
+(function (ConflictResolution) {
+    ConflictResolution[ConflictResolution["ROLLBACK"] = 1] = "ROLLBACK";
+    ConflictResolution[ConflictResolution["ABORT"] = 2] = "ABORT";
+    ConflictResolution[ConflictResolution["FAIL"] = 3] = "FAIL";
+    ConflictResolution[ConflictResolution["IGNORE"] = 4] = "IGNORE";
+    ConflictResolution[ConflictResolution["REPLACE"] = 5] = "REPLACE";
+})(ConflictResolution || (ConflictResolution = {}));
+// Constants for Changeset operations (matching C API)
+export var ChangesetOperation;
+(function (ChangesetOperation) {
+    ChangesetOperation[ChangesetOperation["DELETE"] = 9] = "DELETE";
+    ChangesetOperation[ChangesetOperation["INSERT"] = 18] = "INSERT";
+    ChangesetOperation[ChangesetOperation["UPDATE"] = 23] = "UPDATE";
+})(ChangesetOperation || (ChangesetOperation = {}));
+//# sourceMappingURL=constants.js.map

package/dist/src/common/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/common/constants.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,CAAN,IAAY,aASX;AATD,WAAY,aAAa;IACxB,iDAAQ,CAAA;IACR,+DAA+D;IAC/D,eAAe;IACf,aAAa;IACb,sEAA2B,CAAA;IAC3B,kEAAwB,CAAA;IACxB,iEAAuB,CAAA;IACvB,uCAAuC;AACxC,CAAC,EATW,aAAa,KAAb,aAAa,QASxB;AAED,qCAAqC;AACrC,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACrB,uEAAsB,CAAA;IACtB,qDAAa,CAAA;IACb,uDAAc,CAAA;IACd,mEAAoB,CAAA;AACrB,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB;AAED,4CAA4C;AAC5C,MAAM,CAAN,IAAY,iBAmBX;AAnBD,WAAY,iBAAiB;IAC5B,qDAAM,CAAA;IACN,qDAAM,CAAA;IACN,qDAAM,CAAA;IACN,sDAAO,CAAA;IACP,sDAAO,CAAA;IACP,4DAAU,CAAA;IACV,0DAAS,CAAA;IACT,0DAAS,CAAA;IACT,8DAAW,CAAA;IACX,sDAAO,CAAA;IACP,4DAAU,CAAA;IACV,oEAAc,CAAA;IACd,8DAAW,CAAA;IACX,sDAAO,CAAA;IACP,4DAAU,CAAA;IACV,8DAAW,CAAA;IACX,sDAAO,CAAA;IACP,mEAAc,CAAA;AACf,CAAC,EAnBW,iBAAiB,KAAjB,iBAAiB,QAmB5B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,kBAMX;AAND,WAAY,kBAAkB;IAC7B,mEAAY,CAAA;IACZ,6DAAS,CAAA;IACT,2DAAQ,CAAA;IACR,+DAAU,CAAA;IACV,iEAAW,CAAA;AACZ,CAAC,EANW,kBAAkB,KAAlB,kBAAkB,QAM7B;AAED,sDAAsD;AACtD,MAAM,CAAN,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC7B,+DAAU,CAAA;IACV,gEAAW,CAAA;IACX,gEAAW,CAAA;AACZ,CAAC,EAJW,kBAAkB,KAAlB,kBAAkB,QAI7B"}

package/dist/src/common/datatype.d.ts

@@ -0,0 +1,72 @@
+import type { Expression } from "../parser/ast.js";
+import type { DeepReadonly, SqlDataType } from "./types.js";
+export type TypeClass = 'scalar' | 'relation' | 'list' | 'void';
+export type BaseType = DeepReadonly<{
+    typeClass: TypeClass;
+}>;
+/**
+ * Type information for scalar values.
+ * This is used to determine the type of a scalar value, e.g., for a column reference or a literal.
+ */
+export type ScalarType = DeepReadonly<BaseType & {
+    typeClass: 'scalar';
+    /** The type affinity of the scalar value. */
+    affinity: SqlDataType;
+    /** The optional collation name of the scalar value. */
+    collationName?: string;
+    /** If nullable, null values are allowed and may be encountered in inference contexts too. */
+    nullable: boolean;
+    /** Indicates that it is inferred const, computed, or otherwise immutable.  Missing assumes false. */
+    isReadOnly?: boolean;
+    /** For literals or inferred constants, we can know the specific type */
+    datatype?: SqlDataType;
+}>;
+export type ColumnDef = {
+    name: string;
+    type: ScalarType;
+    /** The optional default value for the column. */
+    default?: Expression;
+    /** If true, the column is generated, not stored.  Absent = false. */
+    generated?: boolean;
+};
+export type ColRef = {
+    index: number;
+    /** If true, the column is sorted in descending order.  Absent = false. */
+    desc?: boolean;
+};
+/**
+ * Type information for relations.
+ * This is used to determine the type of a relation, e.g., for a table or a subquery.
+ * Foreign keys and externally referencing constraints are not part of the relation type as they are essentially database level.
+ */
+export type RelationType = DeepReadonly<BaseType & {
+    typeClass: 'relation';
+    isReadOnly: boolean;
+    /**
+     * If true, this relation is guaranteed to be a set (no duplicate rows).
+     * If false, this relation could be a bag (duplicate rows possible).
+     * This affects how certain operations (like sorting) handle the data.
+     */
+    isSet: boolean;
+    columns: ColumnDef[];
+    /** The unique keys of the relation (the primary key is arbitrarily the first one).
+     * Note that these may or may not be supported by indexes (normally they are), but by definition are unique.
+     * An empty key means the relation can have exactly 0 or 1 rows (TableDum and TableDee respectively).
+     */
+    keys: ColRef[][];
+    /** The row constraints of the relation - limited to the relation itself. */
+    rowConstraints: {
+        name?: string;
+        expr: Expression;
+    }[];
+}>;
+export type ListType = DeepReadonly<BaseType & {
+    typeClass: 'list';
+}>;
+export type VoidType = DeepReadonly<BaseType & {
+    typeClass: 'void';
+}>;
+export declare function isRelationType(type: BaseType): type is RelationType;
+export declare function isScalarType(type: BaseType): type is ScalarType;
+export declare function isListType(type: BaseType): type is ListType;
+//# sourceMappingURL=datatype.d.ts.map

package/dist/src/common/datatype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datatype.d.ts","sourceRoot":"","sources":["../../../src/common/datatype.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;IACnC,SAAS,EAAE,SAAS,CAAC;CACrB,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,GAAG;IAChD,SAAS,EAAE,QAAQ,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,EAAE,WAAW,CAAC;IACtB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,CAAC;IAClB,qGAAqG;IACrG,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,WAAW,CAAC;CAGvB,CAAC,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,IAAI,CAAC,EAAE,OAAO,CAAC;CACf,CAAA;AACD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,QAAQ,GAAG;IAClD,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjB,4EAA4E;IAC5E,cAAc,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC,CAAA;AAEF,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,GAAG;IAC9C,SAAS,EAAE,MAAM,CAAC;CAClB,CAAC,CAAA;AAEF,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,GAAG;IAC9C,SAAS,EAAE,MAAM,CAAC;CAClB,CAAC,CAAA;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,IAAI,YAAY,CAEnE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,IAAI,UAAU,CAE/D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,IAAI,QAAQ,CAE3D"}

package/dist/src/common/datatype.js

@@ -0,0 +1,10 @@
+export function isRelationType(type) {
+    return type.typeClass === 'relation';
+}
+export function isScalarType(type) {
+    return type.typeClass === 'scalar';
+}
+export function isListType(type) {
+    return type.typeClass === 'list';
+}
+//# sourceMappingURL=datatype.js.map

package/dist/src/common/datatype.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datatype.js","sourceRoot":"","sources":["../../../src/common/datatype.ts"],"names":[],"mappings":"AA2EA,MAAM,UAAU,cAAc,CAAC,IAAc;IAC5C,OAAO,IAAI,CAAC,SAAS,KAAK,UAAU,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAc;IAC1C,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAc;IACxC,OAAO,IAAI,CAAC,SAAS,KAAK,MAAM,CAAC;AAClC,CAAC"}

package/dist/src/common/errors.d.ts

@@ -0,0 +1,90 @@
+import { StatusCode } from './types.js';
+import type { Token } from '../parser/lexer.js';
+/**
+ * Base class for Quereus specific errors
+ * Provides location information and status code support
+ */
+export declare class QuereusError extends Error {
+    code: number;
+    cause?: Error;
+    line?: number;
+    column?: number;
+    constructor(message: string, code?: number, cause?: Error, line?: number, column?: number);
+}
+/**
+ * Parser-specific error that includes token information
+ * Used during SQL parsing to provide precise error locations
+ */
+export declare class ParseError extends QuereusError {
+    token: Token;
+    constructor(message: string, token: Token);
+}
+/**
+ * Error thrown when a database constraint is violated
+ */
+export declare class ConstraintError extends QuereusError {
+    constructor(message: string, code?: number);
+}
+/**
+ * Error thrown for SQL syntax issues
+ */
+export declare class SyntaxError extends QuereusError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the API is used incorrectly
+ */
+export declare class MisuseError extends QuereusError {
+    constructor(message?: string);
+}
+/**
+ * Helper function to throw a QuereusError with optional location information from AST nodes
+ * @param message Error message
+ * @param code Status code (defaults to ERROR)
+ * @param cause Optional underlying error
+ * @param astNode Optional AST node or object with location information
+ * @returns Never (always throws)
+ */
+export declare function quereusError(message: string, code?: StatusCode, cause?: Error, astNode?: {
+    loc?: {
+        start: {
+            line: number;
+            column: number;
+        };
+        end?: {
+            line: number;
+            column: number;
+        };
+    };
+}): never;
+/**
+ * Information about an error in the error chain
+ */
+export interface ErrorInfo {
+    message: string;
+    code?: number;
+    line?: number;
+    column?: number;
+    name: string;
+    stack?: string;
+}
+/**
+ * Recursively unwraps a QuereusError (or any Error) and its causes
+ * @param error The error to unwrap
+ * @returns Array of ErrorInfo objects, with the root error first
+ */
+export declare function unwrapError(error: Error): ErrorInfo[];
+/**
+ * Formats an error chain for display
+ * @param errorChain Array of ErrorInfo objects
+ * @param includeStack Whether to include stack traces
+ * @returns Formatted error message
+ */
+export declare function formatErrorChain(errorChain: ErrorInfo[], includeStack?: boolean): string;
+/**
+ * Gets the primary error info (the first error in the chain)
+ * @param error The error to analyze
+ * @returns ErrorInfo for the primary error
+ */
+export declare function getPrimaryError(error: Error): ErrorInfo;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAyB,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAkB3G;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,YAAY;IACpC,KAAK,EAAE,KAAK,CAAC;gBAER,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAKzC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACpC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAA8B;CAIjE;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY;gBAChC,OAAO,GAAE,MAA2B;CAKhD;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY;gBAChC,OAAO,GAAE,MAAqB;CAK1C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,UAA6B,EACnC,KAAK,CAAC,EAAE,KAAK,EACb,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE;QAAE,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GACrG,KAAK,CAQP;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAAE,CAyBrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,YAAY,GAAE,OAAe,GAAG,MAAM,CAuB/F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAMvD"}