@cfast/actions 0.1.2 → 0.2.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { C as ClientDescriptor, S as Serializable } from './types-ogCcbQm3.js';
+import { C as ClientDescriptor, S as Serializable } from './types-C1PGA5l3.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Form } from 'react-router';
 import { ComponentProps, ReactNode } from 'react';
@@ -9,8 +9,16 @@ import '@cfast/permissions';
  * Creates a ClientDescriptor for use in client code without importing
  * server modules. The action names must match the keys passed to
  * `composeActions` or the single action name from `createAction`.
+ *
+ * Pass a `readonly` tuple (`as const`) to get compile-time type-checking
+ * of action names throughout the client code:
+ *
+ * ```ts
+ * const client = clientDescriptor(["create", "delete"] as const);
+ * // client is ClientDescriptor<readonly ["create", "delete"]>
+ * ```
  */
-declare function clientDescriptor(actionNames: readonly string[]): ClientDescriptor;
+declare function clientDescriptor<const TNames extends readonly string[]>(actionNames: TNames): ClientDescriptor<TNames>;
 type ActionHookResult = {
     permitted: boolean;
     invisible: boolean;
@@ -20,7 +28,9 @@ type ActionHookResult = {
     data: unknown | undefined;
     error: unknown | undefined;
 };
-declare function useActions(descriptor: ClientDescriptor): Record<string, (input?: Serializable) => ActionHookResult>;
+declare function useActions<const TNames extends readonly string[]>(descriptor: ClientDescriptor<TNames>): {
+    [K in TNames[number]]: (input?: Serializable) => ActionHookResult;
+};
 
 type ActionFormProps = Omit<ComponentProps<typeof Form>, "children" | "action"> & {
     /** Object with `_action` key and input fields to inject as hidden inputs. */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Grant, PermissionDescriptor } from '@cfast/permissions';
-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 { A as ActionPermissionStatus, a as ActionServices, b as ActionsConfig, O as OperationsFn, c as ActionDefinition, d as ComposedActions } from './types-C1PGA5l3.js';
+export { e as ActionContext, f as ActionPermissionsMap, C as ClientDescriptor, D as DispatchArgs, R as RequestArgs, S as Serializable } from './types-C1PGA5l3.js';
 import '@cfast/db';
 
 /**

package/dist/index.js

@@ -104,7 +104,12 @@ function createActions(config) {
     const buildOperation = (db, input, ctx) => {
       return handler(db, input, ctx);
     };
-    return { action, loader, client, buildOperation };
+    const dispatch = async (args) => {
+      const { ctx, input } = args;
+      const operation = handler(ctx.db, input, ctx);
+      return operation.run();
+    };
+    return { action, dispatch, loader, client, buildOperation };
   }
   function composeActions(actions) {
     const actionNames = Object.keys(actions);

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

@@ -80,6 +80,37 @@ type RequestArgs = {
     /** Optional context object (e.g., Cloudflare Workers env via `context.cloudflare.env`). */
     context?: unknown;
 };
+/**
+ * Arguments for {@link ActionDefinition.dispatch}, which lets a parent action
+ * invoke a sub-action **without** constructing a new `Request`.
+ *
+ * The parent passes its already-resolved {@link ActionContext} and the typed
+ * input directly. This avoids re-running `getContext()` (and thus the
+ * cookie-based session lookup) for the sub-action, which is both faster and
+ * eliminates the class of bugs described in issue #185 where a manually-built
+ * `Request` forgets to forward the `Cookie` header.
+ *
+ * @typeParam TInput - The expected input shape for the target action.
+ * @typeParam TUser - The shape of the authenticated user object.
+ *
+ * @example
+ * ```ts
+ * const parent = createAction((db, input, ctx) => ({
+ *   permissions: [],
+ *   async run() {
+ *     // No Request needed — ctx is reused directly.
+ *     const result = await child.dispatch({ ctx, input: { title: "Hello" } });
+ *     return result;
+ *   },
+ * }));
+ * ```
+ */
+type DispatchArgs<TInput, TUser> = {
+    /** The parent action's already-resolved context, reused as-is. */
+    ctx: ActionContext<TUser>;
+    /** Typed input for the sub-action. */
+    input: TInput;
+};
 /**
  * Configuration for the {@link createActions} factory.
  *
@@ -192,11 +223,11 @@ type ActionPermissionsMap = Record<string, ActionPermissionStatus>;
  * Created by {@link ActionDefinition.client} or {@link ComposedActions.client}.
  * Contains the action names and the key used to read permission data from loader results.
  */
