@cfast/actions 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Schmidt
+
+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/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { C as ClientDescriptor, S as Serializable } from './types-Dolh-eut.js';
+import { C as ClientDescriptor, S as Serializable } from './types-ogCcbQm3.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Form } from 'react-router';
 import { ComponentProps, ReactNode } from 'react';

package/dist/index.d.ts

@@ -1,8 +1,156 @@
 import { Grant, PermissionDescriptor } from '@cfast/permissions';
-import { A as ActionPermissionStatus, a as ActionsConfig, O as OperationsFn, b as ActionDefinition, c as ComposedActions } from './types-Dolh-eut.js';
-export { d as ActionContext, e as ActionPermissionsMap, C as ClientDescriptor, R as RequestArgs, S as Serializable } from './types-Dolh-eut.js';
+import { A as ActionPermissionStatus, a as ActionServices, b as ActionsConfig, O as OperationsFn, c as ActionDefinition, d as ComposedActions } from './types-ogCcbQm3.js';
+export { e as ActionContext, f as ActionPermissionsMap, C as ClientDescriptor, R as RequestArgs, S as Serializable } from './types-ogCcbQm3.js';
 import '@cfast/db';
 
+/**
+ * Tiny schema-based input parser for `createAction`.
+ *
+ * The motivation (#159) is that `Number(formData.get("position"))` silently
+ * returns `NaN` for missing or non-numeric inputs and quietly persists garbage.
+ * This module exposes a minimal Zod-like field DSL whose `.parse()` method
+ * coerces and validates raw form/JSON input into a typed object, throwing an
+ * {@link InvalidInputError} (with field-keyed messages) on failure instead of
+ * letting the bad value reach the database.
+ *
+ * The DSL intentionally only covers the field types `@cfast/forms` already
+ * derives from a Drizzle schema (string / number / integer / boolean) plus
+ * optional/nullable wrappers. Anything more exotic should fall back to a real
+ * validator like Zod via the `custom()` escape hatch.
+ */
+/**
+ * Thrown by {@link InputSchema.parse} when the raw input fails validation.
+ *
+ * `errors` is keyed by field name and contains the human-readable reason for
+ * each failure. Action handlers can re-throw the error directly from a
+ * `createAction` body to surface form-level errors to the client.
+ */
+declare class InvalidInputError extends Error {
+    /** Field-keyed map of validation errors. */
+    readonly errors: Record<string, string>;
+    constructor(errors: Record<string, string>);
+}
+/**
+ * A single field validator. Implementations receive the raw value (string from
+ * a `FormData`, anything from a JSON body, or `undefined` if the field is
+ * missing) and return either a parsed value or a validation error message.
+ */
+type InputField<T> = {
+    /**
+     * Parses a single raw input value. Returns `{ ok: true, value }` on success
+     * or `{ ok: false, error }` with a human-readable explanation on failure.
+     */
+    parse(raw: unknown): {
+        ok: true;
+        value: T;
+    } | {
+        ok: false;
+        error: string;
+    };
+};
+/**
+ * String field. Coerces `FormDataEntryValue` (which is `File | string`) to a
+ * string. Rejects missing values unless wrapped in {@link optional}.
+ */
+declare function stringField(): InputField<string>;
+/**
+ * Number field. The core fix for #159: parses a numeric value and rejects
+ * `NaN`, `Infinity`, and unparseable strings outright. Used by every action
+ * handler that previously did `Number(formData.get("x"))`.
+ */
+declare function numberField(): InputField<number>;
+/**
+ * Integer field. Same semantics as {@link numberField} but additionally
+ * rejects fractional values. Maps to Drizzle's `integer()` columns.
+ */
+declare function integerField(): InputField<number>;
+/**
+ * Boolean field. Accepts the form-typical strings (`"true"`, `"false"`,
+ * `"on"`, `"off"`, `"1"`, `"0"`) plus native booleans from JSON bodies.
+ * Rejects everything else so a typo doesn't silently coerce to `false`.
+ */
+declare function booleanField(): InputField<boolean>;
+/**
+ * Wraps a field so missing values produce `undefined` instead of an error.
+ * Use for genuinely optional inputs.
+ */
+declare function optionalField<T>(inner: InputField<T>): InputField<T | undefined>;
+/**
+ * Wraps a field so missing values produce `null` instead of an error.
+ * Use for nullable database columns.
+ */
+declare function nullableField<T>(inner: InputField<T>): InputField<T | null>;
+/**
+ * Custom field — escape hatch for cases the built-in fields don't cover
+ * (enums, regex matches, etc.). The callback receives the raw value and
+ * returns either the parsed result or throws to signal failure.
+ *
+ * @example
+ * ```ts
+ * const slugField = z.custom<string>((raw) => {
+ *   if (typeof raw !== "string") throw new Error("must be a string");
+ *   if (!/^[a-z0-9-]+$/.test(raw)) throw new Error("must be slug-safe");
+ *   return raw;
+ * });
+ * ```
+ */
+declare function customField<T>(parser: (raw: unknown) => T): InputField<T>;
+/**
+ * Minimal Zod-like field DSL exposed from `@cfast/actions`. Pair with
+ * {@link defineInput} to build a typed parser for an action's input.
+ *
+ * Names match Zod (`z.string`, `z.number`, ...) so callers familiar with
+ * Zod can read the schema at a glance, but this is intentionally a
+ * tiny standalone implementation so `@cfast/actions` doesn't pull in
+ * Zod's bundle weight on the worker.
+ */
+declare const z: {
+    string: typeof stringField;
+    number: typeof numberField;
+    integer: typeof integerField;
+    boolean: typeof booleanField;
+    optional: typeof optionalField;
+    nullable: typeof nullableField;
+    custom: typeof customField;
+};
+/** A schema is a record of field names to validators. */
+type InputSchema<T> = {
+    [K in keyof T]: InputField<T[K]>;
+};
+/**
+ * Result type produced by an {@link InputParser} — the typed object the
+ * caller's action handler receives.
+ */
+type InferInput<S> = S extends InputSchema<infer T> ? T : never;
+/**
+ * A function that parses a raw input record into a typed object, throwing
+ * {@link InvalidInputError} on failure. Returned by {@link defineInput}.
+ */
+type InputParser<T> = (raw: Record<string, unknown>) => T;
+/**
+ * Builds a typed parser from a {@link InputSchema}. The returned function
+ * walks every field, collects errors, and either returns the typed object
+ * or throws {@link InvalidInputError} with all field errors at once.
+ *
+ * @example
+ * ```ts
+ * import { createAction, defineInput, z } from "@cfast/actions";
+ *
+ * const moveCard = createAction({
+ *   input: defineInput({
+ *     cardId: z.string(),
+ *     position: z.integer(),     // rejects NaN, fractional, missing
+ *     pinned: z.optional(z.boolean()),
+ *   }),
+ *   handler: (db, input, ctx) =>
+ *     db.update(cards).set({ position: input.position }).where(eq(cards.id, input.cardId)),
+ * });
+ * ```
+ */
+declare function defineInput<S extends InputSchema<unknown>>(schema: S): InputParser<{
+    [K in keyof S]: S[K] extends InputField<infer V> ? V : never;
+}>;
+
 /**
  * Checks a user's {@link Grant | grants} against a set of permission descriptors
  * and returns an {@link ActionPermissionStatus}.
@@ -34,11 +182,20 @@ declare function checkPermissionStatus(grants: Grant[], descriptors: PermissionD
  * same `getContext` callback. This ensures every action in the application resolves
  * its database, user, and grants consistently.
  *
+ * Services registered via the optional `services` config are injected into
+ * every action's context as `ctx.services`, so handlers can access shared
+ * dependencies (HTTP clients, mailers, third-party APIs) without importing
+ * module-level singletons. Services are always defined on `ctx.services`
+ * — the factory fills in `{}` when no services are configured so handlers
+ * can destructure safely.
+ *
  * @typeParam TUser - The shape of the authenticated user object.
- * @param config - The {@link ActionsConfig} providing the `getContext` callback.
+ * @typeParam TServices - The shape of the registered services map.
+ * @param config - The {@link ActionsConfig} providing the `getContext` callback
+ *   and optional `services` bag.
  * @returns An object with `createAction` and `composeActions` functions.
  *
- * @example
+ * @example Basic usage
  * ```ts
  * import { createActions } from "@cfast/actions";
  *
@@ -50,10 +207,125 @@ declare function checkPermissionStatus(grants: Grant[], descriptors: PermissionD
  *   },
  * });
  * ```
+ *
+ * @example With service injection
+ * ```ts
+ * type Services = { nutritionApi: NutritionApi };
+ *
+ * export const { createAction } = createActions<AppUser, Services>({
+ *   getContext: async ({ request }) => { ... },
+ *   services: { nutritionApi: createNutritionApi(env.NUTRITION_API_KEY) },
+ * });
+ *
+ * const lookupFood = createAction((db, input, ctx) => ({
+ *   permissions: [],
+ *   run: async () => ctx.services.nutritionApi.lookup(input.name),
+ * }));
+ * ```
  */
