@nshiab/simple-data-analysis-core 2.0.5 → 2.0.7

package/llms.txt

@@ -3,7 +3,7 @@
 > Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.
 
 - Package: `@nshiab/simple-data-analysis-core`
-- Version: `2.0.5`
+- Version: `2.0.7`
 
 Install with Deno: `deno add jsr:@nshiab/simple-data-analysis-core`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshiab/simple-data-analysis-core",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.",
   "keywords": [
     "data-analysis",

package/script/class/Simple.d.ts

@@ -18,9 +18,15 @@ export default class Simple {
      */
     typesToLog: boolean;
     /**
-     * The maximum number of characters to display for text-based cells. If undefined, the entire text is shown.
+     * The maximum number of characters to display for text and stringified nested cells, including the truncation marker. This does not control column width. Set to Infinity to show the entire text.
      *
-     * @defaultValue `undefined`
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ charsToLog: 150 });
+     * await sdb.newTable().loadArray([{ text: "x".repeat(200) }]).log();
+     * ```
+     *
+     * @defaultValue `75`
      */
     charsToLog: number | undefined;
     /**

package/script/class/Simple.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Simple.d.ts","sourceRoot":"","sources":["../../src/class/Simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;OAEG;IACH,EAAE,EAAG,cAAc,CAAC;IACpB;;OAEG;IACH,UAAU,EAAG,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,EAAG,CACT,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;KACrB,KACE,OAAO,CACR;QACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,EAAE,GACD,IAAI,CACP,CAAC;gBAGA,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;KACjB;CAOT"}
+{"version":3,"file":"Simple.d.ts","sourceRoot":"","sources":["../../src/class/Simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;OAUG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;OAEG;IACH,EAAE,EAAG,cAAc,CAAC;IACpB;;OAEG;IACH,UAAU,EAAG,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,EAAG,CACT,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;KACrB,KACE,OAAO,CACR;QACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,EAAE,GACD,IAAI,CACP,CAAC;gBAGA,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;KACjB;CAOT"}

package/script/class/Simple.js

@@ -30,9 +30,15 @@ class Simple {
             value: void 0
         });
         /**
-         * The maximum number of characters to display for text-based cells. If undefined, the entire text is shown.
+         * The maximum number of characters to display for text and stringified nested cells, including the truncation marker. This does not control column width. Set to Infinity to show the entire text.
          *
-         * @defaultValue `undefined`
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ charsToLog: 150 });
+         * await sdb.newTable().loadArray([{ text: "x".repeat(200) }]).log();
+         * ```
+         *
+         * @defaultValue `75`
          */
         Object.defineProperty(this, "charsToLog", {
             enumerable: true,
@@ -102,7 +108,7 @@ class Simple {
             value: void 0
         });
         this.rowsToLog = options.rowsToLog ?? 10;
-        this.charsToLog = options.charsToLog;
+        this.charsToLog = options.charsToLog ?? 75;
         this.typesToLog = options.typesToLog ?? false;
         this.defaultTableName = false;
     }

package/script/class/SimpleDB.d.ts

@@ -36,6 +36,73 @@ import Simple from "./Simple.js";
  */
 export default class SimpleDB<Table extends SimpleTable = SimpleTable> extends Simple {
     #private;
+    /**
+     * The operator syntax used by expressions and custom queries in this database.
+     * `"js"` translates JavaScript-style operators (`&&`, `||`, `==`, `===`,
+     * `!==`) and null comparisons within SQL expressions. It does not evaluate
+     * arbitrary JavaScript. `||` remains concatenation when string literals, list
+     * literals, explicit text casts, or `concat()` results make that intent clear.
+     * Otherwise `||` becomes OR; column types are not inferred. Use `concat()`
+     * when concatenation would otherwise be ambiguous, such as `first || last`.
+     * `"sql"` passes SQL through unchanged, including `||` and null comparisons.
+     * Choose the syntax when constructing the database; it applies to all tables.
+     *
+     * @defaultValue `"js"`
+     * @category Properties
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ expressionSyntax: "js" }); // The default mode
+     * // || becomes SQL OR: keep rows where at least one condition is true.
+     * await sdb.newTable().loadArray([{ active: true, admin: false }])
+     *   .filter("active || admin").log();
+     * ```
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ expressionSyntax: "js" });
+     * // && becomes SQL AND: both conditions must be true.
+     * // === becomes SQL =: compare the age with 18.
+     * await sdb.newTable().loadArray([{ active: true, age: 18 }])
+     *   .filter("active && age === 18").log();
+     * ```
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ expressionSyntax: "js" });
+     * // SQL AND and OR also work in JS mode; they pass through unchanged.
+     * // Keep active adults, or anyone who is an admin.
+     * await sdb.newTable().loadArray([{ active: true, age: 18, admin: false }])
+     *   .filter("(active AND age >= 18) OR admin").log();
+     * ```
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ expressionSyntax: "js" });
+     * // Bare column names do not establish concatenation. Use concat() explicitly.
+     * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
+     *   .addColumn("name", "string", "concat(first, ' ', last)").log();
+     * ```
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB(); // JS mode is the default
+     * // The string literal ' ' makes concatenation clear, so both || stay unchanged.
+     * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
+     *   .addColumn("name", "string", "first || ' ' || last").log();
+     * ```
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ expressionSyntax: "sql" });
+     * // SQL mode preserves || as concatenation: the name becomes "Jane Doe".
+     * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
+     *   .addColumn("name", "string", "first || ' ' || last").log();
+     * ```
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ expressionSyntax: "sql" });
+     * // Use SQL AND and OR for logical conditions; && and || are not translated.
+     * // Both active and adult must be true, unless admin is true.
+     * await sdb.newTable().loadArray([{ active: true, age: 18, admin: false }])
+     *   .filter("(active AND age >= 18) OR admin").log();
+     * ```
+     */
+    readonly expressionSyntax: "js" | "sql";
     /**
      * Whether to log each SQL statement immediately before execution.
      *
@@ -255,9 +322,10 @@ export default class SimpleDB<Table extends SimpleTable = SimpleTable> extends S
      * @param options.readOnly - Opens an existing DuckDB file read-only. Defaults to false. Requires a file and cannot be combined with overwrite.
      * @param options.logDuration - A flag indicating whether to log the total execution duration.
      * @param options.rowsToLog - The number of rows to display when logging a table.
-     * @param options.charsToLog - The maximum number of characters to display for text-based cells.
+     * @param options.charsToLog - The maximum characters to display for text and stringified nested cells, including truncation markers (default: 75). Independent of column width. Use Infinity for unlimited text.
      * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
      * @param options.cacheVerbose - Whether to log cache hits and misses, code and input changes, TTL status, and cache read/write timing.
+     * @param options.expressionSyntax - Operator syntax for expressions and custom queries: `"js"` (default) translates JavaScript-style operators in SQL expressions; `"sql"` preserves SQL unchanged.
      * @param options.logSQL - A flag indicating whether to log SQL immediately before execution.
      * @param options.explainSQL - A flag indicating whether to log DuckDB query plans for supported statements.
      * @param options.duckDbCache - A flag indicating whether to use DuckDB's external file cache.
@@ -283,6 +351,7 @@ export default class SimpleDB<Table extends SimpleTable = SimpleTable> extends S
         charsToLog?: number;
         typesToLog?: boolean;
         cacheVerbose?: boolean;
+        expressionSyntax?: "js" | "sql";
         logSQL?: boolean;
         explainSQL?: boolean;
         duckDbCache?: boolean | null;
@@ -300,6 +369,7 @@ export default class SimpleDB<Table extends SimpleTable = SimpleTable> extends S
     start(): Promise<SimpleDB>;
     /**
      * Creates a new SimpleTable instance within the database.
+     * The name must be unique among registered tables, ignoring ASCII letter case.
      *
      * @param name - The name of the new table. If not provided, a default name is generated (e.g., "table1").
      * @returns A new table instance.
@@ -486,6 +556,7 @@ export default class SimpleDB<Table extends SimpleTable = SimpleTable> extends S
     }[]>;
     /**
      * Executes a custom SQL query directly against the DuckDB instance.
+     * With the default `SimpleDB.expressionSyntax: "js"`, queries support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Queries run in UTC. When data is returned, temporal values use the same
      * JavaScript representations as `SimpleTable.getData()`.
      *

package/script/class/SimpleDB.d.ts.map

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

package/script/class/SimpleDB.js

@@ -127,9 +127,10 @@ class SimpleDB extends Simple_js_1.default {
      * @param options.readOnly - Opens an existing DuckDB file read-only. Defaults to false. Requires a file and cannot be combined with overwrite.
      * @param options.logDuration - A flag indicating whether to log the total execution duration.
      * @param options.rowsToLog - The number of rows to display when logging a table.
-     * @param options.charsToLog - The maximum number of characters to display for text-based cells.
+     * @param options.charsToLog - The maximum characters to display for text and stringified nested cells, including truncation markers (default: 75). Independent of column width. Use Infinity for unlimited text.
      * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
      * @param options.cacheVerbose - Whether to log cache hits and misses, code and input changes, TTL status, and cache read/write timing.
+     * @param options.expressionSyntax - Operator syntax for expressions and custom queries: `"js"` (default) translates JavaScript-style operators in SQL expressions; `"sql"` preserves SQL unchanged.
      * @param options.logSQL - A flag indicating whether to log SQL immediately before execution.
      * @param options.explainSQL - A flag indicating whether to log DuckDB query plans for supported statements.
      * @param options.duckDbCache - A flag indicating whether to use DuckDB's external file cache.
@@ -149,6 +150,78 @@ class SimpleDB extends Simple_js_1.default {
     constructor(options = {}) {
         super(options);
         _SimpleDB_instances.add(this);
+        /**
+         * The operator syntax used by expressions and custom queries in this database.
+         * `"js"` translates JavaScript-style operators (`&&`, `||`, `==`, `===`,
+         * `!==`) and null comparisons within SQL expressions. It does not evaluate
+         * arbitrary JavaScript. `||` remains concatenation when string literals, list
+         * literals, explicit text casts, or `concat()` results make that intent clear.
+         * Otherwise `||` becomes OR; column types are not inferred. Use `concat()`
+         * when concatenation would otherwise be ambiguous, such as `first || last`.
+         * `"sql"` passes SQL through unchanged, including `||` and null comparisons.
+         * Choose the syntax when constructing the database; it applies to all tables.
+         *
+         * @defaultValue `"js"`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ expressionSyntax: "js" }); // The default mode
+         * // || becomes SQL OR: keep rows where at least one condition is true.
+         * await sdb.newTable().loadArray([{ active: true, admin: false }])
+         *   .filter("active || admin").log();
+         * ```
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ expressionSyntax: "js" });
+         * // && becomes SQL AND: both conditions must be true.
+         * // === becomes SQL =: compare the age with 18.
+         * await sdb.newTable().loadArray([{ active: true, age: 18 }])
+         *   .filter("active && age === 18").log();
+         * ```
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ expressionSyntax: "js" });
+         * // SQL AND and OR also work in JS mode; they pass through unchanged.
+         * // Keep active adults, or anyone who is an admin.
+         * await sdb.newTable().loadArray([{ active: true, age: 18, admin: false }])
+         *   .filter("(active AND age >= 18) OR admin").log();
+         * ```
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ expressionSyntax: "js" });
+         * // Bare column names do not establish concatenation. Use concat() explicitly.
+         * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
+         *   .addColumn("name", "string", "concat(first, ' ', last)").log();
+         * ```
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB(); // JS mode is the default
+         * // The string literal ' ' makes concatenation clear, so both || stay unchanged.
+         * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
+         *   .addColumn("name", "string", "first || ' ' || last").log();
+         * ```
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ expressionSyntax: "sql" });
+         * // SQL mode preserves || as concatenation: the name becomes "Jane Doe".
+         * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
+         *   .addColumn("name", "string", "first || ' ' || last").log();
+         * ```
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ expressionSyntax: "sql" });
+         * // Use SQL AND and OR for logical conditions; && and || are not translated.
+         * // Both active and adult must be true, unless admin is true.
+         * await sdb.newTable().loadArray([{ active: true, age: 18, admin: false }])
+         *   .filter("(active AND age >= 18) OR admin").log();
+         * ```
+         */
+        Object.defineProperty(this, "expressionSyntax", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * Whether to log each SQL statement immediately before execution.
          *
@@ -461,6 +534,11 @@ class SimpleDB extends Simple_js_1.default {
             writable: true,
             value: SimpleTable_js_1.default
         });
+        if (options.expressionSyntax !== undefined &&
+            !["js", "sql"].includes(options.expressionSyntax)) {
+            throw new Error('expressionSyntax must be "js" or "sql".');
+        }
+        this.expressionSyntax = options.expressionSyntax ?? "js";
         this.file = options.file ?? ":memory:";
         this.logSQL = options.logSQL ?? false;
         this.explainSQL = options.explainSQL ?? false;
@@ -513,6 +591,7 @@ class SimpleDB extends Simple_js_1.default {
     }
     /**
      * Creates a new SimpleTable instance within the database.
+     * The name must be unique among registered tables, ignoring ASCII letter case.
      *
      * @param name - The name of the new table. If not provided, a default name is generated (e.g., "table1").
      * @returns A new table instance.
@@ -766,6 +845,7 @@ class SimpleDB extends Simple_js_1.default {
     }
     /**
      * Executes a custom SQL query directly against the DuckDB instance.
+     * With the default `SimpleDB.expressionSyntax: "js"`, queries support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Queries run in UTC. When data is returned, temporal values use the same
      * JavaScript representations as `SimpleTable.getData()`.
      *