@bezoar/nuxt 0.0.0-stage → 0.0.2

package/.dist/_chunks/constant.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The virtual modules the module adds to the server build: the build of the
+ * app, and its service. A virtual module is bundled in dev and in production
+ * alike, so the plugin of the runtime, which imports both, is too.
+ */
+export declare const VIRTUAL: {
+  readonly build: "#bezoar/build";
+  readonly service: "#bezoar/service";
+};
+/**
+ * The declaration of the service, in the build directory. It declares the
+ * virtual service module, so the server is typed by the build.
+ */
+export declare const DECLARATION = "types/bezoar.d.ts";
+/**
+ * The modules of a kit build the module adopts.
+ */
+export declare const ENTRIES: readonly ["index", "queries", "migrations", "seeds"];
+/**
+ * The export of each module of a kit build, re-exported by the virtual
+ * build. Named, not `export *`: the modules are external to the server
+ * bundle in dev, and a bundler cannot tell which of several external modules
+ * a star re-export provides a name from.
+ */
+export declare const EXPORTS: Record<(typeof ENTRIES)[number], string>;
+/**
+ * The drivers the module can connect with. `pg` connects to a server with
+ * the connection string of the runtime config. `pglite` runs Postgres in the
+ * process, on the data directory of the runtime config, or in memory.
+ */
+export declare const DRIVERS: readonly ["pg", "pglite"];

package/.dist/config.d.ts

@@ -0,0 +1,62 @@
+import { DRIVERS } from "./_chunks/constant.js";
+/**
+ * A driver the module can connect with.
+ */
+export type Driver = (typeof DRIVERS)[number];
+/**
+ * The module's configuration.
+ *
+ * ```ts
+ * export default defineNuxtConfig({
+ *   modules: ["@bezoar/nuxt"],
+ *   bezoar: { build: "@acme/database", migrate: true },
+ * });
+ * ```
+ */
+export interface NuxtBezoarConfig {
+  /**
+   * A kit build: the output directory `bezoar build` wrote. A path,
+   * relative to the project root or absolute, to the directory or its
+   * `index.mjs`, or a package whose main entry is that `index.mjs`.
+   */
+  build: string;
+  /**
+   * The driver. `pg` connects to a Postgres server with the connection
+   * string of the runtime config. `pglite` runs Postgres in the process.
+   * Defaults to `pg`.
+   */
+  driver?: Driver;
+  /**
+   * Whether the server applies the migrations of the build when it starts.
+   * Defaults to `false`.
+   */
+  migrate?: boolean;
+  /**
+   * Whether the server runs the seeds of the build when it starts, after
+   * the migrations. Defaults to `false`.
+   */
+  seed?: boolean;
+}
+/**
+ * The runtime config of the module, under `runtimeConfig.bezoar`. An
+ * environment variable sets each member: `NUXT_BEZOAR_URL` sets `url`.
+ */
+export interface BezoarRuntimeConfig {
+  /** The connection string, for the `pg` driver. */
+  url: string;
+  /** The data directory, for the `pglite` driver. Empty for memory. */
+  dataDir: string;
+  /** The driver. */
+  driver: Driver;
+  /** Whether the server applies the migrations when it starts. */
+  migrate: boolean;
+  /** Whether the server runs the seeds when it starts. */
+  seed: boolean;
+}
+/**
+ * Identity helper that types a Nuxt bezoar configuration.
+ *
+ * @param config - The Nuxt bezoar configuration.
+ * @returns The same config.
+ */
+export declare const defineBezoarConfig: (config: NuxtBezoarConfig) => NuxtBezoarConfig;

package/.dist/config.js

@@ -0,0 +1,2 @@
+const defineBezoarConfig = (config) => config;
+export { defineBezoarConfig };

package/.dist/constant.d.ts

@@ -0,0 +1,2 @@
+import { DECLARATION, DRIVERS, ENTRIES, EXPORTS, VIRTUAL } from "./_chunks/constant.js";
+export { DECLARATION, DRIVERS, ENTRIES, EXPORTS, VIRTUAL };

