@vibeorm/runtime 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# @vibeorm/runtime
+
+Driver-agnostic query engine and client runtime for VibeORM. This package contains the SQL query builder, WHERE clause compiler, relation loading strategies, and client factory. It does **not** include any database driver — use an adapter package to connect to PostgreSQL.
+
+## Installation
+
+```bash
+bun add @vibeorm/runtime
+```
+
+You also need an adapter:
+
+```bash
+bun add @vibeorm/adapter-bun    # for bun:sql
+# or
+bun add @vibeorm/adapter-pg pg  # for node-postgres
+```
+
+## Usage
+
+This package is consumed by the generated client. You typically don't import from it directly — the generated `index.ts` calls `createClient()` internally.
+
+```ts
+// The generated client wires everything together:
+import { VibeClient } from "./generated/vibeorm/index.ts";
+
+const db = VibeClient({
+  relationStrategy: "query",
+  log: false,
+});
+```
+
+## API
+
+### `createClient({ options, modelMeta, schemas? })`
+
+Creates a VibeORM client instance. Called by generated code — takes model metadata, optional Zod schemas, and client options.
+
+### `toSqlExecutor({ adapter })`
+
+Bridges a `DatabaseAdapter` to a `SqlExecutor` for use with the migrate package.
+
+### `VibeValidationError`
+
+Custom error class thrown when Zod validation fails on input or output data.
+
+### `DatabaseAdapter` interface
+
+The contract that adapter packages implement:
+
+```ts
+type DatabaseAdapter = {
+  execute(params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]>;
+  executeRaw(params: { text: string; values: unknown[] }): Promise<QueryResult>;
+  transaction<T>(params: { fn: (adapter: DatabaseAdapter) => Promise<T> }): Promise<T>;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+};
+```
+
+### Relation Loading Strategies
+
+| Strategy | Method | Best for |
+|----------|--------|----------|
+| `"query"` | Parent query + batched `WHERE IN` queries | Deep/nested includes |
+| `"join"` | `LEFT JOIN LATERAL` + JSON aggregation | Flat includes, fewer round-trips |
+
+### Exported Types
+
+`DatabaseAdapter`, `QueryResult`, `SqlExecutor`, `VibeClientOptions`, `ModelMeta`, `ModelMetaMap`, `ModelSchemas`, `ValidationSchema`, `QueryProfile`, `RelationProfile`, `ScalarFieldMeta`, `RelationFieldMeta`, `SqlQuery`, `Operation`.
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vibeorm/runtime",
+  "version": "1.0.0",
+  "description": "Driver-agnostic query engine and client runtime for VibeORM",
+  "license": "MIT",
+  "keywords": [
+    "orm",
+    "runtime",
+    "query-builder",
+    "bun",
+    "typescript",
+    "postgresql"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeorm/vibeorm.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/runtime",
+  "bugs": {
+    "url": "https://github.com/vibeorm/vibeorm/issues"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "peerDependencies": {
+    "zod": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,114 @@
+/**
+ * Database adapter interface for VibeORM.
+ *
+ * Each adapter implementation (bun:sql, pg, etc.) provides a concrete
+ * implementation of this interface. The runtime is completely driver-agnostic
+ * and interacts with the database exclusively through this contract.
+ */
+
+// ─── Core Adapter Interface ───────────────────────────────────────
+
+/**
+ * The primary interface that every database adapter must implement.
+ * Adapters own connection management, query execution, statement caching,
+ * transactions, and driver-specific parameter formatting.
+ */
+export type DatabaseAdapter = {
+  /**
+   * Execute a parameterized query and return rows.
+   * The adapter owns statement caching and driver-specific optimizations.
+   *
+   * For bun:sql this means synthetic tagged template caching.
+   * For pg this means named prepared statement caching.
+   */
+  execute(params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]>;
+
+  /**
+   * Execute a raw/unsafe query without prepared statement caching.
+   * Used for `$queryRawUnsafe`, `$executeRawUnsafe`, and dynamic DDL.
+   *
+   * Returns both rows and affected row count (for INSERT/UPDATE/DELETE).
+   */
+  executeUnsafe(params: {
+    text: string;
+    values?: unknown[];
+  }): Promise<QueryResult>;
+
+  /**
+   * Run a function inside a database transaction.
+   * The callback receives a transactional adapter with the same interface.
+   * If the callback throws, the transaction is automatically rolled back.
+   */
+  transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T>;
+
+  /**
+   * Eagerly warm up the connection pool.
+   * Forces at least one TCP handshake + auth so subsequent queries start instantly.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Gracefully close all connections in the pool.
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Convert a JS array to the driver's preferred format for `= ANY($N)` queries.
+   *
+   * - **bun:sql**: Returns a PG array literal string `"{val1,val2,val3}"` because
+   *   bun:sql's extended query protocol sends values as strings.
+   * - **pg**: Returns the raw JS array (pg driver handles native array serialization).
+   */
+  formatArrayParam(values: unknown[]): unknown;
+};
+
+// ─── Query Result ─────────────────────────────────────────────────
+
+/**
+ * Result from an unsafe query execution.
+ * Contains both the rows returned and the number of affected rows
+ * (parsed from the PostgreSQL CommandComplete tag).
+ */
+export type QueryResult = {
+  rows: Record<string, unknown>[];
+  affectedRows: number;
+};
+
+// ─── SQL Executor (Migration Compatibility) ───────────────────────
+
+/**
+ * Minimal SQL execution interface compatible with `@vibeorm/migrate`.
+ * Adapters expose this via a helper function so migrations can run
+ * without knowing which adapter is in use.
+ *
+ * @example
+ * ```ts
+ * import { bunAdapter } from "@vibeorm/adapter-bun";
+ * import { toSqlExecutor } from "@vibeorm/runtime";
+ *
+ * const adapter = bunAdapter({ url: "postgres://..." });
+ * const executor = toSqlExecutor({ adapter });
+ * await applyMigration({ executor, migrationName: "init", sql, checksum });
+ * ```
+ */
+export type SqlExecutor = (params: {
+  text: string;
+  values?: unknown[];
+}) => Promise<Record<string, unknown>[]>;
+
+/**
+ * Create an SqlExecutor from a DatabaseAdapter.
+ * Bridges the adapter pattern with the migrate package's SqlExecutor interface.
+ */
+export function toSqlExecutor(params: {
+  adapter: DatabaseAdapter;
+}): SqlExecutor {
+  const { adapter } = params;
+  return async (queryParams) => {
+    const result = await adapter.executeUnsafe({
+      text: queryParams.text,
+      values: queryParams.values,
+    });
+    return result.rows;
+  };
+}