-declare function createActions<TUser = any>(config: ActionsConfig<TUser>): {
-    createAction: <TInput, TResult>(operationsFn: OperationsFn<TInput, TResult, TUser>) => ActionDefinition<TInput, TResult, TUser>;
+declare function createActions<TUser = any, TServices extends ActionServices = ActionServices>(config: ActionsConfig<TUser, TServices>): {
+    createAction: <TInput, TResult>(config: OperationsFn<TInput, TResult, TUser> | {
+        /**
+         * Optional typed input parser, e.g. produced by `defineInput({ ... })`.
+         *
+         * When set, the parser runs over the request's raw input before the
+         * handler is invoked. Validation failures throw {@link InvalidInputError}
+         * with field-keyed messages -- the call this fix exists for is
+         * `Number(formData.get("position"))` silently producing NaN, which
+         * `z.number()` / `z.integer()` rejects upfront.
+         */
+        input?: InputParser<TInput>;
+        /** The operation builder. Same shape as the legacy positional form. */
+        handler: OperationsFn<TInput, TResult, TUser>;
+    }) => ActionDefinition<TInput, TResult, TUser>;
     composeActions: <TActions extends Record<string, ActionDefinition<any, any, any>>>(actions: TActions) => ComposedActions<TActions>;
 };
 
-export { ActionDefinition, ActionPermissionStatus, ActionsConfig, ComposedActions, OperationsFn, checkPermissionStatus, createActions };
+/**
+ * Options accepted by {@link forwardRequest}.
+ *
+ * Pass `body` to replace the original body (typical when an action handler
+ * builds a sub-action's payload), `method` to override the HTTP method, or
+ * `url` to dispatch to a different route. Any field omitted defaults to the
+ * value from the source request, so the new request stays a faithful clone
+ * of the original — including cookies, `Authorization`, `X-CSRF-Token`,
+ * and any other headers your auth or middleware layer relies on.
+ */
+type ForwardRequestInit = {
+    /**
+     * Replacement body for the forwarded request. Accepts anything `Request`
+     * itself accepts (including `FormData`, `URLSearchParams`, `string`, and
+     * `ReadableStream`). Pass `null` to forward without a body.
+     *
+     * Defaults to the source request's body. Note that streaming bodies are
+     * single-use, so the source request will be drained when forwarding the
+     * default body — clone the source request first if you need to read it
+     * elsewhere.
+     */
+    body?: BodyInit | null;
+    /** HTTP method override. Defaults to the source request's method. */
+    method?: string;
+    /** URL override. Defaults to the source request's URL. */
+    url?: string;
+    /**
+     * Additional headers to merge on top of the forwarded headers. Use this
+     * to set `Content-Type` (e.g. when replacing the body with JSON) without
+     * having to assemble a full `Headers` instance manually.
+     */
+    headers?: HeadersInit;
+};
+/**
+ * Builds a new {@link Request} that mirrors `original` (URL, method, headers,
+ * cookies) with optional overrides for body, URL, method, or extra headers.
+ *
+ * Use this when an action handler needs to dispatch a sub-action — for
+ * example, an "import CSV" action that builds many "create row" sub-action
+ * requests. Sub-actions resolved with the framework's `getContext()` callback
+ * see a `null` user unless the request still carries the original cookies,
+ * which is exactly what `forwardRequest` preserves.
+ *
+ * The returned request is a fresh `Request`, not a `clone()` of the source.
+ * That means:
+ *
+ * - The forwarded request has its own (drainable) body. Reading it does not
+ *   affect the source request.
+ * - Headers are deep-copied. Mutating the returned request's headers does
+ *   not leak back into the source.
+ * - When `body` is omitted, the source request's body stream is consumed.
+ *   If you need to keep the source readable, call `original.clone()` before
+ *   passing it in, or supply a fresh `body` explicitly.
+ *
+ * @param original - The incoming request to forward.
+ * @param init - Optional overrides for body, method, URL, and headers.
+ * @returns A new `Request` ready to hand to a sub-action.
+ *
+ * @example Basic sub-action dispatch
+ * ```ts
+ * import { forwardRequest } from "@cfast/actions";
+ *
+ * const importCsv = createAction(async (db, input, ctx) => ({
+ *   permissions: createRow.buildOperation(db, {} as never, ctx).permissions,
+ *   async run() {
+ *     for (const row of input.rows) {
+ *       const subFormData = new FormData();
+ *       subFormData.set("_action", "createRow");
+ *       subFormData.set("title", row.title);
+ *       const subRequest = forwardRequest(ctx.request, { body: subFormData });
+ *       await createRow.action({ request: subRequest, params: {}, context: undefined });
+ *     }
+ *     return { ok: true };
+ *   },
+ * }));
+ * ```
+ *
+ * @example JSON body with explicit Content-Type
+ * ```ts
+ * const subRequest = forwardRequest(originalRequest, {
+ *   body: JSON.stringify({ title: "Hello" }),
+ *   headers: { "Content-Type": "application/json" },
+ * });
+ * ```
+ */
+declare function forwardRequest(original: Request, init?: ForwardRequestInit): Request;
+
+export { ActionDefinition, ActionPermissionStatus, ActionServices, ActionsConfig, ComposedActions, type ForwardRequestInit, type InferInput, type InputField, type InputParser, type InputSchema, InvalidInputError, OperationsFn, checkPermissionStatus, createActions, defineInput, forwardRequest, z };

package/dist/index.js

@@ -58,21 +58,34 @@ function checkPermissionStatus(grants, descriptors) {
 }
 function createActions(config) {
   let counter = 0;
-  function createAction(operationsFn) {
+  const services = config.services ?? {};
+  async function resolveContext(args) {
+    const ctx = await config.getContext(args);
+    return {
+      db: ctx.db,
+      user: ctx.user,
+      grants: ctx.grants,
+      services: ctx.services ?? services
+    };
+  }
+  function createAction(config2) {
     const actionId = `action_${++counter}`;
+    const handler = typeof config2 === "function" ? config2 : config2.handler;
+    const parser = typeof config2 === "function" ? void 0 : config2.input;
     const action = async (args) => {
-      const ctx = await config.getContext(args);
-      const input = await parseInput(args.request);
-      const operation = operationsFn(ctx.db, input, ctx);
-      return operation.run({});
+      const ctx = await resolveContext(args);
+      const rawInput = await parseInput(args.request);
+      const input = parser ? parser(rawInput) : rawInput;
+      const operation = handler(ctx.db, input, ctx);
+      return operation.run();
     };
     const loader = (loaderFn) => {
       return async (args) => {
         const [loaderData, ctx] = await Promise.all([
           loaderFn(args),
-          config.getContext(args)
+          resolveContext(args)
         ]);
-        const operation = operationsFn(ctx.db, {}, ctx);
+        const operation = handler(ctx.db, {}, ctx);
         const status = checkPermissionStatus(ctx.grants, operation.permissions);
         const permissions = {
           [actionId]: status
@@ -89,7 +102,7 @@ function createActions(config) {
       permissionsKey: "_actionPermissions"
     };
     const buildOperation = (db, input, ctx) => {
-      return operationsFn(db, input, ctx);
+      return handler(db, input, ctx);
     };
     return { action, loader, client, buildOperation };
   }
@@ -108,7 +121,7 @@ function createActions(config) {
       return async (args) => {
         const [loaderData, ctx] = await Promise.all([
           loaderFn(args),
-          config.getContext(args)
+          resolveContext(args)
         ]);
         const permissions = {};
         for (const [name, actionDef] of Object.entries(actions)) {
@@ -135,7 +148,196 @@ function createActions(config) {
   }
   return { createAction, composeActions };
 }
+
+// src/input-schema.ts
+var InvalidInputError = class extends Error {
+  /** Field-keyed map of validation errors. */
+  errors;
+  constructor(errors) {
+    const summary = Object.entries(errors).map(([field, msg]) => `${field}: ${msg}`).join("; ");
+    super(`Invalid input: ${summary}`);
+    this.name = "InvalidInputError";
+    this.errors = errors;
+  }
+};
+function isMissing(raw) {
+  return raw === void 0 || raw === null || raw === "";
+}
+function stringField() {
+  return {
+    parse(raw) {
+      if (isMissing(raw)) {
+        return { ok: false, error: "is required" };
+      }
+      if (typeof raw === "string") {
+        return { ok: true, value: raw };
+      }
+      return { ok: false, error: "must be a string" };
+    }
+  };
+}
+function numberField() {
+  return {
+    parse(raw) {
+      if (isMissing(raw)) {
+        return { ok: false, error: "is required" };
+      }
+      let parsed;
+      if (typeof raw === "number") {
+        parsed = raw;
+      } else if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (trimmed === "") return { ok: false, error: "is required" };
+        parsed = Number(trimmed);
+      } else {
+        return { ok: false, error: "must be a number" };
+      }
+      if (!Number.isFinite(parsed)) {
+        return { ok: false, error: "must be a finite number" };
+      }
+      return { ok: true, value: parsed };
+    }
+  };
+}
+function integerField() {
+  const num = numberField();
+  return {
+    parse(raw) {
+      const result = num.parse(raw);
+      if (!result.ok) return result;
+      if (!Number.isInteger(result.value)) {
+        return { ok: false, error: "must be an integer" };
+      }
+      return result;
+    }
+  };
+}
+function booleanField() {
+  return {
+    parse(raw) {
+      if (isMissing(raw)) {
+        return { ok: false, error: "is required" };
+      }
+      if (typeof raw === "boolean") return { ok: true, value: raw };
+      if (typeof raw === "string") {
+        const lowered = raw.toLowerCase();
+        if (lowered === "true" || lowered === "on" || lowered === "1") {
+          return { ok: true, value: true };
+        }
+        if (lowered === "false" || lowered === "off" || lowered === "0") {
+          return { ok: true, value: false };
+        }
+      }
+      return { ok: false, error: "must be a boolean" };
+    }
+  };
+}
+function optionalField(inner) {
+  return {
+    parse(raw) {
+      if (isMissing(raw)) return { ok: true, value: void 0 };
+      return inner.parse(raw);
+    }
+  };
+}
+function nullableField(inner) {
+  return {
+    parse(raw) {
+      if (isMissing(raw)) return { ok: true, value: null };
+      return inner.parse(raw);
+    }
+  };
+}
+function customField(parser) {
+  return {
+    parse(raw) {
+      try {
+        return { ok: true, value: parser(raw) };
+      } catch (e) {
+        const message = e instanceof Error ? e.message : "is invalid";
+        return { ok: false, error: message };
+      }
+    }
+  };
+}
+var z = {
+  string: stringField,
+  number: numberField,
+  integer: integerField,
+  boolean: booleanField,
+  optional: optionalField,
+  nullable: nullableField,
+  custom: customField
+};
+function defineInput(schema) {
+  return (raw) => {
+    const result = {};
+    const errors = {};
+    for (const [field, validator] of Object.entries(schema)) {
+      const parsed = validator.parse(raw[field]);
+      if (parsed.ok) {
+        result[field] = parsed.value;
+      } else {
+        errors[field] = parsed.error;
+      }
+    }
+    if (Object.keys(errors).length > 0) {
+      throw new InvalidInputError(errors);
+    }
+    return result;
+  };
+}
+
+// src/forward-request.ts
+function forwardRequest(original, init = {}) {
+  const headers = new Headers(original.headers);
+  if (init.headers) {
+    const overrides = new Headers(init.headers);
+    overrides.forEach((value, key) => {
+      headers.set(key, value);
+    });
+  }
+  const method = init.method ?? original.method;
+  const url = init.url ?? original.url;
+  const bodylessMethod = method === "GET" || method === "HEAD";
+  if (bodylessMethod && init.body !== void 0 && init.body !== null) {
+    throw new TypeError(
+      `forwardRequest: cannot attach a body to a ${method} request. Either omit "body" or set "method" to a body-bearing verb (e.g. POST).`
+    );
+  }
+  let body;
+  if (init.body !== void 0) {
+    body = init.body;
+    const isStructuredBody = typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams;
+    const callerSetContentType = init.headers !== void 0 && new Headers(init.headers).has("content-type");
+    if (isStructuredBody && !callerSetContentType) {
+      headers.delete("content-type");
+      headers.delete("content-length");
+    }
+  } else if (bodylessMethod) {
+    body = null;
+  } else {
+    body = original.body;
+  }
+  const requestInit = {
+    method,
+    headers,
+    body,
+    redirect: original.redirect,
+    referrer: original.referrer,
+    referrerPolicy: original.referrerPolicy,
+    signal: original.signal
+  };
+  if (body !== null && typeof body.getReader === "function") {
+    requestInit.duplex = "half";
+  }
+  return new Request(url, requestInit);
+}
 export {
+  InvalidInputError,
   checkPermissionStatus,
-  createActions
+  createActions,
+  defineInput,
+  forwardRequest,
+  z
 };

package/dist/{types-Dolh-eut.d.ts → types-ogCcbQm3.d.ts}

@@ -10,30 +10,61 @@ import { Grant } from '@cfast/permissions';
 type Serializable = string | number | boolean | null | Serializable[] | {
     [key: string]: Serializable;
 };
+/**
+ * A record of arbitrary external services an action handler may depend on.
+ *
+ * Services are registered once at {@link createActions} time and made
+ * available on every action's {@link ActionContext} via `ctx.services`.
+ * Use this to inject HTTP clients, email providers, cache adapters,
+ * third-party APIs, etc., without each handler having to import them
+ * directly — which both improves testability (services can be mocked
+ * per-suite) and keeps action modules decoupled from concrete providers.
+ *
+ * @example
+ * ```ts
+ * type Services = {
+ *   nutritionApi: { lookup: (name: string) => Promise<Nutrition> };
+ *   mailer: { sendWelcome: (to: string) => Promise<void> };
+ * };
+ * ```
+ */
+type ActionServices = Record<string, any>;
 /**
  * Context provided to every action's {@link OperationsFn}.
  *
  * Created by the `getContext` callback in {@link ActionsConfig} and passed
- * alongside the database instance and parsed input to each action.
+ * alongside the database instance and parsed input to each action. When
+ * `services` are registered with {@link createActions}, they appear on
+ * `ctx.services` so handlers can access them without importing module-
+ * level singletons.
  *
  * @typeParam TUser - The shape of the authenticated user object.
+ * @typeParam TServices - The shape of the registered services map. Defaults
+ *   to an empty record when no services are registered.
  *
  * @example
  * ```ts
- * const ctx: ActionContext<{ id: string; role: string }> = {
+ * const ctx: ActionContext<{ id: string; role: string }, { nutritionApi: NutritionApi }> = {
  *   db,
  *   user: { id: "u_1", role: "author" },
  *   grants: [{ action: "manage", subject: "all" }],
+ *   services: { nutritionApi },
  * };
  * ```
  */
-type ActionContext<TUser> = {
+type ActionContext<TUser, TServices extends ActionServices = ActionServices> = {
     /** The Drizzle database instance from `@cfast/db`. */
     db: Db;
     /** The authenticated user for the current request. */
     user: TUser;
     /** The user's permission {@link Grant | grants}, used for permission checking. */
     grants: Grant[];
+    /**
+     * External services registered with {@link createActions}. Defaults to
+     * an empty object `{}` when no services are provided at factory time,
+     * so handlers can always safely destructure `ctx.services`.
+     */
+    services: TServices;
 };
 /**
  * Subset of React Router loader/action arguments consumed by `@cfast/actions`.
@@ -53,11 +84,19 @@ type RequestArgs = {
  * Configuration for the {@link createActions} factory.
  *
  * Provides a `getContext` callback that resolves the per-request
- * {@link ActionContext} (database, user, grants) for every action invocation.
+ * {@link ActionContext} (database, user, grants) for every action
+ * invocation, plus an optional `services` bag that is injected into
+ * every action's context as `ctx.services`.
+ *
+ * `getContext` is allowed to return an `ActionContext` without the
+ * `services` field (the backward-compatible shape) — the factory will
+ * fill it in with the registered services (or an empty object) so that
+ * every handler can always rely on `ctx.services` being defined.
  *
  * @typeParam TUser - The shape of the authenticated user object.
+ * @typeParam TServices - The shape of the registered services map.
  *
- * @example
+ * @example Basic usage without services
  * ```ts
  * const config: ActionsConfig<AppUser> = {
  *   getContext: async ({ request }) => {
@@ -67,10 +106,39 @@ type RequestArgs = {
  *   },
  * };
  * ```
+ *
+ * @example With service injection
+ * ```ts
+ * const { createAction } = createActions<AppUser, { nutritionApi: NutritionApi }>({
+ *   getContext: async ({ request }) => { ... },
+ *   services: { nutritionApi: createNutritionApi(env.NUTRITION_API_KEY) },
+ * });
+ *
+ * const lookupFood = createAction((db, input, ctx) => ({
+ *   permissions: [],
+ *   run: async () => ctx.services.nutritionApi.lookup(input.name),
+ * }));
+ * ```
  */
-type ActionsConfig<TUser> = {
-    /** Resolves the per-request action context from the route handler arguments. */
-    getContext: (args: RequestArgs) => Promise<ActionContext<TUser>>;
+type ActionsConfig<TUser, TServices extends ActionServices = ActionServices> = {
+    /**
+     * Resolves the per-request action context from the route handler arguments.
+     *
+     * The returned context does not need to include `services` — the factory
+     * merges the registered `services` config in automatically. This keeps
+     * the callback ergonomic for the common case (auth + DB only) while
+     * still letting advanced users return a fully-formed context.
+     */
+    getContext: (args: RequestArgs) => Promise<Omit<ActionContext<TUser, TServices>, "services"> & {
+        services?: TServices;
+    }>;
+    /**
+     * External services made available to every action handler as
+     * `ctx.services`. Registering services here keeps handlers free of
+     * module-level imports of third-party APIs and makes it trivial to
+     * mock them in tests. Defaults to `{}` when omitted.
+     */
+    services?: TServices;
 };
 /**
  * A function that builds a database {@link Operation} for an action.
@@ -217,4 +285,4 @@ type ComposedActions<TActions extends Record<string, ActionDefinition<any, any,
     actions: TActions;
 };
 
-export type { ActionPermissionStatus as A, ClientDescriptor as C, OperationsFn as O, RequestArgs as R, Serializable as S, ActionsConfig as a, ActionDefinition as b, ComposedActions as c, ActionContext as d, ActionPermissionsMap as e };
+export type { ActionPermissionStatus as A, ClientDescriptor as C, OperationsFn as O, RequestArgs as R, Serializable as S, ActionServices as a, ActionsConfig as b, ActionDefinition as c, ComposedActions as d, ActionContext as e, ActionPermissionsMap as f };

package/llms.txt

@@ -29,6 +29,14 @@ function createActions<TUser>(config: ActionsConfig<TUser>): {
 
 function checkPermissionStatus(grants: Grant[], descriptors: PermissionDescriptor[]): ActionPermissionStatus;
 
+function forwardRequest(original: Request, init?: ForwardRequestInit): Request;
+type ForwardRequestInit = {
+  body?: BodyInit | null;          // override body (FormData / JSON / null)
+  method?: string;                  // override HTTP method
+  url?: string;                     // override URL
+  headers?: HeadersInit;            // merged on top of original headers
+};
+
 type ActionsConfig<TUser> = {
   getContext: (args: RequestArgs) => Promise<ActionContext<TUser>>;
 };
@@ -145,7 +153,41 @@ export const loader = composed.loader(async ({ params }) => {
 });
 ```
 
-### 4. Use on the client
+### 4. Dispatch sub-actions with `forwardRequest`
+
+When an action handler builds a sub-request to call another action, the
+sub-action's `getContext()` will see a `null` user unless the sub-request
+carries the original cookies. `forwardRequest()` clones the original request
+with new body / method / URL while preserving cookies, auth headers, and
+other middleware state:
+
+```typescript
+import { forwardRequest } from "@cfast/actions";
+import { createRow } from "~/actions/rows";
+
+export const importCsv = createAction(async (db, input, ctx) => ({
+  permissions: createRow.buildOperation(db, {} as never, ctx).permissions,
+  async run() {
+    for (const row of input.rows) {
+      const subFormData = new FormData();
+      subFormData.set("_action", "createRow");
+      subFormData.set("title", row.title);
+
+      // Cookies, Authorization, X-CSRF-Token, etc. are all preserved.
+      const subRequest = forwardRequest(ctx.request, { body: subFormData });
+      await createRow.action({ request: subRequest, params: {}, context: undefined });
+    }
+    return { ok: true };
+  },
+}));
+```
+
+`forwardRequest` strips the original `Content-Type` automatically when the
+new body is `FormData` or `URLSearchParams`, so the platform can attach the
+correct multipart boundary. Pass an explicit `headers: { "content-type": ... }`
+to override.
+
+### 5. Use on the client
 ```typescript
 import { useActions } from "@cfast/actions/client";
 
@@ -174,3 +216,8 @@ function PostActions({ postId }) {
 - Using `createAction` directly without first calling `createActions` to set up the factory. `createAction` is returned by `createActions`, not a standalone export.
 - Omitting the `_action` hidden input in forms when using `composeActions`. The discriminator field is required to route to the correct handler.
 - Calling `useActions` with the wrong descriptor. Use `composed.client` for composed actions, or `singleAction.client` for a single action.
+
+## See Also
+
+- `@cfast/db` -- Permission descriptors come from Operation results.
+- `@cfast/permissions` -- Defines the grants enforced by action permissions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/actions",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Multi-action routes and permission-aware action definitions for React Router",
   "keywords": [
     "cfast",
@@ -37,20 +37,19 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup src/index.ts src/client.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "test": "vitest run"
-  },
   "peerDependencies": {
+    "@cfast/db": ">=0.3.0 <0.5.0",
+    "@cfast/permissions": ">=0.3.0 <0.5.0",
     "react": "^19.0.0",
     "react-router": "^7.0.0"
   },
-  "dependencies": {
-    "@cfast/db": "workspace:*",
-    "@cfast/permissions": "workspace:*"
+  "peerDependenciesMeta": {
+    "@cfast/db": {
+      "optional": false
+    },
+    "@cfast/permissions": {
+      "optional": false
+    }
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260305.1",
@@ -59,6 +58,15 @@
     "react-router": "^7.6.0",
     "tsup": "^8",
     "typescript": "^5.7",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "@cfast/db": "0.4.0",
+    "@cfast/permissions": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/client.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run"
   }
-}
+}