package/.dist/constant.js

@@ -0,0 +1,19 @@
+const VIRTUAL = {
+	build: "#bezoar/build",
+	service: "#bezoar/service"
+};
+const DECLARATION = "types/bezoar.d.ts";
+const ENTRIES = [
+	"index",
+	"queries",
+	"migrations",
+	"seeds"
+];
+const EXPORTS = {
+	index: "contract",
+	queries: "queries",
+	migrations: "migrations",
+	seeds: "seeds"
+};
+const DRIVERS = ["pg", "pglite"];
+export { DECLARATION, DRIVERS, ENTRIES, EXPORTS, VIRTUAL };

package/.dist/module.d.ts

@@ -0,0 +1,22 @@
+import { NuxtBezoarConfig } from "./config.js";
+/**
+ * Nuxt module for bezoar.
+ *
+ * The module takes a kit build, the output of `bezoar build` in a
+ * database package, and adds two virtual modules to the server build: the
+ * build of the app, which re-exports the modules of the kit build, and the
+ * service of the app, over the contract and the SQL of that build. A
+ * declaration in the build directory types the service by the contract. The
+ * module provides `useBezoar()` to the server from the virtual service: a
+ * service over the contract of the build, typed by it, connected through
+ * the driver and the connection string of the runtime config. The plugin of
+ * the runtime makes the service when the server starts, applies the
+ * migrations and runs the seeds of the virtual build when the config asks,
+ * and closes the connection when the server stops.
+ *
+ * The modules are virtual, not written, so Nitro bundles them in dev as in
+ * production. Nitro loads a written file through Node in dev, where neither
+ * `#imports` nor a virtual module exists.
+ */
+declare const _default: import("@nuxt/schema").NuxtModule<NuxtBezoarConfig, NuxtBezoarConfig, false>;
+export { _default as default };

package/.dist/module.js

