@rocicorp/zero-sqlite3 1.0.0

package/deps/sqlite3.gyp

@@ -0,0 +1,102 @@
+# ===
+# This configuration defines options specific to compiling SQLite3 itself.
+# Compile-time options are loaded by the auto-generated file "defines.gypi".
+# The --sqlite3 option can be provided to use a custom amalgamation instead.
+# ===
+
+{
+  'includes': ['common.gypi'],
+  'targets': [
+    {
+      'target_name': 'locate_sqlite3',
+      'type': 'none',
+      'hard_dependency': 1,
+      'conditions': [
+        ['sqlite3 == ""', {
+          'actions': [{
+            'action_name': 'copy_builtin_sqlite3',
+            'inputs': [
+              'sqlite3/sqlite3.c',
+              'sqlite3/shell.c',
+              'sqlite3/sqlite3.h',
+              'sqlite3/sqlite3ext.h',
+            ],
+            'outputs': [
+              '<(SHARED_INTERMEDIATE_DIR)/sqlite3/sqlite3.c',
+              '<(SHARED_INTERMEDIATE_DIR)/sqlite3/shell.c',
+              '<(SHARED_INTERMEDIATE_DIR)/sqlite3/sqlite3.h',
+              '<(SHARED_INTERMEDIATE_DIR)/sqlite3/sqlite3ext.h',
+            ],
+            'action': ['node', 'copy.js', '<(SHARED_INTERMEDIATE_DIR)/sqlite3', ''],
+          }],
+        }],
+      ],
+    },
+    {
+      'target_name': 'sqlite3',
+      'type': 'static_library',
+      'dependencies': ['locate_sqlite3'],
+      'sources': ['<(SHARED_INTERMEDIATE_DIR)/sqlite3/sqlite3.c'],
+      'include_dirs': ['<(SHARED_INTERMEDIATE_DIR)/sqlite3/'],
+      'direct_dependent_settings': {
+        'include_dirs': ['<(SHARED_INTERMEDIATE_DIR)/sqlite3/'],
+      },
+      'cflags': ['-std=c99', '-w'],
+      'xcode_settings': {
+        'OTHER_CFLAGS': ['-std=c99'],
+        'WARNING_CFLAGS': ['-w'],
+      },
+      'conditions': [
+        ['sqlite3 == ""', {
+          'includes': ['defines.gypi'],
+        }, {
+          'defines': [
+            # This is currently required by better-sqlite3.
+            'SQLITE_ENABLE_COLUMN_METADATA',
+          ],
+        }]
+      ],
+      'configurations': {
+        'Debug': {
+          'msvs_settings': { 'VCCLCompilerTool': { 'RuntimeLibrary': 1 } }, # static debug
+        },
+        'Release': {
+          'msvs_settings': { 'VCCLCompilerTool': { 'RuntimeLibrary': 0 } }, # static release
+        },
+      },
+    },
+    {
+      'target_name': 'shell',
+      'type': 'executable',
+      'dependencies': ['sqlite3'],
+      'sources': ['<(SHARED_INTERMEDIATE_DIR)/sqlite3/sqlite3.c', '<(SHARED_INTERMEDIATE_DIR)/sqlite3/shell.c'],
+      'include_dirs': ['<(SHARED_INTERMEDIATE_DIR)/sqlite3/'],
+      'direct_dependent_settings': {
+        'include_dirs': ['<(SHARED_INTERMEDIATE_DIR)/sqlite3/'],
+      },
+      'cflags': ['-std=c99', '-w'],
+      'xcode_settings': {
+        'OTHER_CFLAGS': ['-std=c99'],
+        'WARNING_CFLAGS': ['-w'],
+      },
+      'conditions': [
+        ['sqlite3 == ""', {
+          'includes': ['defines.gypi'],
+        }, {
+          'defines': [
+            # This is currently required by better-sqlite3.
+            'SQLITE_ENABLE_COLUMN_METADATA',
+          ],
+        }]
+      ],
+      'configurations': {
+        'Debug': {
+          'msvs_settings': { 'VCCLCompilerTool': { 'RuntimeLibrary': 1 } }, # static debug
+        },
+        'Release': {
+          'msvs_settings': { 'VCCLCompilerTool': { 'RuntimeLibrary': 0 } }, # static release
+        },
+      },
+    },
+  ],
+}

package/deps/test_extension.c

