@prisma-next/sqlite 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# @prisma-next/sqlite
+
+Composition-root SQLite helper that builds a Prisma Next runtime client and exposes SQL, ORM, and schema query access.
+
+## Package Classification
+
+- **Domain**: extensions
+- **Layer**: adapters
+- **Plane**: runtime
+
+## Overview
+
+`@prisma-next/sqlite/runtime` exposes a single `sqlite(...)` helper that composes the SQLite execution stack and returns query/runtime roots:
+
+- `db.sql`
+- `db.orm`
+- `db.context`
+- `db.stack`
+
+Runtime resources are deferred until `db.runtime()` or `db.connect(...)` is called.
+Connection binding can be provided up front (`path`) or deferred via `db.connect(...)`.
+
+## Responsibilities
+
+- Build a static SQLite execution stack from target, adapter, and driver descriptors
+- Build typed SQL surface from the execution context via `sql-query-builder-new`
+- Build ORM surface from the execution context
+- Normalize runtime binding input (file path or `:memory:`)
+- Lazily instantiate runtime resources on first `db.runtime()` or `db.connect(...)` call
+- Connect the internal SQLite driver through `db.connect(...)` or from initial binding options
+- Memoize runtime so repeated `db.runtime()` calls return one instance
+
+## Dependencies
+
+- **`@prisma-next/sql-runtime`** for stack/context/runtime primitives
+- **`@prisma-next/framework-components`** for stack instantiation
+- **`@prisma-next/target-sqlite`** for target descriptor
+- **`@prisma-next/adapter-sqlite`** for adapter descriptor
+- **`@prisma-next/driver-sqlite`** for driver descriptor
+- **`@prisma-next/sql-builder`** for `sql(...)` query builder
+- **`@prisma-next/sql-relational-core`** for `schema(...)`
+- **`@prisma-next/sql-orm-client`** for `orm(...)`
+- **`@prisma-next/sql-contract`** for `validateContract(...)` and contract types
+
+## Architecture
+
+```mermaid
+flowchart TD
+    App[App Code] --> Client["sqlite(...)"]
+    Client --> Static["Roots: sql orm context stack"]
+    Client --> Lazy["runtime()"]
+
+    Lazy --> Instantiate[instantiateExecutionStack]
+    Lazy --> Bind["Resolve binding: path or :memory:"]
+    Bind --> DB["DatabaseSync via node:sqlite"]
+    Lazy --> Runtime[createRuntime]
+
+    Runtime --> Target["@prisma-next/target-sqlite"]
+    Runtime --> Adapter["@prisma-next/adapter-sqlite"]
+    Runtime --> Driver["@prisma-next/driver-sqlite"]
+    Runtime --> SqlRuntime["@prisma-next/sql-runtime"]
+    Runtime --> ExecPlane["@prisma-next/framework-components/execution"]
+```
+
+## Related Docs
+
+- Architecture: `docs/Architecture Overview.md`
+- Subsystem: `docs/architecture docs/subsystems/4. Runtime & Middleware Framework.md`
+- Subsystem: `docs/architecture docs/subsystems/5. Adapters & Targets.md`

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@prisma-next/sqlite",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "One-liner lazy SQLite client composition for Prisma Next",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/adapter-sqlite": "workspace:*",
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/driver-sqlite": "workspace:*",
+    "@prisma-next/framework-components": "workspace:*",
+    "@prisma-next/sql-builder": "workspace:*",
+    "@prisma-next/sql-contract": "workspace:*",
+    "@prisma-next/sql-orm-client": "workspace:*",
+    "@prisma-next/sql-relational-core": "workspace:*",
+    "@prisma-next/sql-runtime": "workspace:*",
+    "@prisma-next/target-sqlite": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/test-utils": "workspace:*",
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/3-extensions/sqlite"
+  },
+  "exports": {
+    "./runtime": "./dist/runtime.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/runtime.mjs",
+  "module": "./dist/runtime.mjs",
+  "types": "./dist/runtime.d.mts"
+}

package/src/exports/runtime.ts

