csv-sql-engine 0.0.1 → 0.1.0

package/dist/csv/csv-text.d.ts

@@ -1,4 +1,3 @@
-import { type RequireExactlyOne } from 'type-fest';
 /**
  * Converts multiple rows of values into a CSV file string.
  *
@@ -11,21 +10,6 @@ export declare function convertRowsToCsv(rows: ReadonlyArray<ReadonlyArray<strin
  * @category CSV
  */
 export declare function convertRowToCsv(row: ReadonlyArray<string>): string;
-/**
- * Sorts values for CSV insertion or reading.
- *
- * @category CSV
- */
-export declare function sortValues({ csvFileHeaderOrder, sqlQueryHeaderOrder, from, }: Readonly<{
-    csvFileHeaderOrder: ReadonlyArray<string>;
-    sqlQueryHeaderOrder: ReadonlyArray<string>;
-    from: RequireExactlyOne<{
-        /** When a CSV value array is provided, they are sorted to the SQL header order. */
-        csvFile: ReadonlyArray<string>;
-        /** When a SQL value array is provided, they are sorted to the CSV header order. */
-        sqlQuery: ReadonlyArray<string>;
-    }>;
-}>): string[];
 /**
  * Reads a CSV file contents string and converts it into multiple rows of strings.
  *

package/dist/csv/csv-text.js

@@ -1,6 +1,5 @@
-import { wrapString } from '@augment-vir/common';
+import { trimLines, wrapString } from '@augment-vir/common';
 import { csvParseRows } from 'd3-dsv';
-import { trimLines } from '../augments/trim-lines.js';
 /**
  * Converts multiple rows of values into a CSV file string.
  *
@@ -26,28 +25,6 @@ export function convertRowToCsv(row) {
     })
         .join(',');
 }
-/**
- * Sorts values for CSV insertion or reading.
- *
- * @category CSV
- */
-export function sortValues({ csvFileHeaderOrder, sqlQueryHeaderOrder, from, }) {
-    const fromOrder = from.sqlQuery ? sqlQueryHeaderOrder : csvFileHeaderOrder;
-    const toOrder = (from.sqlQuery ? csvFileHeaderOrder : sqlQueryHeaderOrder).flatMap((header) => {
-        if (header === '*') {
-            return csvFileHeaderOrder;
-        }
-        else {
-            return header;
-        }
-    });
-    const values = from.csvFile || from.sqlQuery;
-    return toOrder.map((header) => {
-        const sourceIndex = fromOrder.indexOf(header);
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        return values[sourceIndex];
-    });
-}
 /**
  * Reads a CSV file contents string and converts it into multiple rows of strings.
  *

package/dist/engine/define-ast-handler.d.ts

@@ -5,7 +5,10 @@ import { type AstHandlerParams } from './params.js';
  *
  * @category Internal
  */
-export type AstHandlerResult = string[][];
+export type AstHandlerResult = {
+    columnNames: string[];
+    values: string[][];
+};
 /**
  * An AST / SQL handler.
  *
@@ -17,7 +20,7 @@ export type AstHandler = {
      * Return `undefined` to mark this AST as not-handled. That means that other handlers should be
      * used instead.
      */
-    handler: (params: Readonly<AstHandlerParams>) => MaybePromise<AstHandlerResult | undefined>;
+    handler: (params: Readonly<AstHandlerParams>) => MaybePromise<AstHandlerResult[] | undefined>;
 };
 /**
  * Used to define new handlers.

package/dist/engine/engine.d.ts

@@ -13,4 +13,4 @@ export declare const allAstHandlers: ReadonlyArray<Readonly<AstHandler>>;
  *
  * @category Main
  */
-export declare function executeSql(sqlInput: Sql | string, params: Readonly<ExecuteSqlParams>): Promise<AstHandlerResult[]>;
+export declare function executeSql(sqlInput: Sql | string, params: Readonly<ExecuteSqlParams>): Promise<AstHandlerResult[][]>;

