@zeno-lib/db 0.5.0 → 0.7.0-beta.0

package/dist/config.mjs

@@ -1,4 +1,41 @@
 import { defineConfig } from "drizzle-kit";
+import { existsSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { styleText } from "node:util";
+//#region src/move-generated-sql.ts
+const GENERATED_SQL = "migration.sql";
+/**
+* Move each `<name>/migration.sql` to `<name>.sql`,
+* because the Supabase CLI only reads `.sql` files at the top of the folder.
+* Throws if a `<name>.sql` already exists.
+*/
+function moveGeneratedSql(options) {
+	const { migrationsDir } = options;
+	const names = existsSync(migrationsDir) ? readdirSync(migrationsDir).filter((name) => existsSync(join(migrationsDir, name, GENERATED_SQL))).sort() : [];
+	const taken = names.map((name) => join(migrationsDir, `${name}.sql`)).filter((target) => existsSync(target));
+	if (taken.length > 0) throw new Error(`Cannot move the generated SQL, because these files already exist: ${taken.join(", ")}`);
+	return { moved: names.map((name) => {
+		const target = join(migrationsDir, `${name}.sql`);
+		renameSync(join(migrationsDir, name, GENERATED_SQL), target);
+		return target;
+	}) };
+}
+/** Run `moveGeneratedSql` when `drizzle-kit generate` exits. */
+function moveGeneratedSqlAfterGenerate(options) {
+	if (process.argv[2] !== "generate") return;
+	process.once("exit", (code) => {
+		if (code !== 0) return;
+		try {
+			const check = styleText("green", "✓", { stream: process.stderr });
+			for (const path of moveGeneratedSql(options).moved) console.error(`${check} Moved the generated SQL to ${path}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(styleText("red", `✗ ${message}`, { stream: process.stderr }));
+			process.exitCode = 1;
+		}
+	});
+}
+//#endregion
 //#region src/config.ts
 /**
 * Roles a Supabase project ships that drizzle-kit's `provider: "supabase"` does
@@ -43,7 +80,7 @@ const DEFAULT_SCHEMA_FILTER = ["public"];
 function defineDrizzleConfig(overrides = {}) {
 	const { entities, ...configOverrides } = overrides;
 	const roleOverrides = typeof entities?.roles === "object" ? entities.roles : {};
-	return defineConfig({
+	const config = defineConfig({
 		dbCredentials: { url: process.env.SUPABASE_DATABASE_URL ?? "" },
 		dialect: "postgresql",
 		entities: {
@@ -59,6 +96,8 @@ function defineDrizzleConfig(overrides = {}) {
 		schemaFilter: DEFAULT_SCHEMA_FILTER,
 		...configOverrides
 	});
+	if (config.out) moveGeneratedSqlAfterGenerate({ migrationsDir: config.out });
+	return config;
 }
 //#endregion
 export { defineDrizzleConfig, supabaseManagedRoles };

package/dist/next.d.mts

@@ -87,12 +87,20 @@ interface ActionContext<TDb> {
 }
 /** An action's body: the RLS-bound `db`, the parsed input, and the context. */
 type ActionHandler<TContext extends ActionContext<unknown>, TOutput, TResult> = (db: TContext["db"], input: TOutput, context: TContext) => TResult | Promise<TResult>;
+/**
+ * What an action resolves to: the handler's result, with `undefined` (and
+ * `void`) replaced by `null`.
+ */
+type ActionValue<TResult> = undefined extends TResult ? Exclude<Exclude<TResult, undefined>, void> | null : TResult;
 /**
  * `defineAction(schema, handler)` returns the server action itself: an async
  * function that parses its argument, resolves the request context, then calls
- * `handler(db, input, context)`.
+ * `handler(db, input, context)`. A handler that resolves to `undefined`, such
+ * as a Drizzle `findFirst` that matched no row, makes the action resolve to
+ * `null`, because TanStack Query rejects a query whose function resolves to
+ * `undefined`.
  */
-type DefineAction<TContext extends ActionContext<unknown>> = <TInput, TOutput, TResult>(schema: ActionSchema<TInput, TOutput>, handler: ActionHandler<TContext, TOutput, TResult>) => (input: TInput) => Promise<TResult>;
+type DefineAction<TContext extends ActionContext<unknown>> = <TInput, TOutput, TResult>(schema: ActionSchema<TInput, TOutput>, handler: ActionHandler<TContext, TOutput, TResult>) => (input: TInput) => Promise<ActionValue<TResult>>;
 /**
  * The schema `defineFormAction` needs: the Standard Schema `validate`, which
  * reports failures as issues with paths instead of throwing. Zod 4 schemas
@@ -179,4 +187,4 @@ type RequestDb<TRelations extends AnyRelations = EmptyRelations> = {
  */
 declare function createRequestDb<TRelations extends AnyRelations = EmptyRelations>(options: CreateRequestDbOptions<TRelations>): RequestDb<TRelations>;
 //#endregion
-export { type ActionContext, type ActionError, type ActionHandler, type ActionIssue, type ActionResult, type ActionSchema, ClaimsSource, CreateRequestDbOptions, type DefineAction, type DefineFormAction, FieldValidationError, type FormActionSchema, RequestContext, RequestDb, UnauthenticatedError, createRequestDb, toActionError, toFieldName };
+export { type ActionContext, type ActionError, type ActionHandler, type ActionIssue, type ActionResult, type ActionSchema, type ActionValue, ClaimsSource, CreateRequestDbOptions, type DefineAction, type DefineFormAction, FieldValidationError, type FormActionSchema, RequestContext, RequestDb, UnauthenticatedError, createRequestDb, toActionError, toFieldName };

package/dist/next.mjs

@@ -81,7 +81,7 @@ function createDefineAction(getContext) {
 	return (schema, handler) => async (input) => {
 		const parsed = schema.parse(input);
 		const context = await getContext();
-		return await handler(context.db, parsed, context);
+		return await handler(context.db, parsed, context) ?? null;
 	};
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/db",
-  "version": "0.5.0",
+  "version": "0.7.0-beta.0",
   "type": "module",
   "exports": {
     ".": {
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@supabase/supabase-js": ">=2",
-    "drizzle-kit": "1.0.0-rc.3",
+    "drizzle-kit": "1.0.0-rc.5-5935859",
     "drizzle-orm": "1.0.0-rc.3",
     "postgres": ">=3.4",
     "react": ">=19"
@@ -71,8 +71,8 @@
     "@supabase/supabase-js": "2.116.0",
     "@types/node": "24.10.0",
     "@types/react": "19.2.14",
-    "dotenv": "17.4.2",
-    "drizzle-kit": "1.0.0-rc.3",
+    "dotenv": "18.0.4",
+    "drizzle-kit": "1.0.0-rc.5-5935859",
     "drizzle-orm": "1.0.0-rc.3",
     "postgres": "3.4.7",
     "react": "^19.2.5",
@@ -80,11 +80,11 @@
     "tsdown": "^0.22.14",
     "typescript": "7.0.2",
     "vite": "8.0.16",
-    "vitest": "4.1.11",
+    "vitest": "5.0.2",
     "zod": "^4.4.3",
     "@zeno-lib/schema": "0.2.2",
-    "@zeno-lib/typescript": "^1.1.0",
-    "@zeno-lib/test": "0.1.0"
+    "@zeno-lib/test": "0.1.0",
+    "@zeno-lib/typescript": "^1.1.0"
   },
   "scripts": {
     "build": "tsdown",
@@ -92,7 +92,6 @@
     "stop": "pnpm exec supabase stop",
     "reset": "pnpm exec supabase db reset",
     "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
     "db:push": "drizzle-kit push",
     "db:studio": "drizzle-kit studio",
     "test": "vitest --run",

package/src/config.ts

@@ -1,6 +1,7 @@
 // https://orm.drizzle.team/docs/drizzle-config-file
 // https://orm.drizzle.team/docs/rls#migrations  (entities.roles.provider: "supabase")
 import { type Config, defineConfig } from "drizzle-kit"
+import { moveGeneratedSqlAfterGenerate } from "./move-generated-sql.ts"
 
 /**
  * Roles a Supabase project ships that drizzle-kit's `provider: "supabase"` does
@@ -54,7 +55,7 @@ export function defineDrizzleConfig(
   const roleOverrides =
     typeof entities?.roles === "object" ? entities.roles : {}
 
-  return defineConfig({
+  const config = defineConfig({
     dbCredentials: { url: process.env.SUPABASE_DATABASE_URL ?? "" },
     dialect: "postgresql",
     // Tells drizzle-kit that Supabase's built-in roles (anon, authenticated,
@@ -74,4 +75,10 @@ export function defineDrizzleConfig(
     schemaFilter: DEFAULT_SCHEMA_FILTER,
     ...configOverrides,
   } as Config)
+
+  if (config.out) {
+    moveGeneratedSqlAfterGenerate({ migrationsDir: config.out })
+  }
+
+  return config
 }

package/src/define-action.ts

@@ -36,10 +36,21 @@ export type ActionHandler<
   context: TContext
 ) => TResult | Promise<TResult>
 
+/**
+ * What an action resolves to: the handler's result, with `undefined` (and
+ * `void`) replaced by `null`.
+ */
+export type ActionValue<TResult> = undefined extends TResult
+  ? Exclude<Exclude<TResult, undefined>, void> | null
+  : TResult
+
 /**
  * `defineAction(schema, handler)` returns the server action itself: an async
  * function that parses its argument, resolves the request context, then calls
- * `handler(db, input, context)`.
+ * `handler(db, input, context)`. A handler that resolves to `undefined`, such
+ * as a Drizzle `findFirst` that matched no row, makes the action resolve to
+ * `null`, because TanStack Query rejects a query whose function resolves to
+ * `undefined`.
  */
 export type DefineAction<TContext extends ActionContext<unknown>> = <
   TInput,
@@ -48,7 +59,7 @@ export type DefineAction<TContext extends ActionContext<unknown>> = <
 >(
   schema: ActionSchema<TInput, TOutput>,
   handler: ActionHandler<TContext, TOutput, TResult>
-) => (input: TInput) => Promise<TResult>
+) => (input: TInput) => Promise<ActionValue<TResult>>
 
 /**
  * Binds `defineAction` to a request-context resolver. Deliberately not a
@@ -61,12 +72,17 @@ export type DefineAction<TContext extends ActionContext<unknown>> = <
 export function createDefineAction<TContext extends ActionContext<unknown>>(
   getContext: () => Promise<TContext>
 ): DefineAction<TContext> {
-  return (schema, handler) => async (input) => {
-    const parsed = schema.parse(input)
-    const context = await getContext()
+  return <TInput, TOutput, TResult>(
+    schema: ActionSchema<TInput, TOutput>,
+    handler: ActionHandler<TContext, TOutput, TResult>
+  ) =>
+    async (input: TInput) => {
+      const parsed = schema.parse(input)
+      const context = await getContext()
+      const result = await handler(context.db, parsed, context)
 
-    return await handler(context.db, parsed, context)
-  }
+      return (result ?? null) as ActionValue<TResult>
+    }
 }
 
 /**

package/src/move-generated-sql.ts

@@ -0,0 +1,80 @@
+import { existsSync, readdirSync, renameSync } from "node:fs"
+import { join } from "node:path"
+import { styleText } from "node:util"
+
+export type MoveGeneratedSqlOptions = {
+  /** drizzle-kit writes migrations to this folder. */
+  migrationsDir: string
+}
+
+export type MoveGeneratedSqlResult = {
+  /** The new paths of the SQL files, sorted by name. */
+  moved: string[]
+}
+
+const GENERATED_SQL = "migration.sql"
+
+/**
+ * Move each `<name>/migration.sql` to `<name>.sql`,
+ * because the Supabase CLI only reads `.sql` files at the top of the folder.
+ * Throws if a `<name>.sql` already exists.
+ */
+export function moveGeneratedSql(
+  options: MoveGeneratedSqlOptions
+): MoveGeneratedSqlResult {
+  const { migrationsDir } = options
+
+  const names = existsSync(migrationsDir)
+    ? readdirSync(migrationsDir)
+        .filter((name) => existsSync(join(migrationsDir, name, GENERATED_SQL)))
+        .sort()
+    : []
+
+  const taken = names
+    .map((name) => join(migrationsDir, `${name}.sql`))
+    .filter((target) => existsSync(target))
+  if (taken.length > 0) {
+    throw new Error(
+      `Cannot move the generated SQL, because these files already exist: ${taken.join(", ")}`
+    )
+  }
+
+  const moved = names.map((name) => {
+    const target = join(migrationsDir, `${name}.sql`)
+    renameSync(join(migrationsDir, name, GENERATED_SQL), target)
+    return target
+  })
+
+  return { moved }
+}
+
+/** Run `moveGeneratedSql` when `drizzle-kit generate` exits. */
+export function moveGeneratedSqlAfterGenerate(
+  options: MoveGeneratedSqlOptions
+): void {
+  // drizzle-kit loads the config for every command.
+  // Only `generate` writes a migration.
+  if (process.argv[2] !== "generate") {
+    return
+  }
+
+  process.once("exit", (code) => {
+    if (code !== 0) {
+      return
+    }
+
+    // Print to stderr, so the JSON from `--output json` on stdout stays valid.
+    try {
+      const check = styleText("green", "✓", { stream: process.stderr })
+      for (const path of moveGeneratedSql(options).moved) {
+        console.error(`${check} Moved the generated SQL to ${path}`)
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.error(
+        styleText("red", `✗ ${message}`, { stream: process.stderr })
+      )
+      process.exitCode = 1
+    }
+  })
+}

package/src/next.test-d.ts

@@ -31,6 +31,22 @@ test("a synchronous handler still yields an async action", () => {
   expectTypeOf(action).returns.toEqualTypeOf<Promise<boolean>>()
 })
 
+test("a result that may be undefined resolves to null instead", () => {
+  const action = defineAction(z.number(), (_db, input) =>
+    Promise.resolve(input > 0 ? { id: input } : undefined)
+  )
+
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<{ id: number } | null>>()
+})
+
+test("a handler with no result resolves to null", () => {
+  const action = defineAction(z.number(), async () => {
+    await Promise.resolve()
+  })
+
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<null>>()
+})
+
 test("defineFormAction takes the schema's input and resolves to an ActionResult", () => {
   const schema = z.object({ id: z.string().transform(Number) })
   const action = defineFormAction(schema, (db, input) => {

package/src/next.test.ts

@@ -79,6 +79,23 @@ describe("defineAction", () => {
     expect(handler).toHaveBeenCalledWith(context.db, { id: 7 }, context)
   })
 
+  it("resolves to null when the handler resolves to undefined", async () => {
+    const action = createDefineAction(() => Promise.resolve({ db: {} }))(
+      schema,
+      () => Promise.resolve(undefined)
+    )
+
+    await expect(action({ id: 1 })).resolves.toBeNull()
+  })
+
+  it("keeps a falsy result other than undefined", async () => {
+    const define = createDefineAction(() => Promise.resolve({ db: {} }))
+
+    await expect(define(schema, () => 0)({ id: 1 })).resolves.toBe(0)
+    await expect(define(schema, () => false)({ id: 1 })).resolves.toBe(false)
+    await expect(define(schema, () => "")({ id: 1 })).resolves.toBe("")
+  })
+
   it("hands the handler the claims for authorship", async () => {
     const context = { claims: { sub: "user-1" }, db: {} }
     const action = createDefineAction(() => Promise.resolve(context))(

package/src/next.ts

@@ -26,6 +26,7 @@ export type {
   ActionContext,
   ActionHandler,
   ActionSchema,
+  ActionValue,
   DefineAction,
   DefineFormAction,
   FormActionSchema,