neosqlite 1.0.0

package/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "tabWidth": 2,
+  "printWidth": 128,
+  "overrides": [
+    {
+      "files": ["*.ts", "*.js", "*.test.ts", "*.test.js"],
+      "options": {
+        "singleQuote": false
+      }
+    }
+  ]
+}

package/index.ts

@@ -0,0 +1,14 @@
+import { createClient } from "./src/client";
+
+const db = createClient({
+  file: "database.db",
+  onQueryLog: (log) => {
+    console.debug(log);
+  },
+});
+
+db.write("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)");
+
+const result = db.readOne("SELECT * FROM users");
+
+console.log(result);

package/lib/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "neosqlite",
+    "description": "A lightweight wrapper around better-sqlite3 that adds developer-friendly features like job scheduling, migrations, error handling, query logging, SQL utilities, and more",
+    "version": "1.0.0",
+    "main": "lib/src/index.js",
+    "scripts": {
+        "build": "tsc",
+        "prepare": "npm run build"
+    },
+    "keywords": [
+        "sqlite",
+        "database",
+        "neosqlite"
+    ],
+    "author": "JS00001",
+    "license": "ISC",
+    "dependencies": {
+        "better-sqlite3": "^12.6.2",
+        "chrono-node": "^2.8.4",
+        "commander": "^14.0.1",
+        "cron-parser": "^5.4.0"
+    },
+    "devDependencies": {
+        "@types/better-sqlite3": "^7.6.13",
+        "tsx": "^4.20.5",
+        "typescript": "^5.9.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/lib/src/client/index.d.ts

@@ -0,0 +1,2 @@
+import type { NeosqliteClient, NeosqliteConfig } from "../types";
+export declare function createClient(config: NeosqliteConfig): NeosqliteClient;

package/lib/src/client/index.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const util_1 = require("./util");
+function createClient(config) {
+    const { file } = config;
+    const db = new better_sqlite3_1.default(file);
+    const transaction = (fn) => {
+        db.transaction(() => {
+            fn();
+        });
+    };
+    /**
+     * Read data from the database, returns all matching rows
+     * @returns An array of objects
+     */
+    const read = (params) => {
+        const query = (0, util_1.parseQuery)(params);
+        const statement = db.prepare(query.sql);
+        return (0, util_1.runQuery)(config, params, () => statement.all(query.args));
+    };
+    /**
+     * Read data from the database, returns the first matching row
+     * @returns An object
+     */
+    const readOne = (params) => {
+        const query = (0, util_1.parseQuery)(params);
+        const statement = db.prepare(query.sql);
+        return (0, util_1.runQuery)(config, params, () => statement.get(query.args));
+    };
+    /**
+     * Write data to the database, returns the number of
+     * rows affected
+     */
+    const write = (params) => {
+        const query = (0, util_1.parseQuery)(params);
+        const statement = db.prepare(query.sql);
+        return (0, util_1.runQuery)(config, params, () => statement.run(query.args));
+    };
+    /**
+     * Write data to the database, returns all matching rows
+     * via RETURNING
+     */
+    const writeReturning = (params) => {
+        const query = (0, util_1.parseQuery)(params);
+        const statement = db.prepare(query.sql);
+        return (0, util_1.runQuery)(config, params, () => statement.all(query.args));
+    };
+    return {
+        read,
+        readOne,
+        write,
+        transaction,
+        writeReturning,
+        pragma: db.pragma,
+        backup: db.backup,
+    };
+}

package/lib/src/client/util.d.ts

@@ -0,0 +1,108 @@
+import { ExecuteQueryParams, NeosqliteConfig } from "../types";
+export declare const parseQuery: (params: ExecuteQueryParams) => import("../types").QueryParams;
+export declare const runQuery: (config: NeosqliteConfig, params: ExecuteQueryParams, fn: Function) => any;
+/**
+ * Join a list of strings into a single string for
+ * SQL queries
+ *
+ * @example
+ * queryString(
+ *   "SELECT * FROM users",
+ *   "WHERE id = :id"
+ * )
+ * // Returns
+ * "SELECT * FROM users WHERE id = :id"
+ */
+export declare const queryString: (...args: (string | boolean | undefined)[]) => string;
+/**
+ * Take a list and return an object with its sql placeholder names, and
+ * its prepared arguments
+ *
+ * @example
+ * parameterize("id", [1, 2, 3])
+ * // Returns
+ * [
+ *   // Placeholders
+ *   ':id0, :id1, :id2',
+ *   // Args
+ *   { id0: 1, id1: 2, id2: 3 }
+ * ]
+ */
+export declare const parameterizePrimitiveArray: (key: string, value: Array<string | number>) => readonly [string, {
+    [k: string]: string | number;
+}];
+/**
+ * Take an array of objects and extract specific fields as needed to be used
+ * as placeholders, and prepared arguments
+ *
+ * @example
+ * parameterizeComplexArray([{ id: 1, name: "foo" }, { id: 2, name: "bar" }], ["id", "name"])
+ * // Returns
+ * [
+ *   // Placeholders
+ *   '(:id0, :name0), (:id1, :name1)',
+ *   // Args
+ *   { id0: 1, name0: "foo", id1: 2, name1: "bar" }
+ * ]
+ */
+export declare const parameterizeComplexArray: <T>(value: T[], fields: (keyof T)[]) => readonly [string, {}];
+/**
+ * Sanitizes a string to be used in a SQL query
+ * @remarks
+ * You should still prefer using parameterized queries over string concatenation, but this
+ * is sometimes necessary
+ */
+export declare const sanitize: (value: string | number | boolean | null | undefined) => string;
+/**
+ * Parse a column as JSON, where it is either parsed as an object, or as
+ * null
+ *
+ * @returns A parsed object, or null
+ */
+export declare const Jsonify: <T extends Record<string, any> | Array<any> = Record<string, any>>(value: string) => T | null;
+/**
+ * Logs the full query string that will be executed.
+ *
+ * @remarks
+ * ⚠️ DO NOT EXECUTE THIS STRING. By default, this is for logging only, to see
+ * what the query would look like with its parameters in place. This does NOT
+ * sanitize the parameters. In fact, it unsanitizes them.
+ */
+export declare const getFullQueryString: (params: ExecuteQueryParams) => string;
+/**
+ * Sanitize a string to remove characters that would break glob patterns
+ * from the string
+ *
+ * @example
+ * sanitizeLike('foo%bar')
+ * // Returns
+ * 'foo\\%bar'
+ */
+export declare const sanitizeLike: (str: string) => string;
+/**
+ * Fully sanitize a string down to only alphanumeric characters. Useful for JSON key paths
+ * or other string values that cannot be parameterized, but need to be sanitized
+ *
+ * @example
+ * sanitizeSqlPath('foo';--bar')
+ * // Returns
+ * 'foobar'
+ */
+export declare const sanitizeSqlPath: (str: string) => string;
+/**
+ * Converts a date to the standard sqlite date format `YYYY-MM-DD HH:MM:SS`
+ * Also converts timezone to UTC
+ */
+export declare const toSqliteDateString: (date: Date | string) => string;
+/**
+ * Converts a database row to a String or null value
+ */
+export declare const StringOrNull: (value: unknown) => string | null;
+/**
+ * Converts a column value to a Number or null value
+ */
+export declare const NumberOrNull: (value: unknown) => number | null;
+/**
+ * Converts a column value to a Boolean or null value
+ */
+export declare const BooleanOrNull: (value: unknown) => boolean | null;

package/lib/src/client/util.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BooleanOrNull = exports.NumberOrNull = exports.StringOrNull = exports.toSqliteDateString = exports.sanitizeSqlPath = exports.sanitizeLike = exports.getFullQueryString = exports.Jsonify = exports.sanitize = exports.parameterizeComplexArray = exports.parameterizePrimitiveArray = exports.queryString = exports.runQuery = exports.parseQuery = void 0;
+const NEWLINE_CHAR = "\t";
+const parseQuery = (params) => {
+    if (typeof params === "string") {
+        return { sql: params, args: {} };
+    }
+    return params;
+};
+exports.parseQuery = parseQuery;
+const runQuery = (config, params, fn) => {
+    const startTime = process.hrtime();
+    const result = fn();
+    const endTime = process.hrtime(startTime);
+    const endTimeMs = endTime[0] * 1_000 + endTime[1] / 1_000_000;
+    if (config.onQueryComplete || config.onQueryLog) {
+        const queryString = (0, exports.getFullQueryString)(params);
+        config.onQueryComplete?.({ query: queryString, time: endTimeMs });
+        if (typeof params === "object" && params.logQuery) {
+            config.onQueryLog?.(queryString);
+        }
+    }
+    return result;
+};
+exports.runQuery = runQuery;
+/**
+ * Join a list of strings into a single string for
+ * SQL queries
+ *
+ * @example
+ * queryString(
+ *   "SELECT * FROM users",
+ *   "WHERE id = :id"
+ * )
+ * // Returns
+ * "SELECT * FROM users WHERE id = :id"
+ */
+const queryString = (...args) => {
+    const filteredArgs = args.filter(Boolean);
+    return filteredArgs.join(NEWLINE_CHAR);
+};
+exports.queryString = queryString;
+/**
+ * Take a list and return an object with its sql placeholder names, and
+ * its prepared arguments
+ *
+ * @example
+ * parameterize("id", [1, 2, 3])
+ * // Returns
+ * [
+ *   // Placeholders
+ *   ':id0, :id1, :id2',
+ *   // Args
+ *   { id0: 1, id1: 2, id2: 3 }
+ * ]
+ */
+const parameterizePrimitiveArray = (key, value) => {
+    const args = Object.fromEntries(value.map((v, i) => [`${key}${i}`, v]));
+    const placeholders = value.map((_, i) => `:${key}${i}`).join(", ");
+    return [placeholders, args];
+};
+exports.parameterizePrimitiveArray = parameterizePrimitiveArray;
+/**
+ * Take an array of objects and extract specific fields as needed to be used
+ * as placeholders, and prepared arguments
+ *
+ * @example
+ * parameterizeComplexArray([{ id: 1, name: "foo" }, { id: 2, name: "bar" }], ["id", "name"])
+ * // Returns
+ * [
+ *   // Placeholders
+ *   '(:id0, :name0), (:id1, :name1)',
+ *   // Args
+ *   { id0: 1, name0: "foo", id1: 2, name1: "bar" }
+ * ]
+ */
+const parameterizeComplexArray = (value, fields) => {
+    const placeholders = value.map((_, i) => `(${fields.map((field) => `:${String(field)}${i}`).join(",")})`).join(", ");
+    const args = value.reduce((acc, item, i) => {
+        return { ...acc, ...Object.fromEntries(fields.map((field) => [`${String(field)}${i}`, item[field] ?? null])) };
+    }, {});
+    return [placeholders, args];
+};
+exports.parameterizeComplexArray = parameterizeComplexArray;
+/**
+ * Sanitizes a string to be used in a SQL query
+ * @remarks
+ * You should still prefer using parameterized queries over string concatenation, but this
+ * is sometimes necessary
+ */
+const sanitize = (value) => {
+    if (value === null || value === undefined)
+        return "NULL";
+    const sanitizedString = String(value)
+        .replace(/\\/g, "\\\\") // backslashes
+        .replace(/\u0008/g, "\\b") // backspace
+        .replace(/\t/g, "\\t") // tab
+        .replace(/\n/g, "\\n") // newline
+        .replace(/\f/g, "\\f") // form feed
+        .replace(/\r/g, "\\r") // carriage return
+        .replace(/'/g, "''"); // single quotes
+    return `'${sanitizedString}'`;
+};
+exports.sanitize = sanitize;
+/**
+ * Parse a column as JSON, where it is either parsed as an object, or as
+ * null
+ *
+ * @returns A parsed object, or null
+ */
+const Jsonify = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch (err) {
+        return null;
+    }
+};
+exports.Jsonify = Jsonify;
+/**
+ * Logs the full query string that will be executed.
+ *
+ * @remarks
+ * ⚠️ DO NOT EXECUTE THIS STRING. By default, this is for logging only, to see
+ * what the query would look like with its parameters in place. This does NOT
+ * sanitize the parameters. In fact, it unsanitizes them.
+ */
+const getFullQueryString = (params) => {
+    if (typeof params === "string") {
+        return params;
+    }
+    let queryString = params.sql;
+    const args = Object.entries(params.args ?? {}).sort(([aKey], [bKey]) => {
+        return bKey.length - aKey.length;
+    });
+    for (const [key, value] of args) {
+        const regex = new RegExp(`:${key}\\b`, "g");
+        queryString = queryString.replace(regex, `'${value}'`);
+    }
+    let fullString = "";
+    const lines = queryString.split(NEWLINE_CHAR);
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        fullString += `${line}\n`;
+    }
+    return fullString;
+};
+exports.getFullQueryString = getFullQueryString;
+/**
+ * Sanitize a string to remove characters that would break glob patterns
+ * from the string
+ *
+ * @example
+ * sanitizeLike('foo%bar')
+ * // Returns
+ * 'foo\\%bar'
+ */
+const sanitizeLike = (str) => {
+    return str
+        .replace(/\\/g, "\\\\") // escape backslashes
+        .replace(/%/g, "\\%") // escape %
+        .replace(/_/g, "\\_"); // escape _
+};
+exports.sanitizeLike = sanitizeLike;
+/**
+ * Fully sanitize a string down to only alphanumeric characters. Useful for JSON key paths
+ * or other string values that cannot be parameterized, but need to be sanitized
+ *
+ * @example
+ * sanitizeSqlPath('foo';--bar')
+ * // Returns
+ * 'foobar'
+ */
+const sanitizeSqlPath = (str) => {
+    return str.replace(/[^a-zA-Z0-9_]/g, "");
+};
+exports.sanitizeSqlPath = sanitizeSqlPath;
+/**
+ * Converts a date to the standard sqlite date format `YYYY-MM-DD HH:MM:SS`
+ * Also converts timezone to UTC
+ */
+const toSqliteDateString = (date) => {
+    if (typeof date === "string") {
+        date = new Date(date);
+    }
+    const yyyy = date.getUTCFullYear();
+    const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(date.getUTCDate()).padStart(2, "0");
+    const hh = String(date.getUTCHours()).padStart(2, "0");
+    const min = String(date.getUTCMinutes()).padStart(2, "0");
+    const ss = String(date.getUTCSeconds()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd} ${hh}:${min}:${ss}`;
+};
+exports.toSqliteDateString = toSqliteDateString;
+/**
+ * Converts a database row to a String or null value
+ */
+const StringOrNull = (value) => {
+    if (value === null)
+        return null;
+    return String(value);
+};
+exports.StringOrNull = StringOrNull;
+/**
+ * Converts a column value to a Number or null value
+ */
+const NumberOrNull = (value) => {
+    if (value === null)
+        return null;
+    return Number(value);
+};
+exports.NumberOrNull = NumberOrNull;
+/**
+ * Converts a column value to a Boolean or null value
+ */
+const BooleanOrNull = (value) => {
+    if (value === null)
+        return null;
+    return Boolean(value);
+};
+exports.BooleanOrNull = BooleanOrNull;

package/lib/src/index.d.ts

@@ -0,0 +1 @@
+export * from "./types";

package/lib/src/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);

package/lib/src/jobs/index.d.ts

@@ -0,0 +1,48 @@
+import { CreateJobsOptions, JobOptions } from "../types";
+export declare class NeosqliteJobs {
+    private db;
+    private options;
+    private jobsRegistry;
+    private activeJobs;
+    private isRunning;
+    constructor(options: CreateJobsOptions);
+    private get jobsTable();
+    private get maxJobs();
+    private get processEvery();
+    private get maxRetries();
+    /**
+     * Setup tables and start the job worker for neosqlite jobs
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the job worker from listening for jobs
+     */
+    stop(): Promise<void>;
+    /**
+     * Register a job to be run
+     */
+    register<T extends Record<string, any> = Record<string, any>>(name: string, options: JobOptions, fn: (data: T) => void, onFailure?: (data: T) => void): void;
+    /**
+     * Queue a job to run instantly based on its
+     * priority
+     */
+    queue<T extends Record<string, any> = Record<string, any>>(name: string, data?: T): Promise<void>;
+    /**
+     * Schedule a job to run in the future. This can use a date string, or a human-readable string
+     * such as 'in 10 minutes' or 'next week'
+     */
+    schedule<T extends Record<string, any> = Record<string, any>>(date: string, name: string, data?: T): Promise<void>;
+    /**
+     * Schedule a job to run every time the cron string is met
+     */
+    every<T extends Record<string, any> = Record<string, any>>(cronString: string, name: string, data?: T): Promise<void>;
+    /**
+     * Creates the jobs table and sets up indexes on it
+     */
+    private setupTables;
+    /**
+     * Sets up the jobs worker to run automatically
+     */
+    private setupJobWorker;
+    private processJob;
+}