@@ -0,0 +1,108 @@
+import { DECLARATION, ENTRIES, EXPORTS, VIRTUAL } from "./constant.js";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { addServerImports, addServerPlugin, addServerTemplate, addTypeTemplate, createResolver, defineNuxtModule, directoryToURL, tryResolveModule } from "@nuxt/kit";
+import { record } from "objectively";
+import { existsSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const locate = async (build, root) => {
+	let path;
+	if (build.startsWith(".") || isAbsolute(build)) path = resolve(root, build);
+	else {
+		const resolved = await tryResolveModule(build, directoryToURL(root));
+		path = resolved?.startsWith("file:") ? fileURLToPath(resolved) : resolved;
+	}
+	if (path === void 0 || !existsSync(path)) throw new Error(`bezoar: \`build\` ${JSON.stringify(build)} could not be found from ${root}`);
+	const directory = statSync(path).isFile() ? dirname(path) : path;
+	for (const entry of ENTRIES) if (!existsSync(join(directory, `${entry}.mjs`))) throw new Error(`bezoar: ${directory} is not a kit build; it has no ${entry}.mjs (run \`bezoar build\` there first)`);
+	return directory;
+};
+const from = (directory, file) => JSON.stringify(join(directory, file));
+const build = ({ build: directory }) => [...ENTRIES.map((entry) => `export { ${EXPORTS[entry]} } from ${from(directory, `${entry}.mjs`)};`), ""].join("\n");
+const service = ({ runtime }) => [
+	`import { contract, queries } from ${JSON.stringify(VIRTUAL.build)};`,
+	`import { defineService } from ${from(runtime, "service.js")};`,
+	"",
+	"export const { useBezoar, closeBezoar } = defineService(contract, queries);",
+	""
+].join("\n");
+const declaration = ({ build, runtime }) => {
+	const contract = `typeof import(${from(build, "index.mjs")}).contract`;
+	const service = `import(${from(runtime, "service.js")})`;
+	return [
+		`declare module ${JSON.stringify(VIRTUAL.service)} {`,
+		`  export type AppBezoarContract = ${contract};`,
+		`  export const useBezoar: ${service}.Defined<AppBezoarContract>["useBezoar"];`,
+		`  export const closeBezoar: ${service}.Defined<AppBezoarContract>["closeBezoar"];`,
+		"  export type AppBezoar = ReturnType<typeof useBezoar>;",
+		`  export type AppBezoarQuery = ${service}.Query<AppBezoarContract>;`,
+		`  export type AppBezoarArguments<Q extends AppBezoarQuery> = ${service}.Arguments<AppBezoarContract, Q>;`,
+		`  export type AppBezoarRow<Q extends AppBezoarQuery> = ${service}.Row<AppBezoarContract, Q>;`,
+		"}",
+		""
+	].join("\n");
+};
+var module_default = defineNuxtModule({
+	meta: {
+		name: "bezoar",
+		configKey: "bezoar"
+	},
+	setup: async (options, nuxt) => {
+		if (typeof options.build !== "string" || options.build === "") throw new Error("bezoar: `build` must name a kit build, as a package or a path");
+		const resolver = createResolver(import.meta.url);
+		const sources = {
+			build: await locate(options.build, nuxt.options.rootDir),
+			runtime: dirname(await resolver.resolvePath("./runtime/server/service"))
+		};
+		nuxt.options.build.transpile.push(sources.runtime);
+		addServerTemplate({
+			filename: VIRTUAL.build,
+			getContents: () => build(sources)
+		});
+		addServerTemplate({
+			filename: VIRTUAL.service,
+			getContents: () => service(sources)
+		});
+		addTypeTemplate({
+			filename: DECLARATION,
+			getContents: () => declaration(sources)
+		}, {
+			nitro: true,
+			nuxt: true
+		});
+		const defaults = {
+			url: "",
+			dataDir: "",
+			driver: options.driver ?? "pg",
+			migrate: options.migrate ?? false,
+			seed: options.seed ?? false
+		};
+		const given = nuxt.options.runtimeConfig.bezoar;
+		nuxt.options.runtimeConfig.bezoar = {
+			...defaults,
+			...record(given) ? given : {}
+		};
+		addServerPlugin(await resolver.resolvePath("./runtime/server/plugin"));
+		addServerImports([
+			{
+				from: VIRTUAL.service,
+				name: "useBezoar"
+			},
+			{
+				from: VIRTUAL.service,
+				name: "closeBezoar"
+			},
+			...[
+				"AppBezoar",
+				"AppBezoarContract",
+				"AppBezoarQuery",
+				"AppBezoarArguments",
+				"AppBezoarRow"
+			].map((name) => ({
+				from: VIRTUAL.service,
+				name,
+				type: true
+			}))
+		]);
+	}
+});
+export { module_default as default };

package/.dist/runtime/server/plugin.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The plugin of the app. Nitro resolves a plugin by path, so the plugin is a
+ * file of the runtime; what differs by app, the service and the build, comes
+ * from the virtual modules the module adds to the server build.
+ */
+declare const _default: (nitroApp: import("#imports").NitroApp) => Promise<void>;
+export { _default as default };

package/.dist/runtime/server/plugin.js

@@ -0,0 +1,10 @@
+import { definePlugin } from "./startup.js";
+import { migrations, seeds } from "#bezoar/build";
+import { closeBezoar, useBezoar } from "#bezoar/service";
+var plugin_default = definePlugin({
+	useBezoar,
+	closeBezoar,
+	migrations,
+	seeds
+});
+export { plugin_default as default };

package/.dist/runtime/server/service.d.ts

@@ -0,0 +1,23 @@
+import { Arguments, Bezoar, Bundle, Definition, Query, Row } from "bezoar";
+/**
+ * The service of an app: `useBezoar` for the service, `closeBezoar`
+ * to close its connection.
+ */
+export interface Defined<D extends Definition> {
+  useBezoar: () => Bezoar<D>;
+  closeBezoar: () => Promise<void>;
+}
+/**
+ * Defines the service of an app over a contract and its SQL. The written
+ * service of the build directory calls this with the modules of the build.
+ *
+ * `useBezoar` connects on its first call, with the driver of the runtime
+ * config, and makes the service. Every call after returns the same service.
+ * `closeBezoar` closes the connection. The next `useBezoar` connects
+ * again.
+ *
+ * @param contract - The contract of the build.
+ * @param queries - The SQL of the build.
+ */
+export declare const defineService: <const D extends Definition>(contract: D, queries: Bundle<D>) => Defined<D>;
+export type { Arguments, Query, Row };

package/.dist/runtime/server/service.js

@@ -0,0 +1,34 @@
+import { useRuntimeConfig } from "#imports";
+import { pg } from "@bezoar/pg";
+import { pglite } from "@bezoar/pglite";
+import { makeBezoar } from "bezoar";
+const connect = (config) => {
+	if (config.driver === "pglite") return pglite(config.dataDir === "" ? {} : config.dataDir);
+	if (config.url === "") throw new Error("bezoar: no connection string; set NUXT_BEZOAR_URL, or runtimeConfig.bezoar.url");
+	return pg(config.url);
+};
+const defineService = (contract, queries) => {
+	let connection;
+	let service;
+	const useBezoar = () => {
+		if (service === void 0) {
+			connection = connect(useRuntimeConfig().bezoar);
+			service = makeBezoar(contract, {
+				executor: connection,
+				queries
+			});
+		}
+		return service;
+	};
+	const closeBezoar = async () => {
+		const open = connection;
+		connection = void 0;
+		service = void 0;
+		await open?.close();
+	};
+	return {
+		useBezoar,
+		closeBezoar
+	};
+};
+export { defineService };

package/.dist/runtime/server/startup.d.ts

@@ -0,0 +1,21 @@
+import { Defined } from "./service.js";
+import { Definition, Migration, Seed } from "bezoar";
+/**
+ * What the plugin of an app runs with: its service, and the migrations and
+ * the seeds of its build.
+ */
+export interface Startup<D extends Definition> extends Defined<D> {
+  migrations: readonly Migration[];
+  seeds: readonly Seed[];
+}
+/**
+ * Defines the plugin of an app. The plugin of the runtime calls this with
+ * the virtual service and the virtual build of the app.
+ *
+ * The plugin makes the service when the server starts. When the runtime
+ * config asks, it applies the migrations of the build and runs its seeds.
+ * It closes the connection when the server stops.
+ *
+ * @param startup - The service, the migrations, and the seeds.
+ */
+export declare const definePlugin: <D extends Definition>(startup: Startup<D>) => (nitroApp: import("#imports").NitroApp) => Promise<void>;

package/.dist/runtime/server/startup.js

@@ -0,0 +1,9 @@
+import { defineNitroPlugin, useRuntimeConfig } from "#imports";
+const definePlugin = (startup) => defineNitroPlugin(async (nitroApp) => {
+	const { migrate, seed } = useRuntimeConfig().bezoar;
+	const db = startup.useBezoar();
+	if (migrate) await db.migrate(startup.migrations);
+	if (seed) await db.seed(startup.seeds);
+	nitroApp.hooks.hook("close", startup.closeBezoar);
+});
+export { definePlugin };

package/.dist/runtime/server/types.d.ts

@@ -0,0 +1,6 @@
+import { BezoarRuntimeConfig } from "../../config.js";
+declare module "nuxt/schema" {
+  interface RuntimeConfig {
+    bezoar: BezoarRuntimeConfig;
+  }
+}

package/.dist/runtime/server/types.js

@@ -0,0 +1 @@
+export {};

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Thorwaldson
+
+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

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @bezoar/nuxt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Nuxt module for bezoar. The module takes a kit build and gives the server
+a typed database service.
+
+## Install
+
+```sh
+pnpm add @bezoar/nuxt
+```
+
+## Setup
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@bezoar/nuxt"],
+  bezoar: { build: "@acme/database", migrate: true },
+});
+```
+
+`build` names a kit build: a package whose main entry is the `index.mjs`
+that `bezoar build` wrote, or a path to that directory. The module adds
+two virtual modules to the server build: `#bezoar/build`, which
+re-exports the modules of the kit build, and `#bezoar/service`, the
+service over its contract and its SQL. It writes a declaration of the
+service into the build directory. `useBezoar()` and its types come from
+the virtual service, so they are typed by the build. The modules are virtual
+so that Nitro bundles them in dev as in production; the server plugin of
+the module imports both.
+
+## Connection
+
+The module reads `runtimeConfig.bezoar`. An environment variable sets
+each member.
+
+| Member    | Variable               | Meaning                                     |
+| --------- | ---------------------- | ------------------------------------------- |
+| `url`     | `NUXT_BEZOAR_URL`      | The connection string, for the `pg` driver  |
+| `dataDir` | `NUXT_BEZOAR_DATA_DIR` | The data directory, for the `pglite` driver |
+| `driver`  | `NUXT_BEZOAR_DRIVER`   | `pg` or `pglite`. Defaults to `pg`          |
+| `migrate` | `NUXT_BEZOAR_MIGRATE`  | Apply the migrations when the server starts |
+| `seed`    | `NUXT_BEZOAR_SEED`     | Run the seeds when the server starts        |
+
+`driver`, `migrate`, and `seed` can also be set in the module options. A
+value in the runtime config wins.
+
+The `pg` driver connects to a Postgres server and needs `url`. The `pglite`
+driver runs Postgres in the process, on `dataDir`, or in memory when it is
+empty. A server with the `pg` driver and no `url` fails to start.
+
+## In a server route
+
+```ts
+export default defineEventHandler(async (event) => {
+  const db = useBezoar();
+  const { day } = await getValidatedQuery(
+    event,
+    db.schema.validators.queries["events.list"].arguments.parse,
+  );
+  return db.events.list({ day });
+});
+```
+
+`useBezoar()` is auto-imported on the server. It returns the same service
+on every call, typed by the contract of the build, so `db.events.list`
+completes, and its arguments and rows check. `AppBezoar`,
+`AppBezoarContract`, `AppBezoarQuery`, `AppBezoarArguments<Q>`, and
+`AppBezoarRow<Q>` are the types, also auto-imported.
+
+## Startup and shutdown
+
+A server plugin makes the service when the server starts. With `migrate`,
+it applies the migrations of the build first, through `migrate` of
+`@bezoar/core`, under an advisory lock, so instances that start together
+apply each migration once. With `seed`, it runs the seeds after. When the
+server stops, the plugin closes the connection. `closeBezoar()` closes it
+by hand.
+
+## Runtime
+
+The `pg` driver needs a Node runtime, which the Node server presets of Nuxt
+and the functions of Vercel are.
+
+## Related
+
+- [`bezoar`](../../packages/bezoar): the runtime.
+- [`@bezoar/kit`](../../packages/kit): builds the contract the module
+  adopts.

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@bezoar/nuxt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Nuxt module for bezoar: a typed database service for server routes, from a kit build",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/bezoar.git",
+    "directory": "integrations/nuxt"
+  },
+  "type": "module",
+  "main": "./.dist/module.js",
+  "types": "./.dist/module.d.ts",
+  "exports": {
+    ".": {
+      "types": "./.dist/module.d.ts",
+      "import": "./.dist/module.js"
+    },
+    "./config": {
+      "types": "./.dist/config.d.ts",
+      "import": "./.dist/config.js"
+    },
+    "./constant": {
+      "types": "./.dist/constant.d.ts",
+      "import": "./.dist/constant.js"
+    }
+  },
+  "files": [
+    ".dist"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.5.0",
+    "objectively": "^0.3.0",
+    "@bezoar/pg": "0.0.2",
+    "@bezoar/pglite": "0.0.2",
+    "bezoar": "0.0.2"
+  },
+  "devDependencies": {
+    "@nuxt/nitro-server": "^4.5.0",
+    "@nuxt/schema": "^4.5.0",
+    "@types/node": "^25.9.9",
+    "nuxt": "^4.5.0"
+  },
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }