@rsc-kit/core 0.22.7 → 0.22.9

package/dist/action.d.ts

@@ -101,16 +101,26 @@ export type ActionMiddleware<Ctx, Extra extends Record<string, unknown>> = (args
     }) => Promise<MiddlewareResult<E>>;
 }) => Promise<MiddlewareResult<Extra>>;
 type Output<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never;
-export interface ActionBuilder<Ctx extends Record<string, unknown>, Input> {
+/** What a caller may pass, before the schema parses it. */
+type InputOf<S> = S extends StandardSchemaV1<infer I, unknown> ? I : unknown;
+/**
+ * A built action, as its callers see it.
+ *
+ * Typed from the schema's input when there is one, so a call with the wrong
+ * shape fails the typecheck rather than the validation - and FormData beside
+ * it, which is how a form calls the same action. Without a schema, anything.
+ */
+export type Action<Raw, Data> = unknown extends Raw ? (input?: unknown) => Promise<ActionResult<Data>> : undefined extends Raw ? (input?: Raw | FormData) => Promise<ActionResult<Data>> : (input: Raw | FormData) => Promise<ActionResult<Data>>;
+export interface ActionBuilder<Ctx extends Record<string, unknown>, Input, Raw = unknown> {
     /** Add a step, and whatever context it contributes. */
     use<Extra extends Record<string, unknown> = Record<string, never>>(middleware: (args: {
         ctx: Ctx;
         next: <E extends Record<string, unknown> = Record<string, never>>(opts?: {
             ctx?: E;
         }) => Promise<MiddlewareResult<E>>;
-    }) => Promise<MiddlewareResult<Extra>>): ActionBuilder<Ctx & Extra, Input>;
+    }) => Promise<MiddlewareResult<Extra>>): ActionBuilder<Ctx & Extra, Input, Raw>;
     /** Parse and check what the caller sent. The handler's `input` follows. */
-    input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>>;
+    input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>, InputOf<S>>;
     /**
      * The body.
      *
@@ -120,7 +130,7 @@ export interface ActionBuilder<Ctx extends Record<string, unknown>, Input> {
      * reading `result.validationErrors` after a redirect reads undefined and
      * not a TypeError inside a transition, which unmounts the root.
      */
