csv-sql-engine 0.0.0 → 0.0.1

package/dist/sql/ast.js

@@ -0,0 +1,266 @@
+import { Type } from '@sinclair/typebox';
+import { defineShape, enumShape, exactShape, nullableShape, primitiveShape, unionShape, } from 'object-shape-tester';
+/**
+ * All AST types (corresponding to various SQL commands). Extracted from
+ * [node-sql-parser](https://npmjs.com/package/node-sql-parser).
+ *
+ * @category Internal
+ */
+export var AstType;
+(function (AstType) {
+    AstType["Alter"] = "alter";
+    AstType["Create"] = "create";
+    AstType["Delete"] = "delete";
+    AstType["Drop"] = "drop";
+    AstType["Insert"] = "insert";
+    AstType["Replace"] = "replace";
+    AstType["Select"] = "select";
+    AstType["Update"] = "update";
+    AstType["Use"] = "use";
+})(AstType || (AstType = {}));
+/**
+ * Shape definition for parsed AST output of a SQL command's list of applicable tables.
+ *
+ * @category Internal
+ */
+export const tablesShape = defineShape([
+    {
+        table: '',
+    },
+]);
+/**
+ * All supported and known alter table actions.
+ *
+ * @category Internal
+ */
+export var AlterExpressionAction;
+(function (AlterExpressionAction) {
+    AlterExpressionAction["Add"] = "add";
+    AlterExpressionAction["Rename"] = "rename";
+    AlterExpressionAction["Drop"] = "drop";
+})(AlterExpressionAction || (AlterExpressionAction = {}));
+/**
+ * Shape definition for parsed AST output of a ALTER command.
+ *
+ * @category Internal
+ */
+export const alterExpressionShape = defineShape(unionShape({
+    action: exactShape(AlterExpressionAction.Add),
+    resource: exactShape('column'),
+    column: {
+        type: exactShape('column_ref'),
+        column: '',
+    },
+    default_val: nullableShape({
+        value: {
+            value: '',
+        },
+    }),
+}, {
+    action: exactShape(AlterExpressionAction.Rename),
+    resource: exactShape('column'),
+    old_column: {
+        /** Old name of the column. */
+        column: '',
+    },
+    column: {
+        /** Name name for the column. */
+        column: '',
+    },
+}, {
+    action: exactShape(AlterExpressionAction.Drop),
+    resource: exactShape('column'),
+    column: {
+        /** Name name for the column. */
+        column: '',
+    },
+}));
+/**
+ * Keywords allowed for the create command. Extracted from
+ * [node-sql-parser](https://npmjs.com/package/node-sql-parser).
+ *
+ * @category Internal
+ */
+export var CreateKeyword;
+(function (CreateKeyword) {
+    CreateKeyword["Aggregate"] = "aggregate";
+    CreateKeyword["Database"] = "database";
+    CreateKeyword["Domain"] = "domain";
+    CreateKeyword["Extension"] = "extension";
+    CreateKeyword["Function"] = "function";
+    CreateKeyword["Index"] = "index";
+    CreateKeyword["Schema"] = "schema";
+    CreateKeyword["Table"] = "table";
+    CreateKeyword["Trigger"] = "trigger";
+    CreateKeyword["Type"] = "type";
+    CreateKeyword["User"] = "user";
+    CreateKeyword["View"] = "view";
+})(CreateKeyword || (CreateKeyword = {}));
+/**
+ * Known / supported where types from the SQL AST.
+ *
+ * @category Internal
+ */
+export var WhereType;
+(function (WhereType) {
+    WhereType["BinaryExpression"] = "binary_expr";
+})(WhereType || (WhereType = {}));
+/**
+ * Known / supported where operators from the SQL AST.
+ *
+ * @category Internal
+ */
+export var WhereOperator;
+(function (WhereOperator) {
+    WhereOperator["Equals"] = "=";
+    WhereOperator["Or"] = "OR";
+    WhereOperator["And"] = "AND";
+})(WhereOperator || (WhereOperator = {}));
+/**
+ * SQL AST shape for the column selection part of a where clause.
+ *
+ * @category Internal
+ */
+export const whereColumnShape = defineShape({
+    type: exactShape('column_ref'),
+    /** The column name. */
+    column: '',
+});
+/**
+ * SQL AST shape for basic where comparison.
+ *
+ * @category Internal
+ */
+export const basicWhereShape = defineShape({
+    operator: unionShape(exactShape(WhereOperator.Equals)),
+    left: {
+        type: exactShape('column_ref'),
+        /** The column name. */
+        column: '',
+    },
+    right: {
+        value: primitiveShape(),
+    },
+});
+/**
+ * SQL AST _schema_ for conjunction where clauses (like `or` or `and`).
+ *
+ * @category Internal
+ * @see {@link whereConjunctionShape} for the shape.
+ */
+export const whereConjunctionSchema = Type.Recursive((Self) => Type.Object({
+    operator: Type.Union([
+        Type.Literal(WhereOperator.Or),
+        Type.Literal(WhereOperator.And),
+    ]),
+    left: Type.Union([
+        basicWhereShape.$_schema,
+        Self,
+    ]),
+    right: basicWhereShape.$_schema,
+}));
+/**
+ * SQL AST _shape_ for conjunction where clauses (like `or` or `and`).
+ *
+ * @category Internal
+ * @see {@link whereConjunctionSchema} for the schema.
+ */
+export const whereConjunctionShape = defineShape(whereConjunctionSchema);
+/**
+ * SQL AST shape for SQL where clauses.
+ *
+ * @category Internal
+ */
+export const whereShape = unionShape(basicWhereShape, whereConjunctionShape);
+/**
+ * SQL AST shape for queries that also select data.
+ *
+ * @category Internal
+ */
+export const returningShape = defineShape({
+    type: exactShape('returning'),
+    columns: [
+        {
+            expr: {
+                column: '',
+            },
+        },
+    ],
+});
+/**
+ * The AST types provided by node-sql-parser are missing a lot of information, so we define our own
+ * here.
+ *
+ * @category Internal
+ */
+export const sqlAstShape = defineShape(unionShape({
+    type: exactShape(AstType.Insert),
+    table: tablesShape,
+    columns: nullableShape(['']),
+    values: {
+        values: [
+            {
+                value: [
+                    {
+                        value: primitiveShape(),
+                    },
+                ],
+            },
+        ],
+    },
+    returning: nullableShape(returningShape),
+}, {
+    type: exactShape(AstType.Delete),
+    table: tablesShape,
+    from: tablesShape,
+    where: whereShape,
+    returning: nullableShape(returningShape),
+}, {
+    type: exactShape(AstType.Select),
+    columns: [
+        {
+            expr: {
+                /** Selected column name. */
+                column: '',
+            },
+        },
+    ],
+    from: tablesShape,
+    where: whereShape,
+}, {
+    type: exactShape(AstType.Update),
+    table: tablesShape,
+    where: whereShape,
+    set: [
+        {
+            /** The name of the column to overwrite. */
+            column: '',
+            value: {
+                /** The new value to insert. */
+                value: '',
+            },
+        },
+    ],
+    returning: nullableShape(returningShape),
+}, {
+    type: exactShape(AstType.Drop),
+    name: tablesShape,
+    prefix: nullableShape(exactShape('if exists')),
+    keyword: exactShape('table'),
+}, {
+    type: exactShape(AstType.Alter),
+    table: tablesShape,
+    expr: [alterExpressionShape],
+}, {
+    type: exactShape(AstType.Create),
+    keyword: enumShape(CreateKeyword),
+    table: tablesShape,
+    create_definitions: [
+        {
+            column: {
+                /** The name of the new column. */
+                column: '',
+            },
+        },
+    ],
+}));