@@ -0,0 +1,21 @@
+#include <sqlite3ext.h>
+SQLITE_EXTENSION_INIT1
+
+/*
+	This SQLite3 extension is used only for testing purposes (npm test).
+ */
+
+static void TestExtensionFunction(sqlite3_context* pCtx, int nVal, sqlite3_value** _) {
+	sqlite3_result_double(pCtx, (double)nVal);
+}
+
+#ifdef _WIN32
+__declspec(dllexport)
+#endif
+
+int sqlite3_extension_init(sqlite3* db, char** pzErrMsg, const sqlite3_api_routines* pApi) {
+	SQLITE_EXTENSION_INIT2(pApi)
+	if (pzErrMsg != 0) *pzErrMsg = 0;
+	sqlite3_create_function(db, "testExtensionFunction", -1, SQLITE_UTF8, 0, TestExtensionFunction, 0, 0);
+	return SQLITE_OK;
+}

package/lib/database.js

@@ -0,0 +1,89 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const util = require('./util');
+const SqliteError = require('./sqlite-error');
+
+let DEFAULT_ADDON;
+
+function Database(filenameGiven, options) {
+	if (new.target == null) {
+		return new Database(filenameGiven, options);
+	}
+
+	// Apply defaults
+	let buffer;
+	if (Buffer.isBuffer(filenameGiven)) {
+		buffer = filenameGiven;
+		filenameGiven = ':memory:';
+	}
+	if (filenameGiven == null) filenameGiven = '';
+	if (options == null) options = {};
+
+	// Validate arguments
+	if (typeof filenameGiven !== 'string') throw new TypeError('Expected first argument to be a string');
+	if (typeof options !== 'object') throw new TypeError('Expected second argument to be an options object');
+	if ('readOnly' in options) throw new TypeError('Misspelled option "readOnly" should be "readonly"');
+	if ('memory' in options) throw new TypeError('Option "memory" was removed in v7.0.0 (use ":memory:" filename instead)');
+
+	// Interpret options
+	const filename = filenameGiven.trim();
+	const anonymous = filename === '' || filename === ':memory:';
+	const readonly = util.getBooleanOption(options, 'readonly');
+	const fileMustExist = util.getBooleanOption(options, 'fileMustExist');
+	const timeout = 'timeout' in options ? options.timeout : 5000;
+	const verbose = 'verbose' in options ? options.verbose : null;
+	const nativeBinding = 'nativeBinding' in options ? options.nativeBinding : null;
+
+	// Validate interpreted options
+	if (readonly && anonymous && !buffer) throw new TypeError('In-memory/temporary databases cannot be readonly');
+	if (!Number.isInteger(timeout) || timeout < 0) throw new TypeError('Expected the "timeout" option to be a positive integer');
+	if (timeout > 0x7fffffff) throw new RangeError('Option "timeout" cannot be greater than 2147483647');
+	if (verbose != null && typeof verbose !== 'function') throw new TypeError('Expected the "verbose" option to be a function');
+	if (nativeBinding != null && typeof nativeBinding !== 'string' && typeof nativeBinding !== 'object') throw new TypeError('Expected the "nativeBinding" option to be a string or addon object');
+
+	// Load the native addon
+	let addon;
+	if (nativeBinding == null) {
+		addon = DEFAULT_ADDON || (DEFAULT_ADDON = require('bindings')('better_sqlite3.node'));
+	} else if (typeof nativeBinding === 'string') {
+		// See <https://webpack.js.org/api/module-variables/#__non_webpack_require__-webpack-specific>
+		const requireFunc = typeof __non_webpack_require__ === 'function' ? __non_webpack_require__ : require;
+		addon = requireFunc(path.resolve(nativeBinding).replace(/(\.node)?$/, '.node'));
+	} else {
+		// See <https://github.com/WiseLibs/better-sqlite3/issues/972>
+		addon = nativeBinding;
+	}
+
+	if (!addon.isInitialized) {
+		addon.setErrorConstructor(SqliteError);
+		addon.isInitialized = true;
+	}
+
+	// Make sure the specified directory exists
+	if (!anonymous && !fs.existsSync(path.dirname(filename))) {
+		throw new TypeError('Cannot open database because the directory does not exist');
+	}
+
+	Object.defineProperties(this, {
+		[util.cppdb]: { value: new addon.Database(filename, filenameGiven, anonymous, readonly, fileMustExist, timeout, verbose || null, buffer || null) },
+		...wrappers.getters,
+	});
+}
+
+const wrappers = require('./methods/wrappers');
+Database.prototype.prepare = wrappers.prepare;
+Database.prototype.transaction = require('./methods/transaction');
+Database.prototype.pragma = require('./methods/pragma');
+Database.prototype.backup = require('./methods/backup');
+Database.prototype.serialize = require('./methods/serialize');
+Database.prototype.function = require('./methods/function');
+Database.prototype.aggregate = require('./methods/aggregate');
+Database.prototype.table = require('./methods/table');
+Database.prototype.exec = wrappers.exec;
+Database.prototype.close = wrappers.close;
+Database.prototype.defaultSafeIntegers = wrappers.defaultSafeIntegers;
+Database.prototype.unsafeMode = wrappers.unsafeMode;
+Database.prototype[util.inspect] = require('./methods/inspect');
+
+module.exports = Database;