-    handler<Data>(fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data): (input?: unknown) => Promise<ActionResult<Data>>;
+    handler<Data>(fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data): Action<Raw, Data>;
     /**
      * The body of a READ, sharing this client's middleware and schema.
      *

package/dist/action.js.map

@@ -1 +1 @@
-{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"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","sourcesContent":["// Server actions with a schema, middleware, and types that follow from both.\n//\n//     export const action = createActionClient({ onError: report })\n//\n//     export const createPost = action\n//       .use(async ({ next }) => next({ ctx: { user: await currentUser() } }))\n//       .input(z.object({ title: z.string().min(3) }))\n//       .handler(async ({ input, ctx }) => savePost(ctx.user.id, input.title))\n//\n// `input` is typed from the schema and `ctx` from every middleware that ran, so\n// the handler is checked against both without either being written down twice.\n//\n// The built action RETURNS its failures rather than throwing them, and that is\n// not a style choice. React serialises a rejected server action opaquely —\n// production strips the message and leaves a digest — so a thrown validation\n// error reaches the browser as \"an error occurred\" and the fields it named are\n// gone. A returned object crosses the boundary intact.\n//\n// Distinct from `middleware.ts` in a route directory, which decides whether a\n// page may render. This wraps one action. They are different questions: an\n// action is reachable without any page, which is why it defends itself.\n\nimport { validateWith, type StandardSchemaV1 } from './js/standardSchema.js'\nimport { decodeFormData } from './js/formEncoding.js'\nimport { markQuery, QueryValidationError, type QueryOptions } from './query.js'\nimport { isRedirectSignal } from './redirectDigest.js'\n\n/** What an action answers with. Exactly one of the four is set. */\nexport interface ActionResult<Data> {\n  /** What the handler returned. */\n  data?: Data\n  /** Field name to messages, in the shape a form already renders. */\n  validationErrors?: Record<string, string[]>\n  /** Something else went wrong, reduced to a message the browser may see. */\n  serverError?: string\n  /**\n   * Where the action sent the visitor. Set by the client, which has already\n   * started the navigation: the page is on its way there, and there is\n   * nothing for the caller to do. Never set on the server side of the call.\n   */\n  redirected?: string\n}\n\n/**\n * A middleware that neither continued nor refused.\n *\n * Never reported through `onError`: that reduces an error to a message for the\n * browser, and this one is for whoever wrote the middleware. A check that\n * forgot to call `next()` would otherwise look exactly like a check that\n * passed.\n */\nexport class ActionMisuse extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'ActionMisuse'\n  }\n}\n\n/** Refuse from inside a handler, naming the fields. */\n/**\n * Marks a refusal so it survives a bundle seam.\n *\n * A property rather than `instanceof`, for the reason this project keeps\n * running into: an app's actions are bundled separately from the engine, so\n * each gets its own copy of this module and its own copy of the class.\n * `instanceof` compares identity across that seam and is simply false — and\n * the refusal is then reported as a server error, so the form shows \"Something\n * went wrong\" instead of naming the fields. Everything works; nothing logs.\n *\n * Symbol.for, so the two copies agree on the key as well as the value.\n */\nconst VALIDATION_MARK = Symbol.for('@rsc-kit/core.action-validation')\n\n/**\n * Set on every function a client builds, so the build can tell them from a\n * bare \"use server\" export. The difference is the middleware: a bare export\n * runs with nothing checking who called it, and nothing else in the app\n * would ever say so. Symbol.for, because the build reads the mark from the\n * bundled copy of this module and the app's actions were built by another.\n */\nconst CLIENT_MARK = Symbol.for('@rsc-kit/core.action-client')\n\n/** Whether a server action was built by createActionClient, and so ran its chain. */\nexport function isClientBuilt(fn: unknown): boolean {\n  return typeof fn === 'function' && (fn as unknown as Record<symbol, unknown>)[CLIENT_MARK] === true\n}\n\nfunction markClientBuilt<F extends Function>(fn: F): F {\n  Object.defineProperty(fn, CLIENT_MARK, { value: true })\n\n  return fn\n}\n\nexport class ActionValidationError extends Error {\n  public readonly errors: Record<string, string[]>\n\n  constructor(errors: Record<string, string[]>) {\n    super('Validation failed')\n    this.name = 'ActionValidationError'\n    this.errors = errors\n    ;(this as unknown as Record<symbol, boolean>)[VALIDATION_MARK] = true\n  }\n}\n\n/** Whether this is a refusal, whichever copy of the class built it. */\nexport function isActionValidationError(error: unknown): error is ActionValidationError {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    (error as Record<symbol, unknown>)[VALIDATION_MARK] === true\n  )\n}\n\n/**\n * The field errors a handler may report, keyed by its own input's fields.\n *\n * `''` is the whole submission — for a refusal that is about no field in\n * particular, which is where the form already looks for one.\n */\nexport type FieldErrorsFor<Input> = Partial<\n  Record<(Input extends object ? keyof Input & string : string) | '', string | string[]>\n>\n\n/**\n * What a handler is given.\n *\n * `fieldErrors` is here as well as exported on its own, and the one here is\n * the one to use: it is typed to this handler's input, so a field the schema\n * does not have is a type error rather than an error the form never shows.\n * The bare export takes any string, for the rare check that runs outside a\n * handler.\n */\nexport interface HandlerArgs<Input, Ctx> {\n  input: Input\n  ctx: Ctx\n  /**\n   * Fail with errors on this input's fields. Throws; nothing after it runs.\n   *\n   * Write `return fieldErrors(...)`. It throws either way, but TypeScript does\n   * not treat a never-return as terminating when the callee is a destructured\n   * binding — only a declaration or an explicitly annotated variable — so\n   * without the return, a value checked on the line above is still possibly\n   * undefined on the line below. The return is what lets the type narrow.\n   */\n  fieldErrors: (errors: FieldErrorsFor<Input>) => never\n}\n\n/**\n * Fail with field errors the form can show.\n *\n * For what a schema cannot know — a name already taken, a balance too low.\n * Throws, so the handler stops where it is; the action turns it into a\n * returned result on the way out.\n *\n * Untyped by field, because it has no handler to take the input from. Inside\n * one, use the `fieldErrors` the handler is given instead.\n */\nexport function fieldErrors(errors: Record<string, string[] | string>): never {\n  const normalised: Record<string, string[]> = {}\n\n  for (const [field, message] of Object.entries(errors)) {\n    normalised[field] = Array.isArray(message) ? message : [message]\n  }\n\n  throw new ActionValidationError(normalised)\n}\n\n/**\n * What `next()` hands back, carrying what the step added.\n *\n * The context a middleware contributes cannot be inferred from the arguments\n * it passes to `next` — TypeScript infers from a function's return, not from a\n * call inside it. So `next` returns this, the middleware returns it, and the\n * addition is read off the middleware's own return type.\n */\nexport interface MiddlewareResult<Extra> {\n  readonly ctx: Extra\n  readonly value: unknown\n}\n\n/**\n * A step that runs before the handler.\n *\n * It calls `next` to continue, optionally adding to the context, and what it\n * adds shows up in the handler's types. Returning without calling `next` — or\n * throwing — stops the action, which is how a check refuses.\n */\nexport type ActionMiddleware<Ctx, Extra extends Record<string, unknown>> = (args: {\n  ctx: Ctx\n  next: <E extends Record<string, unknown> = Record<string, never>>(\n    opts?: { ctx?: E },\n  ) => Promise<MiddlewareResult<E>>\n}) => Promise<MiddlewareResult<Extra>>\n\ntype Output<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never\n\nexport interface ActionBuilder<Ctx extends Record<string, unknown>, Input> {\n  /** Add a step, and whatever context it contributes. */\n  use<Extra extends Record<string, unknown> = Record<string, never>>(\n    middleware: (args: {\n      ctx: Ctx\n      next: <E extends Record<string, unknown> = Record<string, never>>(\n        opts?: { ctx?: E },\n      ) => Promise<MiddlewareResult<E>>\n    }) => Promise<MiddlewareResult<Extra>>,\n  ): ActionBuilder<Ctx & Extra, Input>\n  /** Parse and check what the caller sent. The handler's `input` follows. */\n  input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>>\n  /**\n   * The body.\n   *\n   * What the caller gets is always the result object: `data`, or a\n   * refusal, or - when the action redirected - `redirected`, set by the\n   * client once the navigation is under way. Always an object, so a caller\n   * reading `result.validationErrors` after a redirect reads undefined and\n   * not a TypeError inside a transition, which unmounts the root.\n   */\n  handler<Data>(\n    fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data,\n  ): (input?: unknown) => Promise<ActionResult<Data>>\n  /**\n   * The body of a READ, sharing this client's middleware and schema.\n   *\n   *     export const getPosts = client.input(filter).query(async ({ input, ctx }) =>\n   *       db.posts(ctx.user.id, input))\n   *\n   * The same builder as `handler`, and deliberately so: an app configures its\n   * auth check and its error reporting once, and both a mutation and a read go\n   * through them.\n   *\n   * It fails differently, though, and that is not an oversight. An action\n   * RETURNS its failures because React serialises a rejection opaquely. A query\n   * is handed to a cache library as a fetcher, and every one of them reports\n   * failure by rejection — so this returns the data directly and throws, and\n   * the endpoint carries the message across for it.\n   */\n  query<Data>(\n    fn: (args: { input: Input; ctx: Ctx }) => Promise<Data> | Data,\n    options?: QueryOptions,\n  ): (input?: unknown) => Promise<Data>\n}\n\nexport interface ActionClientOptions {\n  /**\n   * What the browser is told when something unexpected throws.\n   *\n   * Everything reaching here is a bug or an outage, and its message may say\n   * more than a stranger should see — a query, a path, a host. Returning a\n   * fixed string is the safe default; return the message only for errors you\n   * raised deliberately.\n   */\n  onError?: (error: unknown) => string\n}\n\nconst GENERIC = 'Something went wrong.'\n\n/**\n * FormData in, a plain object out — what a schema expects to be handed.\n *\n * The form's own decoder, so the object validated here is the object the\n * browser validated. This had a flat decoder of its own: `items[0].name`\n * stayed a key spelled exactly that, `<Form>` had already parsed it into an\n * array, and a nested form passed in the browser and failed on the server\n * with the fields it named gone.\n */\nconst fromFormData = (body: FormData, schema: unknown): Record<string, unknown> => decodeFormData(body, schema)\n\nexport function createActionClient(\n  options: ActionClientOptions = {},\n): ActionBuilder<Record<never, never>, undefined> {\n  const report = options.onError ?? (() => GENERIC)\n\n  function build<Ctx extends Record<string, unknown>, Input>(\n    middlewares: ActionMiddleware<never, never>[],\n    schema: StandardSchemaV1 | null,\n  ): ActionBuilder<Ctx, Input> {\n      /**\n       * Validate, run the chain, call the body.\n       *\n       * Shared by both terminals, which is the point of putting a read on this\n       * builder at all: one set of middleware, one schema, one place the auth\n       * check lives. Refusals leave by throwing, and each terminal decides what\n       * that should look like from the outside.\n       */\n    const pipeline = async (\n      raw: unknown,\n      fn: (args: HandlerArgs<never, never>) => unknown,\n    ): Promise<unknown> => {\n      const value = raw instanceof FormData ? fromFormData(raw, schema) : raw\n\n      if (schema) {\n        const invalid = await validateWith(schema, value)\n\n        if (invalid) throw new ActionValidationError(invalid)\n      }\n\n      const parsed = schema\n        ? ((await schema['~standard'].validate(value)).value as Input)\n        : (value as Input)\n\n      // Composed inside-out so the first `use` is the outermost — it sees the\n      // others run, which is what makes timing and cleanup possible rather\n      // than only checks.\n      let ctx = {} as Ctx\n      let index = 0\n\n      const run = async (): Promise<unknown> => {\n        const middleware = middlewares[index++]\n\n        if (!middleware) {\n          return await fn({\n            input: parsed as never,\n            ctx: ctx as never,\n            // The same function as the export; the type on the way in is what\n            // is different, and the type is the handler's input.\n            fieldErrors: fieldErrors as never,\n          })\n        }\n\n        let continued = false\n\n        const result = await (middleware as unknown as ActionMiddleware<Ctx, Record<string, unknown>>)({\n          ctx,\n          next: (async (opts?: { ctx?: Record<string, unknown> }) => {\n            continued = true\n            ctx = { ...ctx, ...(opts?.ctx ?? {}) } as Ctx\n\n            return { ctx, value: await run() }\n          }) as never,\n        })\n\n        // Silence is not refusal. A middleware that neither called next() nor\n        // threw has done nothing, and guessing which it meant turns a\n        // forgotten `return` into a check that quietly passes.\n        if (!continued) {\n          throw new ActionMisuse(\n            'A middleware returned without calling next(). Call it to continue, or throw to refuse.',\n          )\n        }\n\n        return (result as { value?: unknown })?.value\n      }\n\n      return await run()\n    }\n\n    return {\n      use(middleware) {\n        return build([...middlewares, middleware as never], schema) as never\n      },\n      input(next) {\n        return build(middlewares, next) as never\n      },\n      handler(fn) {\n        return markClientBuilt(async (raw?: unknown) => {\n          try {\n            return { data: (await pipeline(raw, fn)) as Awaited<ReturnType<typeof fn>> }\n          } catch (error) {\n            // Past onError deliberately — see ActionMisuse.\n            if (error instanceof ActionMisuse) throw error\n\n            // A redirect is an instruction, not a failure: it has to reach\n            // the host, which answers the action with the destination. Caught\n            // here it became { serverError: 'Something went wrong.' } - a\n            // login that succeeded and then showed an error.\n            if (isRedirectSignal(error)) throw error\n\n            if (isActionValidationError(error)) {\n              return { validationErrors: error.errors }\n            }\n\n            return { serverError: report(error) }\n          }\n        })\n      },\n      query(fn, options) {\n        const read = async (raw?: unknown) => {\n          try {\n            return await pipeline(raw, fn)\n          } catch (error) {\n            if (error instanceof ActionMisuse) throw error\n            if (isRedirectSignal(error)) throw error\n\n            // Thrown, not returned. A cache library reports failure by\n            // rejection, so a query that answered with an error-shaped object\n            // would look like a successful read of something odd.\n            if (isActionValidationError(error)) {\n              throw new QueryValidationError(error.errors)\n            }\n\n            throw new Error(report(error))\n          }\n        }\n\n        return markClientBuilt(markQuery(read, options)) as (input?: unknown) => Promise<never>\n      },\n    }\n  }\n\n  return build([], null)\n}\n"]}
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"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","sourcesContent":["// Server actions with a schema, middleware, and types that follow from both.\n//\n//     export const action = createActionClient({ onError: report })\n//\n//     export const createPost = action\n//       .use(async ({ next }) => next({ ctx: { user: await currentUser() } }))\n//       .input(z.object({ title: z.string().min(3) }))\n//       .handler(async ({ input, ctx }) => savePost(ctx.user.id, input.title))\n//\n// `input` is typed from the schema and `ctx` from every middleware that ran, so\n// the handler is checked against both without either being written down twice.\n//\n// The built action RETURNS its failures rather than throwing them, and that is\n// not a style choice. React serialises a rejected server action opaquely —\n// production strips the message and leaves a digest — so a thrown validation\n// error reaches the browser as \"an error occurred\" and the fields it named are\n// gone. A returned object crosses the boundary intact.\n//\n// Distinct from `middleware.ts` in a route directory, which decides whether a\n// page may render. This wraps one action. They are different questions: an\n// action is reachable without any page, which is why it defends itself.\n\nimport { validateWith, type StandardSchemaV1 } from './js/standardSchema.js'\nimport { decodeFormData } from './js/formEncoding.js'\nimport { markQuery, QueryValidationError, type QueryOptions } from './query.js'\nimport { isRedirectSignal } from './redirectDigest.js'\n\n/** What an action answers with. Exactly one of the four is set. */\nexport interface ActionResult<Data> {\n  /** What the handler returned. */\n  data?: Data\n  /** Field name to messages, in the shape a form already renders. */\n  validationErrors?: Record<string, string[]>\n  /** Something else went wrong, reduced to a message the browser may see. */\n  serverError?: string\n  /**\n   * Where the action sent the visitor. Set by the client, which has already\n   * started the navigation: the page is on its way there, and there is\n   * nothing for the caller to do. Never set on the server side of the call.\n   */\n  redirected?: string\n}\n\n/**\n * A middleware that neither continued nor refused.\n *\n * Never reported through `onError`: that reduces an error to a message for the\n * browser, and this one is for whoever wrote the middleware. A check that\n * forgot to call `next()` would otherwise look exactly like a check that\n * passed.\n */\nexport class ActionMisuse extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'ActionMisuse'\n  }\n}\n\n/** Refuse from inside a handler, naming the fields. */\n/**\n * Marks a refusal so it survives a bundle seam.\n *\n * A property rather than `instanceof`, for the reason this project keeps\n * running into: an app's actions are bundled separately from the engine, so\n * each gets its own copy of this module and its own copy of the class.\n * `instanceof` compares identity across that seam and is simply false — and\n * the refusal is then reported as a server error, so the form shows \"Something\n * went wrong\" instead of naming the fields. Everything works; nothing logs.\n *\n * Symbol.for, so the two copies agree on the key as well as the value.\n */\nconst VALIDATION_MARK = Symbol.for('@rsc-kit/core.action-validation')\n\n/**\n * Set on every function a client builds, so the build can tell them from a\n * bare \"use server\" export. The difference is the middleware: a bare export\n * runs with nothing checking who called it, and nothing else in the app\n * would ever say so. Symbol.for, because the build reads the mark from the\n * bundled copy of this module and the app's actions were built by another.\n */\nconst CLIENT_MARK = Symbol.for('@rsc-kit/core.action-client')\n\n/** Whether a server action was built by createActionClient, and so ran its chain. */\nexport function isClientBuilt(fn: unknown): boolean {\n  return typeof fn === 'function' && (fn as unknown as Record<symbol, unknown>)[CLIENT_MARK] === true\n}\n\nfunction markClientBuilt<F extends Function>(fn: F): F {\n  Object.defineProperty(fn, CLIENT_MARK, { value: true })\n\n  return fn\n}\n\nexport class ActionValidationError extends Error {\n  public readonly errors: Record<string, string[]>\n\n  constructor(errors: Record<string, string[]>) {\n    super('Validation failed')\n    this.name = 'ActionValidationError'\n    this.errors = errors\n    ;(this as unknown as Record<symbol, boolean>)[VALIDATION_MARK] = true\n  }\n}\n\n/** Whether this is a refusal, whichever copy of the class built it. */\nexport function isActionValidationError(error: unknown): error is ActionValidationError {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    (error as Record<symbol, unknown>)[VALIDATION_MARK] === true\n  )\n}\n\n/**\n * The field errors a handler may report, keyed by its own input's fields.\n *\n * `''` is the whole submission — for a refusal that is about no field in\n * particular, which is where the form already looks for one.\n */\nexport type FieldErrorsFor<Input> = Partial<\n  Record<(Input extends object ? keyof Input & string : string) | '', string | string[]>\n>\n\n/**\n * What a handler is given.\n *\n * `fieldErrors` is here as well as exported on its own, and the one here is\n * the one to use: it is typed to this handler's input, so a field the schema\n * does not have is a type error rather than an error the form never shows.\n * The bare export takes any string, for the rare check that runs outside a\n * handler.\n */\nexport interface HandlerArgs<Input, Ctx> {\n  input: Input\n  ctx: Ctx\n  /**\n   * Fail with errors on this input's fields. Throws; nothing after it runs.\n   *\n   * Write `return fieldErrors(...)`. It throws either way, but TypeScript does\n   * not treat a never-return as terminating when the callee is a destructured\n   * binding — only a declaration or an explicitly annotated variable — so\n   * without the return, a value checked on the line above is still possibly\n   * undefined on the line below. The return is what lets the type narrow.\n   */\n  fieldErrors: (errors: FieldErrorsFor<Input>) => never\n}\n\n/**\n * Fail with field errors the form can show.\n *\n * For what a schema cannot know — a name already taken, a balance too low.\n * Throws, so the handler stops where it is; the action turns it into a\n * returned result on the way out.\n *\n * Untyped by field, because it has no handler to take the input from. Inside\n * one, use the `fieldErrors` the handler is given instead.\n */\nexport function fieldErrors(errors: Record<string, string[] | string>): never {\n  const normalised: Record<string, string[]> = {}\n\n  for (const [field, message] of Object.entries(errors)) {\n    normalised[field] = Array.isArray(message) ? message : [message]\n  }\n\n  throw new ActionValidationError(normalised)\n}\n\n/**\n * What `next()` hands back, carrying what the step added.\n *\n * The context a middleware contributes cannot be inferred from the arguments\n * it passes to `next` — TypeScript infers from a function's return, not from a\n * call inside it. So `next` returns this, the middleware returns it, and the\n * addition is read off the middleware's own return type.\n */\nexport interface MiddlewareResult<Extra> {\n  readonly ctx: Extra\n  readonly value: unknown\n}\n\n/**\n * A step that runs before the handler.\n *\n * It calls `next` to continue, optionally adding to the context, and what it\n * adds shows up in the handler's types. Returning without calling `next` — or\n * throwing — stops the action, which is how a check refuses.\n */\nexport type ActionMiddleware<Ctx, Extra extends Record<string, unknown>> = (args: {\n  ctx: Ctx\n  next: <E extends Record<string, unknown> = Record<string, never>>(\n    opts?: { ctx?: E },\n  ) => Promise<MiddlewareResult<E>>\n}) => Promise<MiddlewareResult<Extra>>\n\ntype Output<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never\n\n/** What a caller may pass, before the schema parses it. */\ntype InputOf<S> = S extends StandardSchemaV1<infer I, unknown> ? I : unknown\n\n/**\n * A built action, as its callers see it.\n *\n * Typed from the schema's input when there is one, so a call with the wrong\n * shape fails the typecheck rather than the validation - and FormData beside\n * it, which is how a form calls the same action. Without a schema, anything.\n */\nexport type Action<Raw, Data> = unknown extends Raw\n  ? (input?: unknown) => Promise<ActionResult<Data>>\n  : undefined extends Raw\n    ? (input?: Raw | FormData) => Promise<ActionResult<Data>>\n    : (input: Raw | FormData) => Promise<ActionResult<Data>>\n\nexport interface ActionBuilder<Ctx extends Record<string, unknown>, Input, Raw = unknown> {\n  /** Add a step, and whatever context it contributes. */\n  use<Extra extends Record<string, unknown> = Record<string, never>>(\n    middleware: (args: {\n      ctx: Ctx\n      next: <E extends Record<string, unknown> = Record<string, never>>(\n        opts?: { ctx?: E },\n      ) => Promise<MiddlewareResult<E>>\n    }) => Promise<MiddlewareResult<Extra>>,\n  ): ActionBuilder<Ctx & Extra, Input, Raw>\n  /** Parse and check what the caller sent. The handler's `input` follows. */\n  input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>, InputOf<S>>\n  /**\n   * The body.\n   *\n   * What the caller gets is always the result object: `data`, or a\n   * refusal, or - when the action redirected - `redirected`, set by the\n   * client once the navigation is under way. Always an object, so a caller\n   * reading `result.validationErrors` after a redirect reads undefined and\n   * not a TypeError inside a transition, which unmounts the root.\n   */\n  handler<Data>(\n    fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data,\n  ): Action<Raw, Data>\n  /**\n   * The body of a READ, sharing this client's middleware and schema.\n   *\n   *     export const getPosts = client.input(filter).query(async ({ input, ctx }) =>\n   *       db.posts(ctx.user.id, input))\n   *\n   * The same builder as `handler`, and deliberately so: an app configures its\n   * auth check and its error reporting once, and both a mutation and a read go\n   * through them.\n   *\n   * It fails differently, though, and that is not an oversight. An action\n   * RETURNS its failures because React serialises a rejection opaquely. A query\n   * is handed to a cache library as a fetcher, and every one of them reports\n   * failure by rejection — so this returns the data directly and throws, and\n   * the endpoint carries the message across for it.\n   */\n  query<Data>(\n    fn: (args: { input: Input; ctx: Ctx }) => Promise<Data> | Data,\n    options?: QueryOptions,\n  ): (input?: unknown) => Promise<Data>\n}\n\nexport interface ActionClientOptions {\n  /**\n   * What the browser is told when something unexpected throws.\n   *\n   * Everything reaching here is a bug or an outage, and its message may say\n   * more than a stranger should see — a query, a path, a host. Returning a\n   * fixed string is the safe default; return the message only for errors you\n   * raised deliberately.\n   */\n  onError?: (error: unknown) => string\n}\n\nconst GENERIC = 'Something went wrong.'\n\n/**\n * FormData in, a plain object out — what a schema expects to be handed.\n *\n * The form's own decoder, so the object validated here is the object the\n * browser validated. This had a flat decoder of its own: `items[0].name`\n * stayed a key spelled exactly that, `<Form>` had already parsed it into an\n * array, and a nested form passed in the browser and failed on the server\n * with the fields it named gone.\n */\nconst fromFormData = (body: FormData, schema: unknown): Record<string, unknown> => decodeFormData(body, schema)\n\nexport function createActionClient(\n  options: ActionClientOptions = {},\n): ActionBuilder<Record<never, never>, undefined> {\n  const report = options.onError ?? (() => GENERIC)\n\n  function build<Ctx extends Record<string, unknown>, Input>(\n    middlewares: ActionMiddleware<never, never>[],\n    schema: StandardSchemaV1 | null,\n  ): ActionBuilder<Ctx, Input> {\n      /**\n       * Validate, run the chain, call the body.\n       *\n       * Shared by both terminals, which is the point of putting a read on this\n       * builder at all: one set of middleware, one schema, one place the auth\n       * check lives. Refusals leave by throwing, and each terminal decides what\n       * that should look like from the outside.\n       */\n    const pipeline = async (\n      raw: unknown,\n      fn: (args: HandlerArgs<never, never>) => unknown,\n    ): Promise<unknown> => {\n      const value = raw instanceof FormData ? fromFormData(raw, schema) : raw\n\n      if (schema) {\n        const invalid = await validateWith(schema, value)\n\n        if (invalid) throw new ActionValidationError(invalid)\n      }\n\n      const parsed = schema\n        ? ((await schema['~standard'].validate(value)).value as Input)\n        : (value as Input)\n\n      // Composed inside-out so the first `use` is the outermost — it sees the\n      // others run, which is what makes timing and cleanup possible rather\n      // than only checks.\n      let ctx = {} as Ctx\n      let index = 0\n\n      const run = async (): Promise<unknown> => {\n        const middleware = middlewares[index++]\n\n        if (!middleware) {\n          return await fn({\n            input: parsed as never,\n            ctx: ctx as never,\n            // The same function as the export; the type on the way in is what\n            // is different, and the type is the handler's input.\n            fieldErrors: fieldErrors as never,\n          })\n        }\n\n        let continued = false\n\n        const result = await (middleware as unknown as ActionMiddleware<Ctx, Record<string, unknown>>)({\n          ctx,\n          next: (async (opts?: { ctx?: Record<string, unknown> }) => {\n            continued = true\n            ctx = { ...ctx, ...(opts?.ctx ?? {}) } as Ctx\n\n            return { ctx, value: await run() }\n          }) as never,\n        })\n\n        // Silence is not refusal. A middleware that neither called next() nor\n        // threw has done nothing, and guessing which it meant turns a\n        // forgotten `return` into a check that quietly passes.\n        if (!continued) {\n          throw new ActionMisuse(\n            'A middleware returned without calling next(). Call it to continue, or throw to refuse.',\n          )\n        }\n\n        return (result as { value?: unknown })?.value\n      }\n\n      return await run()\n    }\n\n    return {\n      use(middleware) {\n        return build([...middlewares, middleware as never], schema) as never\n      },\n      input(next) {\n        return build(middlewares, next) as never\n      },\n      handler(fn) {\n        return markClientBuilt(async (raw?: unknown) => {\n          try {\n            return { data: (await pipeline(raw, fn)) as Awaited<ReturnType<typeof fn>> }\n          } catch (error) {\n            // Past onError deliberately — see ActionMisuse.\n            if (error instanceof ActionMisuse) throw error\n\n            // A redirect is an instruction, not a failure: it has to reach\n            // the host, which answers the action with the destination. Caught\n            // here it became { serverError: 'Something went wrong.' } - a\n            // login that succeeded and then showed an error.\n            if (isRedirectSignal(error)) throw error\n\n            if (isActionValidationError(error)) {\n              return { validationErrors: error.errors }\n            }\n\n            return { serverError: report(error) }\n          }\n        })\n      },\n      query(fn, options) {\n        const read = async (raw?: unknown) => {\n          try {\n            return await pipeline(raw, fn)\n          } catch (error) {\n            if (error instanceof ActionMisuse) throw error\n            if (isRedirectSignal(error)) throw error\n\n            // Thrown, not returned. A cache library reports failure by\n            // rejection, so a query that answered with an error-shaped object\n            // would look like a successful read of something odd.\n            if (isActionValidationError(error)) {\n              throw new QueryValidationError(error.errors)\n            }\n\n            throw new Error(report(error))\n          }\n        }\n\n        return markClientBuilt(markQuery(read, options)) as (input?: unknown) => Promise<never>\n      },\n    }\n  }\n\n  return build([], null)\n}\n"]}

package/dist/host.d.ts

@@ -1,7 +1,3 @@
-/**
- * @internal For a host adapter that embeds the engine. An app imports this
- * from `@rsc-kit/core/revalidate`.
- */
 export { revalidate } from "./revalidate.js";
 import { type CriticalAssets } from "./earlyHints.js";
 /**

package/dist/host.js

@@ -22,6 +22,12 @@ import { withRevalidation } from "./revalidate.js";
  * @internal For a host adapter that embeds the engine. An app imports this
  * from `@rsc-kit/core/revalidate`.
  */
+/**
+ * A guard's notFound(), from refuseUnlessAllowed. Not a Response: a page's
+ * answer is null, which the caller in front serves as not-found.tsx, and the
+ * internal endpoints answer a plain 404.
+ */
+const RENDER_NOT_FOUND = Symbol("render-not-found");
 export { revalidate } from "./revalidate.js";
 import { currentNotFound, withRedirect } from "./redirect.js";
 import { compressed } from "./compress.js";
@@ -761,6 +767,10 @@ export function createRscHandler(options) {
             // questions. The build answers the first; this answers the second, and
             // only then is the frozen page handed over.
             const refusal = await refuseUnlessAllowed(request, match);
+            // Null, as a render that calls notFound() answers: the caller in front
+            // serves not-found.tsx with a 404, the same for a guard as for a page.
+            if (refusal === RENDER_NOT_FOUND)
+                return null;
             if (refusal)
                 return refusal;
             const frozen = await servePrerendered(request, url, match, options.prerendered);
@@ -1050,6 +1060,8 @@ export function createRscHandler(options) {
         // The same refusal the document would get, before a byte of the holes is
         // rendered. Nothing below runs for a caller this turns away.
         const refusal = await refuseUnlessAllowed(request, route);
+        if (refusal === RENDER_NOT_FOUND)
+            return new Response("Not found", { status: 404 });
         if (refusal)
             return refusal;
         if (!engine.handleRscResume) {
@@ -1329,6 +1341,12 @@ export function createRscHandler(options) {
                 const refused = taken();
                 if (refused)
                     return redirectResponse(refused, asPayload);
+                // notFound() from a guard: this caller is to be told there is no such
+                // page, as a render that called it would tell them. It escaped as an
+                // error here, while the same guard answered 404 on a page rendered
+                // per request - the check held until the build stored the page.
+                if (currentNotFound())
+                    return RENDER_NOT_FOUND;
                 // A visitor who may not see this page has not caused a server
                 // error. Answering 500 makes a guarded route indistinguishable from
                 // a broken one, in the logs and to the person looking at it.
@@ -1399,6 +1417,8 @@ export function createRscHandler(options) {
         if (!intercepted)
             return new Response("No such page", { status: 404 });
         const refusal = await refuseUnlessAllowed(request, intercepted);
+        if (refusal === RENDER_NOT_FOUND)
+            return new Response("Not found", { status: 404 });
         if (refusal)
             return refusal;
         const from = refererPath(request.headers.get(HEADER.referer), url.origin, siteHosts);
@@ -1481,6 +1501,9 @@ export function createRscHandler(options) {
                 const redirected = taken();
                 if (redirected)
                     return apiRedirect(request, redirected);
+                // notFound() from a guard: no such endpoint, for this caller.
+                if (currentNotFound())
+                    return new Response("Not found", { status: 404 });
                 // A visitor who may not use this endpoint has not caused a server
                 // error, and answering 500 makes a guarded route indistinguishable
                 // from a broken one. Null means the middleware threw something that is