flatsql 1.1.0 → 1.4.4

package/README.md

@@ -74,6 +74,29 @@ FlatBuffer → Query (via virtual table) → FlatBuffer
 
 ## Runtime Choices & Performance Gates
 
+### SDN flow runtime contract
+
+Within an SDN module flow, FlatSQL always runs as a signed, pluggable WASM node.
+The exact same artifact bytes and hash run under the browser/JavaScript harness
+and WasmEdge. The pure TypeScript implementation is a library fallback and
+must not substitute for the FlatSQL node in an isomorphic flow.
+
+FlatSQL remains independently instantiated and addressable by its signed
+manifest and artifact hash. A flow bundle may carry those bytes, but a compiler
+must not statically fold FlatSQL into the consuming application module.
+
+The FlatSQL node owns SQL, tables, rows, indexes, compaction, snapshots, and
+reload semantics. Hosts provide only generic opaque byte persistence,
+shared-arena bounds checking, clocks/wakeups, network byte streams, and module
+lifecycle. They must not expose a FlatSQL service, `storage_engine_link`, or
+schema-aware row/query API.
+
+Every FlatSQL module input and output port supports both canonical SDS
+FlatBuffer and aligned-binary representations for the same schema identity.
+`PIV`/`TAB.WIRE_FORMAT` selects per frame. Aligned frames are transient
+shared-memory views; durable, network, and fallback records remain canonical
+size-prefixed FlatBuffers.
+
 - Production should prefer the SQLite-backed native/WASM path (`initFlatSQL` → `FlatSQL` → `createDatabase`). The pure TypeScript `FlatSQLDatabase` is preserved only as an explicit fallback/reference implementation for environments that cannot load the WASM module.
 - Standalone deployments use the C++ WASI reactor at `flatsql/wasi.wasm`. Browser hosts load it through `flatsql/standalone`, while Node/WasmEdge hosts use a resident runner from `flatsql/standalone/wasmedge`.
 - Artifact-builder cache behavior belongs to C++: query templates, result-cache keys, invalidation generation, hit/miss counters, SQL execution, and raw FlatBuffer lookup all live in the WASM database instance. JavaScript only marshals bytes and fills host capability gaps.
@@ -459,14 +482,29 @@ const back = sdm.fromECEF(ecef.x, ecef.y, ecef.z);
 
 ## SQL Support
 
+FlatSQL ships two query engines. The WASM engine (`initFlatSQL()`) embeds
+SQLite and speaks full SQL. The pure-JS engine (`FlatSQLDatabase`, used where a
+WASM instance is not available) implements the focused subset below.
+
+### Fail-closed guarantee
+
+Both engines reject what they cannot execute. In particular the JS engine
+**throws** on a `WHERE`, `ORDER BY`, or `LIMIT` clause its grammar does not
+understand. It never falls back to an unfiltered scan: a caller that asks for a
+subset must get that subset or an error, never the whole table with no
+indication that the filter was dropped.
+
 ### Supported
 
 - `SELECT` with column selection
-- `WHERE` with `=`, `<`, `>`, `<=`, `>=`, `BETWEEN`, `LIKE`, `AND`, `OR`
-- `ORDER BY` (ASC/DESC)
+- `WHERE` with `=`, `!=`/`<>`, `<`, `>`, `<=`, `>=`, `BETWEEN`, `IN`, `LIKE`,
+  `IS NULL`, and `AND` / `OR` / `NOT` / parentheses
+- `LIKE` with `%` and `_` wildcards, ASCII case-insensitive (the SQLite default)
+- `ORDER BY` (ASC/DESC, multiple terms)
 - `LIMIT` and `OFFSET`
-- `COUNT(*)` aggregate
-- Index-accelerated queries on `(id)` and `(key)` columns
+- `COUNT(*)` aggregate (WASM engine)
+- Index-accelerated queries on `(id)` and `(key)` columns, including as one
+  conjunct of a larger `AND` predicate
 
 ### Not Supported
 

package/dist/core/database.d.ts

@@ -31,9 +31,7 @@ export declare class FlatSQLDatabase {
     getStorageBytes(): number;
     query(sql: string): QueryResult;
     private parseSQL;
-    private parseValue;
     private enforceRateLimit;
-    private evaluateCondition;
     getTableDef(tableName: string): TableDef | undefined;
     listTables(): string[];
     exportData(): Uint8Array;
@@ -44,4 +42,45 @@ export declare class FlatSQLDatabase {
         indexes: string[];
     }[];
 }
+export interface OrderByTerm {
+    column: string;
+    descending: boolean;
+}
+type ComparisonOperator = '=' | '!=' | '<>' | '<' | '>' | '<=' | '>=';
+export type WhereNode = {
+    kind: 'and';
+    children: WhereNode[];
+} | {
+    kind: 'or';
+    children: WhereNode[];
+} | {
+    kind: 'not';
+    child: WhereNode;
+} | {
+    kind: 'cmp';
+    column: string;
+    operator: ComparisonOperator;
+    value: any;
+} | {
+    kind: 'between';
+    column: string;
+    minValue: any;
+    maxValue: any;
+    negated: boolean;
+} | {
+    kind: 'in';
+    column: string;
+    values: any[];
+    negated: boolean;
+} | {
+    kind: 'like';
+    column: string;
+    matcher: RegExp;
+    negated: boolean;
+} | {
+    kind: 'isNull';
+    column: string;
+    negated: boolean;
+};
+export {};
 //# sourceMappingURL=database.d.ts.map

package/dist/core/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/core/database.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAe,MAAM,oBAAoB,CAAC;AAS3E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAEhD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,UAAU,CAAC;CACzE;AAED,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,QAAQ,CAAqB;IAGrC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAgB;gBAE3B,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,OAAO,GAAE,eAAoB;IAmB/F,MAAM,CAAC,UAAU,CACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,GAAE,MAAkB,EACxB,OAAO,GAAE,eAAoB,GAC5B,eAAe;IAMlB,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM;IAW5D,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,GAAG,MAAM;IAUhE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,EAAE;IAStE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IASxD,eAAe,IAAI,MAAM;IAQzB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAsF/B,OAAO,CAAC,QAAQ;IAoDhB,OAAO,CAAC,UAAU;IAkClB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,iBAAiB;IAqBzB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAKpD,UAAU,IAAI,MAAM,EAAE;IAKtB,UAAU,IAAI,UAAU;IAKxB,SAAS,IAAI,cAAc;IAK3B,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE;CAO5E"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/core/database.ts"],"names":[],"mappings":"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"}