@zeno-lib/db 0.5.0 → 0.6.0

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.6.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",

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/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,