csv-sql-engine 0.0.0 → 0.0.1

package/LICENSE-CC0

@@ -0,0 +1,121 @@
+CC0 1.0 Universal
+
+Creative Commons Legal Code
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 electrovir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# csv-sql-engine
+
+An API for executing SQL statements on a collection of CSV files. Handles SQLite syntax.
+
+Supports only basic version of the following operations:
+
+-   creating tables
+-   dropping tables
+-   adding columns
+-   dropping columns
+-   renaming columns
+-   inserting rows
+-   deleting rows
+-   updating rows
+-   selecting data
+
+Caveats:
+
+-   Default column values are only applied when adding a _new column_ to an existing table. (Not when adding new rows.)
+-   Database constraints (column data types, relational ids, not null, etc.) are not enforced on read or write.
+-   Auto-incrementing ids do not auto increment.
+-   Every value is written and read as a string.
+-   Probably not performant on large CSV files.
+-   Joins are not yet supported.
+
+## Install
+
+```sh
+npm i csv-sql-engine
+```
+
+## Examples
+
+<!-- example-link: ./src/engine/engine.example.ts -->
+
+```TypeScript
+import {executeSql, sql} from 'csv-sql-engine';
+
+/** Creates a new file at `./my-csv-files/users.csv`. */
+await executeSql(
+    sql`
+        CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT);
+        INSERT INTO users VALUES (1, "example@example.com", "example");
+    `,
+    {
+        csvDirPath: './my-csv-files/',
+    },
+);
+```

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

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

package/dist/augments/trim-lines.js

@@ -0,0 +1,12 @@
+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();
+}

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

@@ -0,0 +1,70 @@
+import { type RequireExactlyOne } from 'type-fest';
+/**
+ * The extension used for reading and writing to CSV files.
+ *
+ * @category Internal
+ */
+export declare const csvExtension = ".csv";
+/**
+ * A parsed CSV file's contents.
+ *
+ * @category Internal
+ */
+export type CsvFile = string[][];
+/**
+ * Appends multiple rows to a CSV file.
+ *
+ * @category CSV
+ */
+export declare function appendCsvRows(valueMatrix: ReadonlyArray<ReadonlyArray<string>>, csvFilePath: string): Promise<void>;
+/**
+ * Appends a single row to a CSV file.
+ *
+ * @category CSV
+ */
+export declare function appendCsvRow(row: ReadonlyArray<string>, csvFilePath: string): Promise<void>;
+/**
+ * Creates a sanitized table name and file path for the given SQL table name.
+ *
+ * @category CSV
+ */
+export declare function nameCsvTableFile({ csvDirPath, tableName, }: {
+    csvDirPath: string;
+    tableName: string;
+}): {
+    tableFilePath: string;
+    sanitizedTableName: string;
+};
+/**
+ * Reads a CSV from a file path and converts its contents into multiple rows of strings.
+ *
+ * @category CSV
+ */
+export declare function readCsvFile(filePath: string): Promise<CsvFile>;
+/**
+ * Replaces a CSV file's complete contents with the new given contents. If the file does not exist,
+ * it and its directories are created.
+ *
+ * @category CSV
+ */
+export declare function writeCsvFile(filePath: string, contents: ReadonlyArray<ReadonlyArray<string>>): Promise<void>;
+/**
+ * Reads headers from a CSV file or already-parsed CSV contents.
+ *
+ * @category CSV
+ */
+export declare function readCsvHeaders(params: Readonly<RequireExactlyOne<{
+    csvFilePath: string;
+    csvContents: Readonly<CsvFile>;
+}> & {
+    sanitizedTableName: string;
+}>): Promise<string[]>;
+/**
+ * Maps CSV headers to their indexes.
+ *
+ * @category CSV
+ */
+export declare function createCsvHeaderMaps(csvHeaders: ReadonlyArray<string>): {
+    byName: Record<string, number>;
+    byIndex: Record<number, string>;
+};

package/dist/csv/csv-file.js

