sqlite-hello 0.1.0-alpha.34

package/README.md

@@ -0,0 +1,88 @@
+# `sqlite-hello` NPM Package
+
+`sqlite-hello` is distributed on `npm` for Node.js developers. To install on [supported platforms](#supported-platforms), simply run:
+
+```
+npm install sqlite-hello
+```
+
+The `sqlite-hello` package is meant to be used with Node SQLite clients like [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) and [`node-sqlite3`](https://github.com/TryGhost/node-sqlite3). For `better-sqlite3`, call [`.loadExtension()`](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#loadextensionpath-entrypoint---this) on your database object, passing in [`getLoadablePath()`](#getLoadablePath).
+
+```js
+import Database from "better-sqlite3";
+import * as sqlite_hello from "sqlite-hello";
+
+const db = new Database(":memory:");
+
+db.loadExtension(sqlite_hello.getLoadablePath());
+
+const version = db.prepare("select hello_version()").pluck().get();
+console.log(version); // "v0.2.0"
+```
+
+For `node-sqlite3`, call the similarly named [`.loadExtension()`](https://github.com/TryGhost/node-sqlite3/wiki/API#loadextensionpath--callback) method on your database object, and pass in [`getLoadablePath()`](#getLoadablePath).
+
+```js
+import sqlite3 from "sqlite3";
+import * as sqlite_hello from "sqlite-hello";
+
+const db = new sqlite3.Database(":memory:");
+
+db.loadExtension(sqlite_hello.getLoadablePath());
+
+db.get("select hello_version()", (err, row) => {
+  console.log(row); // {hello_version(): "v0.2.0"}
+});
+```
+
+See [the full API Reference](#api-reference) for the Node API, and [`docs.md`](../../docs.md) for documentation on the `sqlite-hello` SQL API.
+
+## Supported Platforms
+
+Since the underlying `hello0` SQLite extension is pre-compiled, the `sqlite-hello` NPM package only works on a few "platforms" (operating systems + CPU architectures). These platforms include:
+
+- `darwin-x64` (MacOS x86_64)
+- `darwin-arm64` (MacOS M1 and M2 chips)
+- `win32-x64` (Windows x86_64)
+- `linux-x64` (Linux x86_64)
+
+To see which platform your machine is, check the [`process.arch`](https://nodejs.org/api/process.html#processarch) and [`process.platform`](https://nodejs.org/api/process.html#processplatform) values like so:
+
+```bash
+$ node -e 'console.log([process.platform, process.arch])'
+[ 'darwin', 'x64' ]
+```
+
+When the `sqlite-hello` NPM package is installed, the correct pre-compiled extension for your operating system and CPU architecture will be downloaded from the [optional dependencies](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#optionaldependencies), with platform-specific packages like `sqlite-hello-darwin-x64`. This will be automatically, there's no need to directly install those packages.
+
+More platforms may be supported in the future. Consider [supporting my work](https://github.com/sponsors/asg017/) if you'd like to see more operating systems and CPU architectures supported in `sqlite-hello`.
+
+## API Reference
+
+<a href="#getLoadablePath" name="getLoadablePath">#</a> <b>getLoadablePath</b> [<>](https://github.com/asg017/sqlite-hello/blob/main/npm/sqlite-hello/src/index.js "Source")
+
+Returns the full path to where the `sqlite-hello` _should_ be installed, based on the `sqlite-hello`'s `package.json` optional dependencies and the host's operating system and architecture.
+
+This path can be directly passed into [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3)'s [`.loadExtension()`](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#loadextensionpath-entrypoint---this).
+
+```js
+import Database from "better-sqlite3";
+import * as sqlite_hello from "sqlite-hello";
+
+const db = new Database(":memory:");
+db.loadExtension(sqlite_hello.getLoadablePath());
+```
+
+It can also be used in [`node-sqlite3`](https://github.com/TryGhost/node-sqlite3)'s [`.loadExtension()`](https://github.com/TryGhost/node-sqlite3/wiki/API#loadextensionpath--callback).
+
+```js
+import sqlite3 from "sqlite3";
+import * as sqlite_hello from "sqlite-hello";
+
+const db = new sqlite3.Database(":memory:");
+db.loadExtension(sqlite_hello.getLoadablePath());
+```
+
+This function throws an `Error` in two different cases. The first case is when `sqlite-hello` is installed and run on an [unsupported platform](#supported-platforms). The second case is when the platform-specific optional dependency is not installed. If you reach this, ensure you aren't using `--no-optional` flag, and [file an issue](https://github.com/asg017/sqlite-hello/issues/new) if you are stuck.
+
+The `db.loadExtension()` function may also throw an Error if the compiled extension is incompatible with your SQLite connection for any reason, including missing system packages, outdated glib versions, or other misconfigurations. If you reach this, please [file an issue](https://github.com/asg017/sqlite-hello/issues/new).

package/package.json

@@ -0,0 +1,33 @@
+{
+  "//": "Autogenerated by the npm_generate_platform_packages.sh script, do not edit by hand",
+  "name": "sqlite-hello",
+  "version": "0.1.0-alpha.34",
+  "description": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/asg017/sqlite-hello.git",
+    "directory": "npm/sqlite-hello"
+  },
+  "author": "Alex Garcia <alexsebastian.garcia@gmail.com>",
+  "license": "(MIT OR Apache-2.0)",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "files": [
+    "*.dylib",
+    "*.so",
+    "*.dll"
+  ],
+  "optionalDependencies": {
+    "sqlite-hello-darwin-arm64": "0.1.0-alpha.34",
+    "sqlite-hello-darwin-x64": "0.1.0-alpha.34",
+    "sqlite-hello-linux-x64": "0.1.0-alpha.34",
+    "sqlite-hello-windows-x64": "0.1.0-alpha.34"
+  },
+  "devDependencies": {
+    "better-sqlite3": "^8.1.0",
+    "sqlite3": "^5.1.4"
+  }
+}

package/src/index.js

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { arch, platform } from "node:process";
+import { statSync } from "node:fs";
+
+const supportedPlatforms = [
+  ["darwin", "x64"],
+  ["darwin", "arm64"],
+  ["win32", "x64"],
+  ["linux", "x64"],
+];
+
+function validPlatform(platform, arch) {
+  return (
+    supportedPlatforms.find(([p, a]) => platform == p && arch === a) !== null
+  );
+}
+function extensionSuffix(platform) {
+  if (platform === "win32") return "dll";
+  if (platform === "darwin") return "dylib";
+  return "so";
+}
+function platformPackageName(platform, arch) {
+  const os = platform === "win32" ? "windows" : platform;
+  return `sqlite-hello-${os}-${arch}`;
+}
+
+export function getLoadablePath() {
+  if (!validPlatform(platform, arch)) {
+    throw new Error(
+      `Unsupported platform for sqlite-hello, on a ${platform}-${arch} machine, but not in supported platforms (${supportedPlatforms
+        .map(([p, a]) => `${p}-${a}`)
+        .join(",")}). Consult the sqlite-hello NPM package README for details. `
+    );
+  }
+  const packageName = platformPackageName(platform, arch);
+  const loadablePath = join(
+    fileURLToPath(new URL(".", import.meta.url)),
+    "..",
+    "..",
+    packageName,
+    "lib",
+    `hello0.${extensionSuffix(platform)}`
+  );
+  if (!statSync(loadablePath, { throwIfNoEntry: false })) {
+    throw new Error(
+      `Loadble extension for sqlite-hello not found. Was the ${packageName} package installed? Avoid using the --no-optional flag, as the optional dependencies for sqlite-hello are required.`
+    );
+  }
+
+  return loadablePath;
+}