-type ClientDescriptor = {
+type ClientDescriptor<TNames extends readonly string[] = readonly string[]> = {
     /** Brand field to distinguish this type at the type level. */
     _brand: "ActionClientDescriptor";
     /** The list of action names this descriptor covers. */
-    actionNames: readonly string[];
+    actionNames: TNames;
     /** The loader-data key where {@link ActionPermissionsMap} is stored. */
     permissionsKey: string;
 };
@@ -230,6 +261,30 @@ type ClientDescriptor = {
 type ActionDefinition<TInput, TResult, TUser> = {
     /** React Router action handler. Parses input, resolves context, and runs the operation. */
     action: (args: RequestArgs) => Promise<TResult>;
+    /**
+     * Dispatches the action using an already-resolved {@link ActionContext},
+     * bypassing `getContext()` entirely.
+     *
+     * Use this when a parent action handler needs to invoke a sub-action.
+     * Because the parent's `ctx` is reused directly, cookies, user session,
+     * and grants are inherited without constructing a new `Request` — which
+     * eliminates the cookie-forwarding bug described in issue #185.
+     *
+     * @param args - The {@link DispatchArgs} containing the parent's `ctx`
+     *   and the typed input for this action.
+     * @returns The action's result, same as calling `.action()`.
+     *
+     * @example
+     * ```ts
+     * const parent = createAction((db, input, ctx) => ({
+     *   permissions: [],
+     *   async run() {
+     *     return child.dispatch({ ctx, input: { title: "Hello" } });
+     *   },
+     * }));
+     * ```
+     */
+    dispatch: (args: DispatchArgs<TInput, TUser>) => Promise<TResult>;
     /**
      * Wraps a loader function to inject {@link ActionPermissionsMap} into its return value.
      *
@@ -285,4 +340,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, ActionServices as a, ActionsConfig as b, ActionDefinition as c, ComposedActions as d, ActionContext as e, ActionPermissionsMap as f };
+export type { ActionPermissionStatus as A, ClientDescriptor as C, DispatchArgs as D, 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

@@ -68,9 +68,31 @@ type ActionPermissionsMap = Record<string, ActionPermissionStatus>;
 
 ### Client (`@cfast/actions/client`)
 
+#### Type-safe `clientDescriptor()` and `useActions()`
+
+`clientDescriptor()` now uses `const` type parameters to infer the literal tuple
+type from the action names array. `useActions()` returns a mapped type keyed by
+those literal names instead of `Record<string, ...>`, giving compile-time
+autocomplete and error checking on action names.
+
+```typescript
+// Type-safe: actions.create and actions.delete are typed, typos are caught
+const client = clientDescriptor(["create", "delete"]);
+// client is ClientDescriptor<readonly ["create", "delete"]>
+
+const actions = useActions(client);
+// actions is { create: (input?) => ActionHookResult; delete: (input?) => ActionHookResult }
+// actions.creat → TypeScript error (typo caught at compile time)
+```
+
 ```typescript
-function useActions(descriptor: ClientDescriptor): Record<string, (input?: Serializable) => ActionHookResult>;
-function clientDescriptor(actionNames: readonly string[]): ClientDescriptor;
+function useActions<const TNames extends readonly string[]>(
+  descriptor: ClientDescriptor<TNames>,
+): { [K in TNames[number]]: (input?: Serializable) => ActionHookResult };
+
+function clientDescriptor<const TNames extends readonly string[]>(
+  actionNames: TNames,
+): ClientDescriptor<TNames>;
 
 function ActionForm(props: ActionFormProps): JSX.Element;
 
@@ -187,7 +209,37 @@ 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
+### 5. Dispatch sub-actions with `action.dispatch()` (preferred)
+
+`action.dispatch({ ctx, input })` calls an action's operation directly,
+bypassing Request construction entirely. No cookie forwarding, no FormData
+serialisation, no `forwardRequest()` boilerplate -- just pass the context
+and input you already have:
+
+```typescript
+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) {
+      await createRow.dispatch({
+        ctx: { db, user: ctx.user, grants: ctx.grants, services: {} },
+        input: { title: row.title },
+      });
+    }
+    return { ok: true };
+  },
+}));
+```
+
+`dispatch()` reuses the caller's `db`, `user`, and `grants` directly, so
+permission checks still run on the sub-action's operation. Use `dispatch()`
+for all server-to-server sub-action calls. `forwardRequest()` still works
+but is only needed when you must go through the full HTTP action handler
+(e.g., calling an action in a different Worker).
+
+### 6. Use on the client
 ```typescript
 import { useActions } from "@cfast/actions/client";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/actions",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Multi-action routes and permission-aware action definitions for React Router",
   "keywords": [
     "cfast",
@@ -39,7 +39,7 @@
   },
   "peerDependencies": {
     "@cfast/db": ">=0.3.0 <0.5.0",
-    "@cfast/permissions": ">=0.3.0 <0.5.0",
+    "@cfast/permissions": ">=0.3.0 <0.6.0",
     "react": "^19.0.0",
     "react-router": "^7.0.0"
   },
@@ -59,8 +59,8 @@
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0",
-    "@cfast/db": "0.4.0",
-    "@cfast/permissions": "0.4.0"
+    "@cfast/db": "0.5.0",
+    "@cfast/permissions": "0.5.1"
   },
   "scripts": {
     "build": "tsup src/index.ts src/client.ts --format esm --dts",