@@ -0,0 +1,98 @@
+import { addSuffix, awaitedForEach, removeSuffix } from '@augment-vir/common';
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CsvFileMissingHeadersError } from '../errors/csv.error.js';
+import { convertRowsToCsv, convertRowToCsv, parseCsvContents } from './csv-text.js';
+/**
+ * The extension used for reading and writing to CSV files.
+ *
+ * @category Internal
+ */
+export const csvExtension = '.csv';
+/**
+ * Appends multiple rows to a CSV file.
+ *
+ * @category CSV
+ */
+export async function appendCsvRows(valueMatrix, csvFilePath) {
+    await awaitedForEach(valueMatrix, async (values) => {
+        await appendCsvRow(values, csvFilePath);
+    });
+}
+/**
+ * Appends a single row to a CSV file.
+ *
+ * @category CSV
+ */
+export async function appendCsvRow(row, csvFilePath) {
+    await appendFile(csvFilePath, convertRowToCsv(row) + '\n');
+}
+/**
+ * Creates a sanitized table name and file path for the given SQL table name.
+ *
+ * @category CSV
+ */
+export function nameCsvTableFile({ csvDirPath, tableName, }) {
+    const sanitizedTableName = removeSuffix({ value: tableName, suffix: csvExtension }).replaceAll(/[./\\]/g, '');
+    const newCsvFileName = addSuffix({ value: sanitizedTableName, suffix: csvExtension });
+    return {
+        tableFilePath: join(csvDirPath, newCsvFileName),
+        sanitizedTableName,
+    };
+}
+/**
+ * Reads a CSV from a file path and converts its contents into multiple rows of strings.
+ *
+ * @category CSV
+ */
+export async function readCsvFile(filePath) {
+    const fileContents = await readFile(filePath, 'utf-8');
+    return parseCsvContents(fileContents);
+}
+/**
+ * Replaces a CSV file's complete contents with the new given contents. If the file does not exist,
+ * it and its directories are created.
+ *
+ * @category CSV
+ */
+export async function writeCsvFile(filePath, contents) {
+    if (!existsSync(filePath)) {
+        await mkdir(dirname(filePath), {
+            recursive: true,
+        });
+    }
+    const fileContents = convertRowsToCsv(contents);
+    await writeFile(filePath, fileContents);
+}
+/**
+ * Reads headers from a CSV file or already-parsed CSV contents.
+ *
+ * @category CSV
+ */
+export async function readCsvHeaders(params) {
+    const headers = params.csvContents
+        ? params.csvContents[0]
+        : (await readCsvFile(params.csvFilePath))[0];
+    if (!headers) {
+        throw new CsvFileMissingHeadersError(params.sanitizedTableName);
+    }
+    return headers;
+}
+/**
+ * Maps CSV headers to their indexes.
+ *
+ * @category CSV
+ */
+export function createCsvHeaderMaps(csvHeaders) {
+    const byName = {};
+    const byIndex = {};
+    csvHeaders.forEach((name, index) => {
+        byName[name] = index;
+        byIndex[index] = name;
+    });
+    return {
+        byIndex,
+        byName,
+    };
+}

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

@@ -0,0 +1,52 @@
+import { type RequireExactlyOne } from 'type-fest';
+/**
+ * Converts multiple rows of values into a CSV file string.
+ *
+ * @category CSV
+ */
+export declare function convertRowsToCsv(rows: ReadonlyArray<ReadonlyArray<string>>): string;
+/**
+ * Converts a single row of values into a CSV file string.
+ *
+ * @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.
+ *
+ * @category CSV
+ */
+export declare function parseCsvContents(csvContents: string): string[][];
+/**
+ * A tagged template creator that simply returns a string. All leading and trailing whitespace on
+ * each line is trimmed, allowing you to format the CSV contents however you like without affecting
+ * content.
+ *
+ * @category CSV
+ * @example
+ *
+ * ```ts
+ * import {csv} from 'csv-sql-engine';
+ *
+ * export myCsv = csv`
+ *     a,b,c,d
+ *     1,2,3,4
+ * `;
+ * ```
+ */
+export declare function csv(strings: ReadonlyArray<string>, ...values: Array<string>): string;

package/dist/csv/csv-text.js