package/dist/engine/engine.js

@@ -51,7 +51,7 @@ async function executeIndividualCommand(params) {
         for (const handler of allAstHandlers) {
             const output = await handler.handler(params);
             if (output) {
-                return output;
+                return output.filter((entry) => entry.values.length);
             }
         }
         /** If nothing handled the query, then we don't support it. */

package/dist/engine/handlers/row-delete.handler.js

@@ -1,9 +1,9 @@
 import { check } from '@augment-vir/assert';
 import { awaitedBlockingMap } from '@augment-vir/common';
 import { nameCsvTableFile, readCsvFile, readCsvHeaders, writeCsvFile } from '../../csv/csv-file.js';
-import { sortValues } from '../../csv/csv-text.js';
 import { AstType } from '../../sql/ast.js';
 import { defineAstHandler } from '../define-ast-handler.js';
+import { sortValues } from '../sort-values.js';
 import { findWhereMatches } from '../where-matcher.js';
 /**
  * Handles deleting rows.
@@ -12,10 +12,10 @@ import { findWhereMatches } from '../where-matcher.js';
  */
 export const rowDeleteHandler = defineAstHandler({
     name: 'row-delete',
-    async handler({ ast, csvDirPath }) {
+    async handler({ ast, csvDirPath, sql }) {
         if (ast.type === AstType.Delete) {
             const tableNames = ast.table.map((table) => table.table);
-            const returning = await awaitedBlockingMap(tableNames, async (tableName) => {
+            const results = await awaitedBlockingMap(tableNames, async (tableName) => {
                 const { tableFilePath, sanitizedTableName } = nameCsvTableFile({
                     csvDirPath,
                     tableName,
@@ -27,24 +27,23 @@ export const rowDeleteHandler = defineAstHandler({
                 });
                 const rowIndexesToDelete = findWhereMatches(ast.where, csvContents, tableFilePath);
                 const returningRequirement = ast.returning;
-                const returning = returningRequirement
-                    ? csvContents
-                        .filter((row, index) => rowIndexesToDelete.includes(index))
-                        .map((row) => sortValues({
+                const result = returningRequirement
+                    ? sortValues({
                         csvFileHeaderOrder: csvHeaders,
                         sqlQueryHeaderOrder: returningRequirement.columns.map((column) => column.expr.column),
                         from: {
-                            csvFile: row,
+                            csvFile: csvContents.filter((row, index) => rowIndexesToDelete.includes(index)),
                         },
-                    }))
+                        unconsumedInterpolationValues: sql.unconsumedValues,
+                    })
                     : undefined;
                 rowIndexesToDelete.forEach((rowIndexToDelete) => {
                     csvContents.splice(rowIndexToDelete, 1);
                 });
                 await writeCsvFile(tableFilePath, csvContents);
-                return returning;
+                return result;
             });
-            return returning.flat().filter(check.isTruthy);
+            return results.flat().filter(check.isTruthy);
         }
         return undefined;
     },

package/dist/engine/handlers/row-insert.handler.js

@@ -1,9 +1,9 @@
-import { check } from '@augment-vir/assert';
+import { assertWrap, check } from '@augment-vir/assert';
 import { awaitedBlockingMap } from '@augment-vir/common';
 import { appendCsvRow, nameCsvTableFile, readCsvHeaders } from '../../csv/csv-file.js';
-import { sortValues } from '../../csv/csv-text.js';
 import { AstType } from '../../sql/ast.js';
 import { defineAstHandler } from '../define-ast-handler.js';
+import { sortValues } from '../sort-values.js';
 /**
  * Handles inserting rows.
  *
@@ -11,10 +11,10 @@ import { defineAstHandler } from '../define-ast-handler.js';
  */
 export const rowInsertHandler = defineAstHandler({
     name: 'row-insert',
-    async handler({ ast, csvDirPath }) {
+    async handler({ ast, csvDirPath, sql }) {
         if (ast.type === AstType.Insert) {
             const tableNames = ast.table.map((table) => table.table);
-            const returning = await awaitedBlockingMap(tableNames, async (tableName) => {
+            const results = await awaitedBlockingMap(tableNames, async (tableName) => {
                 const { tableFilePath, sanitizedTableName } = nameCsvTableFile({
                     csvDirPath,
                     tableName,
@@ -24,30 +24,31 @@ export const rowInsertHandler = defineAstHandler({
                     csvFilePath: tableFilePath,
                     sanitizedTableName,
                 });
-                const values = ast.columns
-                    ? sortValues({
-                        csvFileHeaderOrder,
-                        sqlQueryHeaderOrder: ast.columns,
-                        from: {
-                            sqlQuery: rawValues,
-                        },
-                    })
-                    : rawValues;
-                await appendCsvRow(values, tableFilePath);
+                const newRow = assertWrap.isDefined(sortValues({
+                    csvFileHeaderOrder,
+                    sqlQueryHeaderOrder: ast.columns || csvFileHeaderOrder,
+                    from: {
+                        sqlQuery: [rawValues],
+                    },
+                    unconsumedInterpolationValues: sql.unconsumedValues,
+                }).values[0], 'No sorted row retrieved.');
+                await appendCsvRow(newRow, tableFilePath);
                 if (ast.returning) {
+                    const sqlHeaders = ast.returning.columns.map((column) => column.expr.column);
                     return sortValues({
                         csvFileHeaderOrder,
-                        sqlQueryHeaderOrder: ast.returning.columns.map((column) => column.expr.column),
+                        sqlQueryHeaderOrder: sqlHeaders,
                         from: {
-                            csvFile: values,
+                            csvFile: [newRow],
                         },
+                        unconsumedInterpolationValues: undefined,
                     });
                 }
                 else {
                     return undefined;
                 }
             });
-            return returning.filter(check.isTruthy);
+            return results.filter(check.isTruthy);
         }
         return undefined;
     },

package/dist/engine/handlers/row-select.handler.js

@@ -1,9 +1,9 @@
 import { check } from '@augment-vir/assert';
 import { awaitedBlockingMap } from '@augment-vir/common';
-import { nameCsvTableFile, readCsvFile, readCsvHeaders, writeCsvFile } from '../../csv/csv-file.js';
-import { sortValues } from '../../csv/csv-text.js';
+import { nameCsvTableFile, readCsvFile, readCsvHeaders } from '../../csv/csv-file.js';
 import { AstType } from '../../sql/ast.js';
 import { defineAstHandler } from '../define-ast-handler.js';
+import { sortValues } from '../sort-values.js';
 import { findWhereMatches } from '../where-matcher.js';
 /**
  * Handles SQL selection.
@@ -12,7 +12,7 @@ import { findWhereMatches } from '../where-matcher.js';
  */
 export const rowSelectHandler = defineAstHandler({
     name: 'row-select',
-    async handler({ ast, csvDirPath }) {
+    async handler({ ast, csvDirPath, sql }) {
         if (ast.type === AstType.Select) {
             const tableNames = ast.from.map((table) => table.table);
             const allSelections = await awaitedBlockingMap(tableNames, async (tableName) => {
@@ -27,17 +27,14 @@ export const rowSelectHandler = defineAstHandler({
                 });
                 const rowIndexesToSelect = findWhereMatches(ast.where, csvContents, tableFilePath);
                 const columnNames = ast.columns.map((column) => column.expr.column);
-                const selection = csvContents
-                    .filter((row, index) => rowIndexesToSelect.includes(index))
-                    .map((row) => sortValues({
+                return sortValues({
                     csvFileHeaderOrder: csvHeaders,
                     sqlQueryHeaderOrder: columnNames,
                     from: {
-                        csvFile: row,
+                        csvFile: csvContents.filter((row, index) => rowIndexesToSelect.includes(index)),
                     },
-                }));
-                await writeCsvFile(tableFilePath, csvContents);
-                return selection;
+                    unconsumedInterpolationValues: sql.unconsumedValues,
+                });
             });
             return allSelections.flat().filter(check.isTruthy);
         }

package/dist/engine/handlers/row-update.handler.js

@@ -1,10 +1,10 @@
 import { assertWrap, check } from '@augment-vir/assert';
 import { awaitedBlockingMap } from '@augment-vir/common';
 import { createCsvHeaderMaps, nameCsvTableFile, readCsvFile, readCsvHeaders, writeCsvFile, } from '../../csv/csv-file.js';
-import { sortValues } from '../../csv/csv-text.js';
 import { CsvColumnDoesNotExistError } from '../../errors/csv.error.js';
 import { AstType } from '../../sql/ast.js';
 import { defineAstHandler } from '../define-ast-handler.js';
+import { sortValues } from '../sort-values.js';
 import { findWhereMatches } from '../where-matcher.js';
 /**
  * Handles updating rows.
@@ -13,10 +13,10 @@ import { findWhereMatches } from '../where-matcher.js';
  */
 export const rowUpdateHandler = defineAstHandler({
     name: 'row-update',
-    async handler({ ast, csvDirPath }) {
+    async handler({ ast, csvDirPath, sql }) {
         if (ast.type === AstType.Update) {
             const tableNames = ast.table.map((table) => table.table);
-            const returning = await awaitedBlockingMap(tableNames, async (tableName) => {
+            const results = await awaitedBlockingMap(tableNames, async (tableName) => {
                 const { tableFilePath, sanitizedTableName } = nameCsvTableFile({
                     csvDirPath,
                     tableName,
@@ -40,21 +40,21 @@ export const rowUpdateHandler = defineAstHandler({
                         row[headerIndex] = set.value.value;
                     });
                 });
-                const returning = returningRequirement
-                    ? csvContents
-                        .filter((row, index) => rowIndexesToUpdate.includes(index))
-                        .map((row) => sortValues({
+                const sqlHeaders = returningRequirement?.columns.map((column) => column.expr.column) || [];
+                const result = returningRequirement
+                    ? sortValues({
                         csvFileHeaderOrder: csvHeaders,
-                        sqlQueryHeaderOrder: returningRequirement.columns.map((column) => column.expr.column),
+                        sqlQueryHeaderOrder: sqlHeaders,
                         from: {
-                            csvFile: row,
+                            csvFile: csvContents.filter((row, index) => rowIndexesToUpdate.includes(index)),
                         },
-                    }))
+                        unconsumedInterpolationValues: sql.unconsumedValues,
+                    })
                     : undefined;
                 await writeCsvFile(tableFilePath, csvContents);
-                return returning;
+                return result;
             });
-            return returning.flat().filter(check.isTruthy);
+            return results.flat().filter(check.isTruthy);
         }
         return undefined;
     },

package/dist/engine/sort-values.d.ts

@@ -0,0 +1,21 @@
+import { type RequireExactlyOne } from 'type-fest';
+import { type ConsumableValue } from '../sql/sql.js';
+/**
+ * Sorts values for CSV insertion or reading and handle interpolated values.
+ *
+ * @category Internal
+ */
+export declare function sortValues({ csvFileHeaderOrder, sqlQueryHeaderOrder, from, unconsumedInterpolationValues, }: Readonly<{
+    csvFileHeaderOrder: ReadonlyArray<string>;
+    sqlQueryHeaderOrder: ReadonlyArray<string>;
+    from: RequireExactlyOne<{
+        /** When a CSV value array is provided, they are sorted to the SQL header order. */
+        csvFile: ReadonlyArray<ReadonlyArray<string>>;
+        /** When a SQL value array is provided, they are sorted to the CSV header order. */
+        sqlQuery: ReadonlyArray<ReadonlyArray<string>>;
+    }>;
+    unconsumedInterpolationValues: undefined | ConsumableValue[];
+}>): {
+    values: string[][];
+    columnNames: string[];
+};

package/dist/engine/sort-values.js

@@ -0,0 +1,44 @@
+/**
+ * Sorts values for CSV insertion or reading and handle interpolated values.
+ *
+ * @category Internal
+ */
+export function sortValues({ csvFileHeaderOrder, sqlQueryHeaderOrder, from, unconsumedInterpolationValues, }) {
+    const fromOrder = from.sqlQuery ? sqlQueryHeaderOrder : csvFileHeaderOrder;
+    const toOrder = (from.sqlQuery ? csvFileHeaderOrder : sqlQueryHeaderOrder).flatMap((header) => {
+        if (header === '*') {
+            return csvFileHeaderOrder;
+        }
+        else {
+            return header;
+        }
+    });
+    const values = (from.csvFile || from.sqlQuery).map((valueRow) => {
+        const mappedValueRow = valueRow.map((value) => {
+            if (value === '?') {
+                if (unconsumedInterpolationValues) {
+                    if (unconsumedInterpolationValues.length) {
+                        return unconsumedInterpolationValues.shift() || '';
+                    }
+                    else {
+                        throw new Error('Encountered ? but all interpolation values have already been used.');
+                    }
+                }
+                else {
+                    throw new Error('Encountered ? but received no interpolation values.');
+                }
+            }
+            else {
+                return value;
+            }
+        });
+        return toOrder.map((header) => {
+            const sourceIndex = fromOrder.indexOf(header);
+            return mappedValueRow[sourceIndex] ?? '';
+        });
+    });
+    return {
+        columnNames: toOrder,
+        values,
+    };
+}

package/dist/errors/sql.error.js

@@ -1,5 +1,4 @@
-import { addSuffix, extractErrorMessage, indent } from '@augment-vir/common';
-import { trimLines } from '../augments/trim-lines.js';
+import { addSuffix, extractErrorMessage, indent, trimLines } from '@augment-vir/common';
 import { CsvSqlEngineError } from './csv-sql-engine.error.js';
 /**
  * Generic SQL related error thrown by the csv-sql-engine package. All SQL related errors from this

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export * from './augments/trim-lines.js';
 export * from './csv/csv-file.js';
 export * from './csv/csv-text.js';
 export * from './engine/define-ast-handler.js';
@@ -11,6 +10,7 @@ export * from './engine/handlers/table-alter.handler.js';
 export * from './engine/handlers/table-create.handler.js';
 export * from './engine/handlers/table-drop.handler.js';
 export * from './engine/params.js';
+export * from './engine/sort-values.js';
 export * from './engine/where-matcher.js';
 export * from './errors/csv-sql-engine.error.js';
 export * from './errors/csv.error.js';

package/dist/index.js

@@ -1,4 +1,3 @@
-export * from './augments/trim-lines.js';
 export * from './csv/csv-file.js';
 export * from './csv/csv-text.js';
 export * from './engine/define-ast-handler.js';
@@ -11,6 +10,7 @@ export * from './engine/handlers/table-alter.handler.js';
 export * from './engine/handlers/table-create.handler.js';
 export * from './engine/handlers/table-drop.handler.js';
 export * from './engine/params.js';
+export * from './engine/sort-values.js';
 export * from './engine/where-matcher.js';
 export * from './errors/csv-sql-engine.error.js';
 export * from './errors/csv.error.js';

package/dist/sql/sql.d.ts

@@ -1,5 +1,11 @@
-import { type MaybeArray } from '@augment-vir/common';
+import { type Branded } from '@augment-vir/common';
 import { Sql as OriginalSql } from 'sql-template-tag';
+/**
+ * Used to mark consumable values so we don't accidentally assign the wrong array for mutation.
+ *
+ * @category Internal
+ */
+export type ConsumableValue = Branded<string, 'consumable-values'>;
 /**
  * A SQL command's strings and values.
  *
@@ -7,6 +13,9 @@ import { Sql as OriginalSql } from 'sql-template-tag';
  */
 export declare class Sql extends OriginalSql {
     values: string[];
+    /** This will be mutated by whatever is reading this SQL. */
+    unconsumedValues: ConsumableValue[];
+    constructor(rawStrings: readonly string[], rawValues: readonly (Sql | string)[]);
 }
 /**
  * Parses a SQL string with interpolations extracted into values so that they can be properly
@@ -14,7 +23,7 @@ export declare class Sql extends OriginalSql {
  *
  * @category SQL
  */
-export declare function sql(strings: ReadonlyArray<string>, ...values: Array<MaybeArray<string> | Sql>): Sql;
+export declare function sql(strings: ReadonlyArray<string>, ...values: Array<string | number | Sql>): Sql;
 /**
  * Creates a raw, _unsafe_, {@link Sql} command. Prefer {@link sql} whenever possible.
  *

package/dist/sql/sql.js

@@ -5,6 +5,12 @@ import { Sql as OriginalSql } from 'sql-template-tag';
  * @category Internal
  */
 export class Sql extends OriginalSql {
+    /** This will be mutated by whatever is reading this SQL. */
+    unconsumedValues;
+    constructor(rawStrings, rawValues) {
+        super(rawStrings, rawValues);
+        this.unconsumedValues = [...this.values];
+    }
 }
 /**
  * Parses a SQL string with interpolations extracted into values so that they can be properly
@@ -13,7 +19,14 @@ export class Sql extends OriginalSql {
  * @category SQL
  */
 export function sql(strings, ...values) {
-    return new Sql(strings, values);
+    return new Sql(strings, values.map((value) => {
+        if (value instanceof Sql) {
+            return value;
+        }
+        else {
+            return String(value);
+        }
+    }));
 }
 /**
  * Creates a raw, _unsafe_, {@link Sql} command. Prefer {@link sql} whenever possible.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "csv-sql-engine",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "API for executing SQL statements on CSV files.",
     "keywords": [
         "CSV",
@@ -43,9 +43,9 @@
         "test:update": "npm run test update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.55.0",
-        "@augment-vir/common": "^31.55.0",
-        "@augment-vir/node": "^31.55.0",
+        "@augment-vir/assert": "^31.56.0",
+        "@augment-vir/common": "^31.56.0",
+        "@augment-vir/node": "^31.56.0",
         "@sinclair/typebox": "^0.34.45",
         "d3-dsv": "^3.0.1",
         "node-sql-parser": "^5.3.13",
@@ -53,7 +53,7 @@
         "sql-template-tag": "^5.2.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.55.0",
+        "@augment-vir/test": "^31.56.0",
         "@eslint/eslintrc": "^3.3.3",
         "@eslint/js": "^9.39.2",
         "@stylistic/eslint-plugin": "^5.6.1",
@@ -93,7 +93,7 @@
         "typedoc": "^0.28.15",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.50.1",
-        "virmator": "^14.3.5"
+        "virmator": "^14.4.0"
     },
     "engines": {
         "node": ">=22"

package/dist/augments/trim-lines.d.ts

@@ -1,6 +0,0 @@
-/**
- * Trims every line in the given string.
- *
- * @category Internal
- */
-export declare function trimLines(value: string): string;

package/dist/augments/trim-lines.js

@@ -1,12 +0,0 @@
-import { check } from '@augment-vir/assert';
-import { filterMap } from '@augment-vir/common';
-/**
- * Trims every line in the given string.
- *
- * @category Internal
- */
-export function trimLines(value) {
-    return filterMap(value.trim().split('\n'), (line) => line.trim(), check.isTruthy)
-        .join('\n')
-        .trim();
-}