package/dist/sql/parse-sql.d.ts

@@ -0,0 +1,9 @@
+import { type ParseSqlOptions } from '../engine/params.js';
+import { type SqlAst } from './ast.js';
+import { type Sql } from './sql.js';
+/**
+ * Parse SQL into multiple SQL ASTs.
+ *
+ * @category SQL
+ */
+export declare function parseSql(sql: Sql, options?: Readonly<ParseSqlOptions>): SqlAst[];

package/dist/sql/parse-sql.js

@@ -0,0 +1,38 @@
+import { combineErrorMessages, ensureArray, extractErrorMessage, indent, wrapInTry, } from '@augment-vir/common';
+import NodeSqlParser from 'node-sql-parser';
+import { assertValidShape, checkValidShape } from 'object-shape-tester';
+import { SqlParseError } from '../errors/sql.error.js';
+import { sqlAstShape } from './ast.js';
+const defaultParser = new NodeSqlParser.Parser();
+/**
+ * Parse SQL into multiple SQL ASTs.
+ *
+ * @category SQL
+ */
+export function parseSql(sql, options = {}) {
+    try {
+        return ensureArray(
+        // cspell:word astify
+        (options.parser || defaultParser).astify(sql.sql, {
+            database: 'Sqlite',
+        })).filter((ast) => {
+            if (checkValidShape(ast, sqlAstShape, {
+                allowExtraKeys: true,
+            })) {
+                return true;
+            }
+            else if (options.rejectUnsupportedOperations) {
+                const failureReason = extractErrorMessage(wrapInTry(() => assertValidShape(ast, sqlAstShape, {
+                    allowExtraKeys: true,
+                })));
+                throw new Error(combineErrorMessages('AST failed', failureReason, '\n', indent(JSON.stringify(ast, null, 4))));
+            }
+            else {
+                return false;
+            }
+        });
+    }
+    catch (error) {
+        throw new SqlParseError(sql, error);
+    }
+}

package/dist/sql/sql.d.ts