@@ -0,0 +1,79 @@
+import { 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.
+ *
+ * @category CSV
+ */
+export function convertRowsToCsv(rows) {
+    return rows.map((row) => convertRowToCsv(row)).join('\n');
+}
+/**
+ * Converts a single row of values into a CSV file string.
+ *
+ * @category CSV
+ */
+export function convertRowToCsv(row) {
+    return row
+        .map((value) => {
+        if (value) {
+            return wrapString({ value, wrapper: '"' });
+        }
+        else {
+            return '""';
+        }
+    })
+        .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.
+ *
+ * @category CSV
+ */
+export function parseCsvContents(csvContents) {
+    return csvParseRows(csvContents);
+}
+/**
+ * A tagged template creator that simply returns a string. All leading and trailing whitespace on
+ * each line is trimmed, allowing you to format the CSV contents however you like without affecting
+ * content.
+ *
+ * @category CSV
+ * @example
+ *
+ * ```ts
+ * import {csv} from 'csv-sql-engine';
+ *
+ * export myCsv = csv`
+ *     a,b,c,d
+ *     1,2,3,4
+ * `;
+ * ```
+ */
+export function csv(strings, ...values) {
+    const fullString = strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
+    return trimLines(fullString);
+}

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

@@ -0,0 +1,27 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type AstHandlerParams } from './params.js';
+/**
+ * Output from a handler that handled a SQL query.
+ *
+ * @category Internal
+ */
+export type AstHandlerResult = string[][];
+/**
+ * An AST / SQL handler.
+ *
+ * @category Internal
+ */
+export type AstHandler = {
+    name: string;
+    /**
+     * 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>;
+};
+/**
+ * Used to define new handlers.
+ *
+ * @category Internal
+ */
+export declare function defineAstHandler(params: AstHandler): AstHandler;

package/dist/engine/define-ast-handler.js

@@ -0,0 +1,8 @@
+/**
+ * Used to define new handlers.
+ *
+ * @category Internal
+ */
+export function defineAstHandler(params) {
+    return params;
+}

package/dist/engine/engine.d.ts

@@ -0,0 +1,16 @@
+import { type Sql } from '../sql/sql.js';
+import { type AstHandler, type AstHandlerResult } from './define-ast-handler.js';
+import { type ExecuteSqlParams } from './params.js';
+/**
+ * All current SQL handlers.
+ *
+ * @category Internal
+ */
+export declare const allAstHandlers: ReadonlyArray<Readonly<AstHandler>>;
+/**
+ * The main entry point to this package. Run SQLite-compatible SQL commands on a collection of CSV
+ * files.
+ *
+ * @category Main
+ */
+export declare function executeSql(sqlInput: Sql | string, params: Readonly<ExecuteSqlParams>): Promise<AstHandlerResult[]>;

package/dist/engine/engine.js

@@ -0,0 +1,66 @@
+import { check } from '@augment-vir/assert';
+import { awaitedBlockingMap, ensureErrorAndPrependMessage } from '@augment-vir/common';
+import { mkdir } from 'node:fs/promises';
+import { SqlUnsupportedOperationError } from '../errors/sql.error.js';
+import { parseSql } from '../sql/parse-sql.js';
+import { rawSql } from '../sql/sql.js';
+import { rowDeleteHandler } from './handlers/row-delete.handler.js';
+import { rowInsertHandler } from './handlers/row-insert.handler.js';
+import { rowSelectHandler } from './handlers/row-select.handler.js';
+import { rowUpdateHandler } from './handlers/row-update.handler.js';
+import { tableAlterHandler } from './handlers/table-alter.handler.js';
+import { tableCreateHandler } from './handlers/table-create.handler.js';
+import { tableDropHandler } from './handlers/table-drop.handler.js';
+/**
+ * All current SQL handlers.
+ *
+ * @category Internal
+ */
+export const allAstHandlers = [
+    tableAlterHandler,
+    tableCreateHandler,
+    rowInsertHandler,
+    tableDropHandler,
+    rowDeleteHandler,
+    rowUpdateHandler,
+    rowSelectHandler,
+];
+/**
+ * The main entry point to this package. Run SQLite-compatible SQL commands on a collection of CSV
+ * files.
+ *
+ * @category Main
+ */
+export async function executeSql(sqlInput, params) {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    const sql = check.isString(sqlInput) ? rawSql(sqlInput) : sqlInput;
+    const astResults = parseSql(sql, params);
+    await mkdir(params.csvDirPath, {
+        recursive: true,
+    });
+    return await awaitedBlockingMap(astResults, async (ast) => {
+        return await executeIndividualCommand({
+            ...params,
+            ast,
+            sql,
+        });
+    });
+}
+async function executeIndividualCommand(params) {
+    try {
+        for (const handler of allAstHandlers) {
+            const output = await handler.handler(params);
+            if (output) {
+                return output;
+            }
+        }
+        /** If nothing handled the query, then we don't support it. */
+        if (params.rejectUnsupportedOperations) {
+            throw new SqlUnsupportedOperationError(params.sql, undefined);
+        }
+        return [];
+    }
+    catch (error) {
+        throw ensureErrorAndPrependMessage(error, `Failed to execute '${params.ast.type}' command.`);
+    }
+}

package/dist/engine/handlers/row-delete.handler.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Handles deleting rows.
+ *
+ * @category SQL Handler
+ */
+export declare const rowDeleteHandler: import("../define-ast-handler.js").AstHandler;