@@ -0,0 +1,10 @@
+export type { SqliteBindingInput } from '../runtime/binding';
+export type {
+  SqliteClient,
+  SqliteOptions,
+  SqliteOptionsBase,
+  SqliteOptionsWithContract,
+  SqliteOptionsWithContractJson,
+  SqliteTargetId,
+} from '../runtime/sqlite';
+export { default } from '../runtime/sqlite';

package/src/runtime/binding.ts

@@ -0,0 +1,16 @@
+import type { SqliteBinding } from '@prisma-next/driver-sqlite/runtime';
+
+export type SqliteBindingInput = { readonly path: string };
+
+export function resolveSqliteBinding(input: SqliteBindingInput): SqliteBinding {
+  return { kind: 'path', path: input.path };
+}
+
+export function resolveOptionalSqliteBinding(options: {
+  readonly path?: string;
+}): SqliteBinding | undefined {
+  if (options.path === undefined) {
+    return undefined;
+  }
+  return { kind: 'path', path: options.path };
+}

package/src/runtime/sqlite.ts

@@ -0,0 +1,199 @@
+import sqliteAdapter from '@prisma-next/adapter-sqlite/runtime';
+import type { Contract } from '@prisma-next/contract/types';
+import type { SqliteBinding } from '@prisma-next/driver-sqlite/runtime';
+import sqliteDriver from '@prisma-next/driver-sqlite/runtime';
+import { emptyCodecLookup } from '@prisma-next/framework-components/codec';
+import { instantiateExecutionStack } from '@prisma-next/framework-components/execution';
+import { sql as sqlBuilder } from '@prisma-next/sql-builder/runtime';
+import type { Db } from '@prisma-next/sql-builder/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { validateContract } from '@prisma-next/sql-contract/validate';
+import { orm as ormBuilder } from '@prisma-next/sql-orm-client';
+import type {
+  ExecutionContext,
+  Middleware,
+  Runtime,
+  RuntimeVerifyOptions,
+  SqlExecutionStackWithDriver,
+  SqlRuntimeExtensionDescriptor,
+} from '@prisma-next/sql-runtime';
+import {
+  createExecutionContext,
+  createRuntime,
+  createSqlExecutionStack,
+} from '@prisma-next/sql-runtime';
+import sqliteTarget from '@prisma-next/target-sqlite/runtime';
+import { resolveOptionalSqliteBinding, resolveSqliteBinding } from './binding';
+
+export type SqliteTargetId = 'sqlite';
+type OrmClient<TContract extends Contract<SqlStorage>> = ReturnType<typeof ormBuilder<TContract>>;
+
+export interface SqliteClient<TContract extends Contract<SqlStorage>> {
+  readonly sql: Db<TContract>;
+  readonly orm: OrmClient<TContract>;
+  readonly context: ExecutionContext<TContract>;
+  readonly stack: SqlExecutionStackWithDriver<SqliteTargetId>;
+  connect(bindingInput?: { readonly path: string }): Promise<Runtime>;
+  runtime(): Runtime;
+}
+
+export interface SqliteOptionsBase<TContract extends Contract<SqlStorage>> {
+  readonly extensions?: readonly SqlRuntimeExtensionDescriptor<SqliteTargetId>[];
+  readonly middleware?: readonly Middleware<TContract>[];
+  readonly verify?: RuntimeVerifyOptions;
+}
+
+export type SqliteOptionsWithContract<TContract extends Contract<SqlStorage>> = {
+  readonly path?: string;
+} & SqliteOptionsBase<TContract> & {
+    readonly contract: TContract;
+    readonly contractJson?: never;
+  };
+
+export type SqliteOptionsWithContractJson<TContract extends Contract<SqlStorage>> = {
+  readonly path?: string;
+} & SqliteOptionsBase<TContract> & {
+    readonly contractJson: unknown;
+    readonly contract?: never;
+  };
+
+export type SqliteOptions<TContract extends Contract<SqlStorage>> =
+  | SqliteOptionsWithContract<TContract>
+  | SqliteOptionsWithContractJson<TContract>;
+
+function resolveContract<TContract extends Contract<SqlStorage>>(
+  options: SqliteOptions<TContract>,
+): TContract {
+  const contractInput =
+    'contractJson' in options && options.contractJson !== undefined
+      ? options.contractJson
+      : (options as SqliteOptionsWithContract<TContract>).contract;
+  return validateContract<TContract>(contractInput, emptyCodecLookup);
+}
+
+export default function sqlite<TContract extends Contract<SqlStorage>>(
+  options: SqliteOptionsWithContract<TContract>,
+): SqliteClient<TContract>;
+export default function sqlite<TContract extends Contract<SqlStorage>>(
+  options: SqliteOptionsWithContractJson<TContract>,
+): SqliteClient<TContract>;
+export default function sqlite<TContract extends Contract<SqlStorage>>(
+  options: SqliteOptions<TContract>,
+): SqliteClient<TContract> {
+  const contract = resolveContract(options);
+  let binding = resolveOptionalSqliteBinding(options);
+  const stack = createSqlExecutionStack({
+    target: sqliteTarget,
+    adapter: sqliteAdapter,
+    driver: sqliteDriver,
+    extensionPacks: options.extensions ?? [],
+  });
+
+  const context = createExecutionContext({
+    contract,
+    stack,
+  });
+
+  const sql: Db<TContract> = sqlBuilder<TContract>({ context });
+  let runtimeInstance: Runtime | undefined;
+  let runtimeDriver: { connect(binding: unknown): Promise<void> } | undefined;
+  let driverConnected = false;
+  let connectPromise: Promise<void> | undefined;
+  let backgroundConnectError: unknown;
+
+  const connectDriver = async (resolvedBinding: SqliteBinding): Promise<void> => {
+    if (driverConnected) return;
+    if (!runtimeDriver) throw new Error('SQLite runtime driver missing');
+    if (connectPromise) return connectPromise;
+    connectPromise = runtimeDriver
+      .connect(resolvedBinding)
+      .then(() => {
+        driverConnected = true;
+      })
+      .catch((err) => {
+        backgroundConnectError = err;
+        connectPromise = undefined;
+        throw err;
+      });
+    return connectPromise;
+  };
+
+  const getRuntime = (): Runtime => {
+    if (backgroundConnectError !== undefined) {
+      throw backgroundConnectError;
+    }
+
+    if (runtimeInstance) {
+      return runtimeInstance;
+    }
+
+    const stackInstance = instantiateExecutionStack(stack);
+    const driverDescriptor = stack.driver;
+    if (!driverDescriptor) {
+      throw new Error('Driver descriptor missing from execution stack');
+    }
+
+    const driver = driverDescriptor.create();
+    runtimeDriver = driver;
+    if (binding !== undefined) {
+      void connectDriver(binding).catch(() => undefined);
+    }
+
+    runtimeInstance = createRuntime({
+      stackInstance,
+      context,
+      driver,
+      verify: options.verify ?? { mode: 'onFirstUse', requireMarker: false },
+      ...(options.middleware ? { middleware: options.middleware } : {}),
+    });
+
+    return runtimeInstance;
+  };
+
+  const orm: OrmClient<TContract> = ormBuilder({
+    context,
+    runtime: {
+      execute(plan) {
+        return getRuntime().execute(plan);
+      },
+      connection() {
+        return getRuntime().connection();
+      },
+    },
+  });
+
+  return {
+    sql,
+    orm,
+    context,
+    stack,
+    async connect(bindingInput) {
+      if (driverConnected || connectPromise) {
+        throw new Error('SQLite client already connected');
+      }
+
+      backgroundConnectError = undefined;
+
+      if (bindingInput !== undefined) {
+        binding = resolveSqliteBinding(bindingInput);
+      }
+
+      if (binding === undefined) {
+        throw new Error(
+          'SQLite binding not configured. Pass path to sqlite(...) or call db.connect({ path }).',
+        );
+      }
+
+      const runtime = getRuntime();
+      if (driverConnected) {
+        return runtime;
+      }
+
+      await connectDriver(binding);
+      return runtime;
+    },
+    runtime() {
+      return getRuntime();
+    },
+  };
+}