package/lib/index.d.ts

@@ -0,0 +1,151 @@
+/// <reference types="node" />
+
+// FIXME: Is this `any` really necessary?
+type VariableArgFunction = (...params: any[]) => unknown;
+type ArgumentTypes<F extends VariableArgFunction> = F extends (...args: infer A) => unknown ? A : never;
+type ElementOf<T> = T extends Array<infer E> ? E : T;
+
+declare namespace BetterSqlite3 {
+    interface Statement<BindParameters extends unknown[], Result = unknown> {
+        database: Database;
+        source: string;
+        reader: boolean;
+        readonly: boolean;
+        busy: boolean;
+
+        run(...params: BindParameters): Database.RunResult;
+        get(...params: BindParameters): Result | undefined;
+        all(...params: BindParameters): Result[];
+        iterate(...params: BindParameters): IterableIterator<Result>;
+        pluck(toggleState?: boolean): this;
+        expand(toggleState?: boolean): this;
+        raw(toggleState?: boolean): this;
+        bind(...params: BindParameters): this;
+        columns(): ColumnDefinition[];
+        safeIntegers(toggleState?: boolean): this;
+    }
+
+    interface ColumnDefinition {
+        name: string;
+        column: string | null;
+        table: string | null;
+        database: string | null;
+        type: string | null;
+    }
+
+    interface Transaction<F extends VariableArgFunction> {
+        (...params: ArgumentTypes<F>): ReturnType<F>;
+        default(...params: ArgumentTypes<F>): ReturnType<F>;
+        deferred(...params: ArgumentTypes<F>): ReturnType<F>;
+        immediate(...params: ArgumentTypes<F>): ReturnType<F>;
+        exclusive(...params: ArgumentTypes<F>): ReturnType<F>;
+    }
+
+    interface VirtualTableOptions {
+        rows: (...params: unknown[]) => Generator;
+        columns: string[];
+        parameters?: string[] | undefined;
+        safeIntegers?: boolean | undefined;
+        directOnly?: boolean | undefined;
+    }
+
+    interface Database {
+        memory: boolean;
+        readonly: boolean;
+        name: string;
+        open: boolean;
+        inTransaction: boolean;
+
+        prepare<BindParameters extends unknown[] | {} = unknown[], Result = unknown>(
+            source: string,
+        ): BindParameters extends unknown[] ? Statement<BindParameters, Result> : Statement<[BindParameters], Result>;
+        transaction<F extends VariableArgFunction>(fn: F): Transaction<F>;
+        exec(source: string): this;
+        pragma(source: string, options?: Database.PragmaOptions): unknown;
+        function(name: string, cb: (...params: unknown[]) => unknown): this;
+        function(name: string, options: Database.RegistrationOptions, cb: (...params: unknown[]) => unknown): this;
+        aggregate<T>(
+            name: string,
+            options: Database.RegistrationOptions & {
+                start?: T | (() => T);
+                // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+                step: (total: T, next: ElementOf<T>) => T | void;
+                inverse?: ((total: T, dropped: T) => T) | undefined;
+                result?: ((total: T) => unknown) | undefined;
+            },
+        ): this;
+        loadExtension(path: string): this;
+        close(): this;
+        defaultSafeIntegers(toggleState?: boolean): this;
+        backup(destinationFile: string, options?: Database.BackupOptions): Promise<Database.BackupMetadata>;
+        table(name: string, options: VirtualTableOptions): this;
+        unsafeMode(unsafe?: boolean): this;
+        serialize(options?: Database.SerializeOptions): Buffer;
+    }
+
+    interface DatabaseConstructor {
+        new(filename?: string | Buffer, options?: Database.Options): Database;
+        (filename?: string, options?: Database.Options): Database;
+        prototype: Database;
+
+        SqliteError: typeof SqliteError;
+    }
+}
+
+declare class SqliteError extends Error {
+    name: string;
+    message: string;
+    code: string;
+    constructor(message: string, code: string);
+}
+
+declare namespace Database {
+    interface RunResult {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }
+
+    interface Options {
+        readonly?: boolean | undefined;
+        fileMustExist?: boolean | undefined;
+        timeout?: number | undefined;
+        verbose?: ((message?: unknown, ...additionalArgs: unknown[]) => void) | undefined;
+        nativeBinding?: string | undefined;
+    }
+
+    interface SerializeOptions {
+        attached?: string;
+    }
+
+    interface PragmaOptions {
+        simple?: boolean | undefined;
+    }
+
+    interface RegistrationOptions {
+        varargs?: boolean | undefined;
+        deterministic?: boolean | undefined;
+        safeIntegers?: boolean | undefined;
+        directOnly?: boolean | undefined;
+    }
+
+    type AggregateOptions = Parameters<BetterSqlite3.Database["aggregate"]>[1];
+
+    interface BackupMetadata {
+        totalPages: number;
+        remainingPages: number;
+    }
+    interface BackupOptions {
+        progress: (info: BackupMetadata) => number;
+    }
+
+    type SqliteError = typeof SqliteError;
+    type Statement<BindParameters extends unknown[] | {} = unknown[], Result = unknown> = BindParameters extends
+        unknown[] ? BetterSqlite3.Statement<BindParameters, Result>
+        : BetterSqlite3.Statement<[BindParameters], Result>;
+    type ColumnDefinition = BetterSqlite3.ColumnDefinition;
+    type Transaction<T extends VariableArgFunction = VariableArgFunction> = BetterSqlite3.Transaction<T>;
+    type Database = BetterSqlite3.Database;
+}
+
+declare const Database: BetterSqlite3.DatabaseConstructor;
+export = Database;