@@ -0,0 +1,24 @@
+import { type MaybeArray } from '@augment-vir/common';
+import { Sql as OriginalSql } from 'sql-template-tag';
+/**
+ * A SQL command's strings and values.
+ *
+ * @category Internal
+ */
+export declare class Sql extends OriginalSql {
+    values: string[];
+}
+/**
+ * Parses a SQL string with interpolations extracted into values so that they can be properly
+ * sanitized.
+ *
+ * @category SQL
+ */
+export declare function sql(strings: ReadonlyArray<string>, ...values: Array<MaybeArray<string> | Sql>): Sql;
+/**
+ * Creates a raw, _unsafe_, {@link Sql} command. Prefer {@link sql} whenever possible.
+ *
+ * @deprecated This is unsafe: refer {@link sql} whenever possible.
+ * @category Internal
+ */
+export declare function rawSql(value: string): Sql;

package/dist/sql/sql.js

@@ -0,0 +1,26 @@
+import { Sql as OriginalSql } from 'sql-template-tag';
+/**
+ * A SQL command's strings and values.
+ *
+ * @category Internal
+ */
+export class Sql extends OriginalSql {
+}
+/**
+ * Parses a SQL string with interpolations extracted into values so that they can be properly
+ * sanitized.
+ *
+ * @category SQL
+ */
+export function sql(strings, ...values) {
+    return new Sql(strings, values);
+}
+/**
+ * Creates a raw, _unsafe_, {@link Sql} command. Prefer {@link sql} whenever possible.
+ *
+ * @deprecated This is unsafe: refer {@link sql} whenever possible.
+ * @category Internal
+ */
+export function rawSql(value) {
+    return sql([value]);
+}

package/package.json

@@ -1,13 +1,101 @@
 {
-  "name": "csv-sql-engine",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "MIT",
-  "type": "commonjs"
+    "name": "csv-sql-engine",
+    "version": "0.0.1",
+    "description": "API for executing SQL statements on CSV files.",
+    "keywords": [
+        "CSV",
+        "SQL",
+        "SQLite"
+    ],
+    "homepage": "https://github.com/electrovir/csv-sql-engine",
+    "bugs": {
+        "url": "https://github.com/electrovir/csv-sql-engine/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/csv-sql-engine.git"
+    },
+    "license": "(MIT or CC0 1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "sideEffects": false,
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "format": "virmator format",
+        "lint": "virmator lint fix",
+        "publish": "virmator publish npm run test:all",
+        "start": "tsx src/index.ts",
+        "test": "virmator test node",
+        "test:all": "npm run compile && runstorm --names tests,spelling,format,docs,deps,lint \"npm run test\" \"npm run test:spelling\" \"npm run test:format\" \"npm run test:docs\" \"npm run test:deps\" \"npm run test:lint\"",
+        "test:coverage": "npm run test coverage",
+        "test:deps": "virmator deps check",
+        "test:docs": "virmator docs check",
+        "test:format": "virmator format check",
+        "test:lint": "virmator lint",
+        "test:spelling": "virmator spellcheck",
+        "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",
+        "@sinclair/typebox": "^0.34.45",
+        "d3-dsv": "^3.0.1",
+        "node-sql-parser": "^5.3.13",
+        "object-shape-tester": "^6.11.0",
+        "sql-template-tag": "^5.2.1"
+    },
+    "devDependencies": {
+        "@augment-vir/test": "^31.55.0",
+        "@eslint/eslintrc": "^3.3.3",
+        "@eslint/js": "^9.39.2",
+        "@stylistic/eslint-plugin": "^5.6.1",
+        "@stylistic/eslint-plugin-ts": "^4.4.1",
+        "@types/d3-dsv": "^3.0.7",
+        "@types/node": "^25.0.3",
+        "@typescript-eslint/eslint-plugin": "^8.50.1",
+        "c8": "^10.1.3",
+        "cspell": "^9.4.0",
+        "dependency-cruiser": "^17.3.5",
+        "esbuild": "^0.27.2",
+        "eslint": "^9.39.2",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-jsdoc": "^61.5.0",
+        "eslint-plugin-monorepo-cop": "^1.0.2",
+        "eslint-plugin-playwright": "^2.4.0",
+        "eslint-plugin-prettier": "^5.5.4",
+        "eslint-plugin-require-extensions": "^0.1.3",
+        "eslint-plugin-sonarjs": "^3.0.5",
+        "eslint-plugin-unicorn": "^62.0.0",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "markdown-code-example-inserter": "^3.0.3",
+        "npm-check-updates": "^19.2.0",
+        "prettier": "~3.3.3",
+        "prettier-plugin-embed": "^0.5.1",
+        "prettier-plugin-interpolated-html-tags": "^2.0.1",
+        "prettier-plugin-jsdoc": "^1.8.0",
+        "prettier-plugin-multiline-arrays": "^4.1.3",
+        "prettier-plugin-organize-imports": "^4.3.0",
+        "prettier-plugin-packagejson": "^2.5.20",
+        "prettier-plugin-sort-json": "^4.1.1",
+        "prettier-plugin-sql": "^0.19.2",
+        "prettier-plugin-toml": "^2.0.6",
+        "runstorm": "^1.0.0",
+        "tsx": "^4.21.0",
+        "type-fest": "^5.3.1",
+        "typedoc": "^0.28.15",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.50.1",
+        "virmator": "^14.3.5"
+    },
+    "engines": {
+        "node": ">=22"
+    }
 }