@katajs/drizzle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaseer A. Okino
+
+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

@@ -0,0 +1,77 @@
+# @katajs/drizzle
+
+Drizzle adapter for [katajs](https://github.com/ookino/katajs) — wires [Drizzle ORM](https://orm.drizzle.team) to [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/) for Postgres.
+
+```bash
+pnpm add @katajs/drizzle drizzle-orm pg
+```
+
+## Usage
+
+```ts
+import { createApp } from '@katajs/core';
+import { drizzleAdapter } from '@katajs/drizzle';
+import * as schema from './db/schema';
+
+type Bindings = {
+  HYPERDRIVE: Hyperdrive;
+};
+
+const { app } = createApp({
+  bindings: {} as Bindings,
+  db: drizzleAdapter({ schema }),
+  modules: [/* ... */],
+});
+```
+
+`drizzleAdapter` returns a `DbAdapter` that katajs's container middleware uses to construct a per-request `db` client backed by `env.HYPERDRIVE.connectionString`.
+
+## Transactions
+
+```ts
+// inside a service
+async create(input: CreatePostInput) {
+  return c.withTransaction(async (tx) => {
+    const post = await tx.resolve('postRepository').insert(input);
+    await tx.resolve('auditService').log({ action: 'post.create', id: post.id });
+    return post;
+  });
+}
+```
+
+`withTransaction` wraps `db.transaction(...)` and rebuilds a sub-container where every repository uses the transaction-bound `tx` client. Non-repository services are reused from the outer container. Nested calls reuse the outer transaction (no savepoints in v0.1).
+
+## Public API
+
+```ts
+export { drizzleAdapter } from '@katajs/drizzle';
+export type {
+  DrizzleAdapterConfig,
+  DrizzleClient,
+  DrizzleClientOrTx,
+  DrizzleTx,
+  HyperdriveBinding,
+} from '@katajs/drizzle';
+```
+
+## Local development
+
+When developing locally with `wrangler dev`, configure `wrangler.jsonc` with a `localConnectionString` for the Hyperdrive binding:
+
+```jsonc
+{
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+      "id": "<your-hyperdrive-id>",
+      "localConnectionString": "postgres://postgres:postgres@localhost:5432/myapp"
+    }
+  ]
+}
+```
+
+The binding `id` is required even locally; use any UUID until you've created the real Hyperdrive resource.
+
+## License
+
+[MIT](./LICENSE) © Yaseer A. Okino

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { ExtractTablesWithRelations } from 'drizzle-orm';
+import { PgTransaction, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+
+/** Drizzle client bound to node-postgres against a Hyperdrive connection. */
+type DrizzleClient<TSchema extends Record<string, unknown> = Record<string, never>> = NodePgDatabase<TSchema>;
+/** Drizzle transaction handle (same query API as the client). */
+type DrizzleTx<TSchema extends Record<string, unknown> = Record<string, never>> = PgTransaction<PgQueryResultHKT, TSchema, ExtractTablesWithRelations<TSchema>>;
+type DrizzleClientOrTx<TSchema extends Record<string, unknown> = Record<string, never>> = DrizzleClient<TSchema> | DrizzleTx<TSchema>;
+
+/** Cloudflare Hyperdrive binding shape (per `env.HYPERDRIVE`). */
+type HyperdriveBinding = {
+    connectionString: string;
+};
+type DrizzleAdapterConfig<TSchema extends Record<string, unknown> = Record<string, never>> = {
+    /** Drizzle relational schema. Required for `db.query.<table>` API. */
+    schema?: TSchema;
+    /**
+     * Override the Hyperdrive binding key on `env`. Default `HYPERDRIVE`.
+     * Useful when a project uses multiple bindings or a non-conventional name.
+     */
+    bindingName?: string;
+    /**
+     * Inject a custom client factory. When provided, `bindingName` is ignored.
+     * Primarily for tests; production code should let the adapter build the pool.
+     */
+    makeClient?: (env: unknown) => DrizzleClient<TSchema>;
+};
+/**
+ * Drizzle adapter targeting Cloudflare Hyperdrive (Postgres). Per spec §6.2
+ * uses `pg` (`node-postgres`) with `nodejs_compat`.
+ *
+ *   const { app } = createApp({
+ *     bindings: {} as Bindings,
+ *     db: drizzleAdapter({ schema }),
+ *     modules: [...],
+ *   });
+ */
+declare function drizzleAdapter<TSchema extends Record<string, unknown> = Record<string, never>>(config?: DrizzleAdapterConfig<TSchema>): {
+    create(env: unknown): DrizzleClient<TSchema>;
+    /**
+     * Run a function inside a Drizzle transaction. Surfaces the txDb to the
+     * caller via Drizzle's native `db.transaction(...)`. v0.1 has no
+     * savepoints — nested calls reuse the outer transaction (handled by core).
+     */
+    runTransaction<T>(db: DrizzleClient<TSchema>, fn: (txDb: DrizzleTx<TSchema>) => Promise<T>): Promise<T>;
+};
+
+export { type DrizzleAdapterConfig, type DrizzleClient, type DrizzleClientOrTx, type DrizzleTx, type HyperdriveBinding, drizzleAdapter };

package/dist/index.js

@@ -0,0 +1,31 @@
+// src/adapter.ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+function drizzleAdapter(config = {}) {
+  const bindingName = config.bindingName ?? "HYPERDRIVE";
+  return {
+    create(env) {
+      if (config.makeClient) return config.makeClient(env);
+      const binding = env?.[bindingName];
+      if (!binding?.connectionString) {
+        throw new Error(
+          `[katajs] Missing '${bindingName}' binding or its connectionString. Add a Hyperdrive binding to wrangler.jsonc, or pass 'makeClient' for tests.`
+        );
+      }
+      const pool = new Pool({ connectionString: binding.connectionString });
+      return drizzle(pool, { schema: config.schema });
+    },
+    /**
+     * Run a function inside a Drizzle transaction. Surfaces the txDb to the
+     * caller via Drizzle's native `db.transaction(...)`. v0.1 has no
+     * savepoints — nested calls reuse the outer transaction (handled by core).
+     */
+    async runTransaction(db, fn) {
+      return db.transaction(async (txDb) => fn(txDb));
+    }
+  };
+}
+export {
+  drizzleAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapter.ts"],"sourcesContent":["import { drizzle } from 'drizzle-orm/node-postgres';\nimport { Pool } from 'pg';\nimport type { DrizzleClient, DrizzleTx } from './types';\n\n/** Cloudflare Hyperdrive binding shape (per `env.HYPERDRIVE`). */\nexport type HyperdriveBinding = {\n  connectionString: string;\n};\n\nexport type DrizzleAdapterConfig<\n  TSchema extends Record<string, unknown> = Record<string, never>,\n> = {\n  /** Drizzle relational schema. Required for `db.query.<table>` API. */\n  schema?: TSchema;\n  /**\n   * Override the Hyperdrive binding key on `env`. Default `HYPERDRIVE`.\n   * Useful when a project uses multiple bindings or a non-conventional name.\n   */\n  bindingName?: string;\n  /**\n   * Inject a custom client factory. When provided, `bindingName` is ignored.\n   * Primarily for tests; production code should let the adapter build the pool.\n   */\n  makeClient?: (env: unknown) => DrizzleClient<TSchema>;\n};\n\n/**\n * Drizzle adapter targeting Cloudflare Hyperdrive (Postgres). Per spec §6.2\n * uses `pg` (`node-postgres`) with `nodejs_compat`.\n *\n *   const { app } = createApp({\n *     bindings: {} as Bindings,\n *     db: drizzleAdapter({ schema }),\n *     modules: [...],\n *   });\n */\nexport function drizzleAdapter<\n  TSchema extends Record<string, unknown> = Record<string, never>,\n>(config: DrizzleAdapterConfig<TSchema> = {}) {\n  const bindingName = config.bindingName ?? 'HYPERDRIVE';\n\n  return {\n    create(env: unknown): DrizzleClient<TSchema> {\n      if (config.makeClient) return config.makeClient(env);\n\n      const binding = (env as Record<string, unknown> | null | undefined)?.[\n        bindingName\n      ] as HyperdriveBinding | undefined;\n\n      if (!binding?.connectionString) {\n        throw new Error(\n          `[katajs] Missing '${bindingName}' binding or its connectionString. ` +\n            `Add a Hyperdrive binding to wrangler.jsonc, or pass 'makeClient' for tests.`,\n        );\n      }\n\n      const pool = new Pool({ connectionString: binding.connectionString });\n      return drizzle(pool, { schema: config.schema }) as DrizzleClient<TSchema>;\n    },\n\n    /**\n     * Run a function inside a Drizzle transaction. Surfaces the txDb to the\n     * caller via Drizzle's native `db.transaction(...)`. v0.1 has no\n     * savepoints — nested calls reuse the outer transaction (handled by core).\n     */\n    async runTransaction<T>(\n      db: DrizzleClient<TSchema>,\n      fn: (txDb: DrizzleTx<TSchema>) => Promise<T>,\n    ): Promise<T> {\n      return db.transaction(async (txDb) => fn(txDb as DrizzleTx<TSchema>));\n    },\n  };\n}\n"],"mappings":";AAAA,SAAS,eAAe;AACxB,SAAS,YAAY;AAmCd,SAAS,eAEd,SAAwC,CAAC,GAAG;AAC5C,QAAM,cAAc,OAAO,eAAe;AAE1C,SAAO;AAAA,IACL,OAAO,KAAsC;AAC3C,UAAI,OAAO,WAAY,QAAO,OAAO,WAAW,GAAG;AAEnD,YAAM,UAAW,MACf,WACF;AAEA,UAAI,CAAC,SAAS,kBAAkB;AAC9B,cAAM,IAAI;AAAA,UACR,qBAAqB,WAAW;AAAA,QAElC;AAAA,MACF;AAEA,YAAM,OAAO,IAAI,KAAK,EAAE,kBAAkB,QAAQ,iBAAiB,CAAC;AACpE,aAAO,QAAQ,MAAM,EAAE,QAAQ,OAAO,OAAO,CAAC;AAAA,IAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,MAAM,eACJ,IACA,IACY;AACZ,aAAO,GAAG,YAAY,OAAO,SAAS,GAAG,IAA0B,CAAC;AAAA,IACtE;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@katajs/drizzle",
+  "version": "0.1.0",
+  "description": "Drizzle adapter for katajs — Hyperdrive-backed Postgres on Cloudflare Workers.",
+  "keywords": [
+    "katajs",
+    "drizzle",
+    "drizzle-orm",
+    "hyperdrive",
+    "cloudflare",
+    "workers",
+    "postgres"
+  ],
+  "license": "MIT",
+  "author": "Yaseer A. Okino <yaseerokino@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ookino/katajs.git",
+    "directory": "packages/drizzle"
+  },
+  "homepage": "https://github.com/ookino/katajs/tree/main/packages/drizzle#readme",
+  "bugs": {
+    "url": "https://github.com/ookino/katajs/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "drizzle-orm": ">=0.36.0",
+    "pg": "^8.13.0",
+    "@katajs/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.10",
+    "drizzle-orm": "^0.36.4",
+    "pg": "^8.13.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.5",
+    "@katajs/core": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}