package/lib/index.js

@@ -0,0 +1,3 @@
+'use strict';
+module.exports = require('./database');
+module.exports.SqliteError = require('./sqlite-error');

package/lib/methods/aggregate.js

@@ -0,0 +1,43 @@
+'use strict';
+const { getBooleanOption, cppdb } = require('../util');
+
+module.exports = function defineAggregate(name, options) {
+	// Validate arguments
+	if (typeof name !== 'string') throw new TypeError('Expected first argument to be a string');
+	if (typeof options !== 'object' || options === null) throw new TypeError('Expected second argument to be an options object');
+	if (!name) throw new TypeError('User-defined function name cannot be an empty string');
+
+	// Interpret options
+	const start = 'start' in options ? options.start : null;
+	const step = getFunctionOption(options, 'step', true);
+	const inverse = getFunctionOption(options, 'inverse', false);
+	const result = getFunctionOption(options, 'result', false);
+	const safeIntegers = 'safeIntegers' in options ? +getBooleanOption(options, 'safeIntegers') : 2;
+	const deterministic = getBooleanOption(options, 'deterministic');
+	const directOnly = getBooleanOption(options, 'directOnly');
+	const varargs = getBooleanOption(options, 'varargs');
+	let argCount = -1;
+
+	// Determine argument count
+	if (!varargs) {
+		argCount = Math.max(getLength(step), inverse ? getLength(inverse) : 0);
+		if (argCount > 0) argCount -= 1;
+		if (argCount > 100) throw new RangeError('User-defined functions cannot have more than 100 arguments');
+	}
+
+	this[cppdb].aggregate(start, step, inverse, result, name, argCount, safeIntegers, deterministic, directOnly);
+	return this;
+};
+
+const getFunctionOption = (options, key, required) => {
+	const value = key in options ? options[key] : null;
+	if (typeof value === 'function') return value;
+	if (value != null) throw new TypeError(`Expected the "${key}" option to be a function`);
+	if (required) throw new TypeError(`Missing required option "${key}"`);
+	return null;
+};
+
+const getLength = ({ length }) => {
+	if (Number.isInteger(length) && length >= 0) return length;
+	throw new TypeError('Expected function.length to be a positive integer');
+};

package/lib/methods/backup.js

@@ -0,0 +1,67 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { promisify } = require('util');
+const { cppdb } = require('../util');
+const fsAccess = promisify(fs.access);
+
+module.exports = async function backup(filename, options) {
+	if (options == null) options = {};
+
+	// Validate arguments
+	if (typeof filename !== 'string') throw new TypeError('Expected first argument to be a string');
+	if (typeof options !== 'object') throw new TypeError('Expected second argument to be an options object');
+
+	// Interpret options
+	filename = filename.trim();
+	const attachedName = 'attached' in options ? options.attached : 'main';
+	const handler = 'progress' in options ? options.progress : null;
+
+	// Validate interpreted options
+	if (!filename) throw new TypeError('Backup filename cannot be an empty string');
+	if (filename === ':memory:') throw new TypeError('Invalid backup filename ":memory:"');
+	if (typeof attachedName !== 'string') throw new TypeError('Expected the "attached" option to be a string');
+	if (!attachedName) throw new TypeError('The "attached" option cannot be an empty string');
+	if (handler != null && typeof handler !== 'function') throw new TypeError('Expected the "progress" option to be a function');
+
+	// Make sure the specified directory exists
+	await fsAccess(path.dirname(filename)).catch(() => {
+		throw new TypeError('Cannot save backup because the directory does not exist');
+	});
+
+	const isNewFile = await fsAccess(filename).then(() => false, () => true);
+	return runBackup(this[cppdb].backup(this, attachedName, filename, isNewFile), handler || null);
+};
+
+const runBackup = (backup, handler) => {
+	let rate = 0;
+	let useDefault = true;
+
+	return new Promise((resolve, reject) => {
+		setImmediate(function step() {
+			try {
+				const progress = backup.transfer(rate);
+				if (!progress.remainingPages) {
+					backup.close();
+					resolve(progress);
+					return;
+				}
+				if (useDefault) {
+					useDefault = false;
+					rate = 100;
+				}
+				if (handler) {
+					const ret = handler(progress);
+					if (ret !== undefined) {
+						if (typeof ret === 'number' && ret === ret) rate = Math.max(0, Math.min(0x7fffffff, Math.round(ret)));
+						else throw new TypeError('Expected progress callback to return a number or undefined');
+					}
+				}
+				setImmediate(step);
+			} catch (err) {
+				backup.close();
+				reject(err);
+			}
+		});
+	});
+};

package/lib/methods/function.js

@@ -0,0 +1,31 @@
+'use strict';
+const { getBooleanOption, cppdb } = require('../util');
+
+module.exports = function defineFunction(name, options, fn) {
+	// Apply defaults
+	if (options == null) options = {};
+	if (typeof options === 'function') { fn = options; options = {}; }
+
+	// Validate arguments
+	if (typeof name !== 'string') throw new TypeError('Expected first argument to be a string');
+	if (typeof fn !== 'function') throw new TypeError('Expected last argument to be a function');
+	if (typeof options !== 'object') throw new TypeError('Expected second argument to be an options object');
+	if (!name) throw new TypeError('User-defined function name cannot be an empty string');
+
+	// Interpret options
+	const safeIntegers = 'safeIntegers' in options ? +getBooleanOption(options, 'safeIntegers') : 2;
+	const deterministic = getBooleanOption(options, 'deterministic');
+	const directOnly = getBooleanOption(options, 'directOnly');
+	const varargs = getBooleanOption(options, 'varargs');
+	let argCount = -1;
+
+	// Determine argument count
+	if (!varargs) {
+		argCount = fn.length;
+		if (!Number.isInteger(argCount) || argCount < 0) throw new TypeError('Expected function.length to be a positive integer');
+		if (argCount > 100) throw new RangeError('User-defined functions cannot have more than 100 arguments');
+	}
+
+	this[cppdb].function(fn, name, argCount, safeIntegers, deterministic, directOnly);
+	return this;
+};

package/lib/methods/inspect.js

@@ -0,0 +1,7 @@
+'use strict';
+const DatabaseInspection = function Database() {};
+
+module.exports = function inspect(depth, opts) {
+	return Object.assign(new DatabaseInspection(), this);
+};
+

package/lib/methods/pragma.js

@@ -0,0 +1,12 @@
+'use strict';
+const { getBooleanOption, cppdb } = require('../util');
+
+module.exports = function pragma(source, options) {
+	if (options == null) options = {};
+	if (typeof source !== 'string') throw new TypeError('Expected first argument to be a string');
+	if (typeof options !== 'object') throw new TypeError('Expected second argument to be an options object');
+	const simple = getBooleanOption(options, 'simple');
+
+	const stmt = this[cppdb].prepare(`PRAGMA ${source}`, this, true);
+	return simple ? stmt.pluck().get() : stmt.all();
+};

package/lib/methods/serialize.js

@@ -0,0 +1,16 @@
+'use strict';
+const { cppdb } = require('../util');
+
+module.exports = function serialize(options) {
+	if (options == null) options = {};
+
+	// Validate arguments
+	if (typeof options !== 'object') throw new TypeError('Expected first argument to be an options object');
+
+	// Interpret and validate options
+	const attachedName = 'attached' in options ? options.attached : 'main';
+	if (typeof attachedName !== 'string') throw new TypeError('Expected the "attached" option to be a string');
+	if (!attachedName) throw new TypeError('The "attached" option cannot be an empty string');
+
+	return this[cppdb].serialize(attachedName);
+};