@diphyx/harlemify 5.4.1 → 6.0.0

package/README.md

@@ -13,6 +13,13 @@ Define your data **shape** once with Zod — get typed **models**, computed **vi
 - **Vue composables** — Reactive helpers for actions, models, and views in components
 - **SSR ready** — Server-side rendering with automatic state hydration
 
+## For AI Agents
+
+If you are an AI coding agent working on a project that uses `@diphyx/harlemify`, read **[`docs/AGENTS.md`](docs/AGENTS.md)** first. It is a single-file, end-to-end reference (shapes, models, views, actions, compose, composables, SSR, lazy stores, concurrency, cancellation, isolated status, logging) designed to give you the full mental model in one read.
+
+- Source: [`docs/AGENTS.md`](docs/AGENTS.md)
+- Rendered: [https://diphyx.github.io/harlemify/#/AGENTS](https://diphyx.github.io/harlemify/#/AGENTS)
+
 ## Install
 
 ```bash

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.14.0 || ^4.0.0"
   },
-  "version": "5.4.1",
+  "version": "6.0.0",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "unknown"

package/dist/runtime/core/layers/action.js

@@ -3,7 +3,7 @@ import {
   ActionApiMethod
 } from "../types/action.js";
 export function createActionFactory(config, logger) {
-  function apiCall(request, commit) {
+  function apiCall(request, ...commits) {
     return wrapBaseDefinition({
       request: {
         endpoint: config?.endpoint,
@@ -13,57 +13,27 @@ export function createActionFactory(config, logger) {
         concurrent: config?.concurrent,
         ...request
       },
-      commit,
+      commits,
       logger
     });
   }
-  function apiGet(request, commit) {
-    return apiCall({ ...request, method: ActionApiMethod.GET }, commit);
+  function apiGet(request, ...commits) {
+    return apiCall({ ...request, method: ActionApiMethod.GET }, ...commits);
   }
-  function apiHead(request, commit) {
-    return apiCall(
-      {
-        ...request,
-        method: ActionApiMethod.HEAD
-      },
-      commit
-    );
+  function apiHead(request, ...commits) {
+    return apiCall({ ...request, method: ActionApiMethod.HEAD }, ...commits);
   }
-  function apiPost(request, commit) {
-    return apiCall(
-      {
-        ...request,
-        method: ActionApiMethod.POST
-      },
-      commit
-    );
+  function apiPost(request, ...commits) {
+    return apiCall({ ...request, method: ActionApiMethod.POST }, ...commits);
   }
-  function apiPut(request, commit) {
-    return apiCall(
-      {
-        ...request,
-        method: ActionApiMethod.PUT
-      },
-      commit
-    );
+  function apiPut(request, ...commits) {
+    return apiCall({ ...request, method: ActionApiMethod.PUT }, ...commits);
   }
-  function apiPatch(request, commit) {
-    return apiCall(
-      {
-        ...request,
-        method: ActionApiMethod.PATCH
-      },
-      commit
-    );
+  function apiPatch(request, ...commits) {
+    return apiCall({ ...request, method: ActionApiMethod.PATCH }, ...commits);
   }
-  function apiDelete(request, commit) {
-    return apiCall(
-      {
-        ...request,
-        method: ActionApiMethod.DELETE
-      },
-      commit
-    );
+  function apiDelete(request, ...commits) {
+    return apiCall({ ...request, method: ActionApiMethod.DELETE }, ...commits);
   }
   const api = Object.assign(apiCall, {
     get: apiGet,

package/dist/runtime/core/types/action.d.ts

@@ -52,9 +52,12 @@ export interface ActionApiCommit<MD extends ModelDefinitions, K extends keyof MD
     value?: (data: unknown) => unknown;
     options?: ModelOneCommitOptions | ModelManyCommitOptions;
 }
-export interface ActionApiDefinition<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>, K extends keyof MD = keyof MD> extends BaseDefinition {
+export type ActionApiCommitReturn<MD extends ModelDefinitions, C extends readonly ActionApiCommit<MD>[]> = C extends readonly [] ? unknown : {
+    [E in C[number] as E["model"] & string]: E["model"] extends keyof MD ? ModelDefinitionInfer<MD, E["model"]> : never;
+};
+export interface ActionApiDefinition<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>, C extends readonly ActionApiCommit<MD>[] = readonly ActionApiCommit<MD>[]> extends BaseDefinition {
     request: ActionApiRequest<MD, VD>;
-    commit?: ActionApiCommit<MD, K>;
+    commits: C;
 }
 export interface ActionHandlerOptions<P = unknown> {
     payload?: P;
@@ -69,23 +72,27 @@ export interface ActionHandlerDefinition<MD extends ModelDefinitions, VD extends
     callback: ActionHandlerCallback<MD, VD, P, R>;
     options?: ActionHandlerOptions<P>;
 }
-export type ActionDefinition<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>> = ActionApiDefinition<MD, VD> | ActionHandlerDefinition<MD, VD, any, any>;
+export type ActionDefinition<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>> = ActionApiDefinition<MD, VD, any> | ActionHandlerDefinition<MD, VD, any, any>;
 export type ActionDefinitions<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>> = Record<string, ActionDefinition<MD, VD>>;
+type ActionApiCommitTuple<MD extends ModelDefinitions> = readonly [
+    ActionApiCommit<MD, keyof MD>,
+    ...ActionApiCommit<MD, keyof MD>[]
+];
 export interface ActionApiFactory<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>> {
-    <K extends keyof MD>(request: ActionApiRequest<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    (request: ActionApiRequest<MD, VD>): ActionApiDefinition<MD, VD>;
-    get<K extends keyof MD>(request: ActionApiRequestShortcut<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    get(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD>;
-    head<K extends keyof MD>(request: ActionApiRequestShortcut<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    head(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD>;
-    post<K extends keyof MD>(request: ActionApiRequestShortcut<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    post(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD>;
-    put<K extends keyof MD>(request: ActionApiRequestShortcut<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    put(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD>;
-    patch<K extends keyof MD>(request: ActionApiRequestShortcut<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    patch(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD>;
-    delete<K extends keyof MD>(request: ActionApiRequestShortcut<MD, VD>, commit: ActionApiCommit<MD, K>): ActionApiDefinition<MD, VD, K>;
-    delete(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD>;
+    (request: ActionApiRequest<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    <const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequest<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
+    get(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    get<const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequestShortcut<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
+    head(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    head<const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequestShortcut<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
+    post(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    post<const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequestShortcut<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
+    put(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    put<const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequestShortcut<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
+    patch(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    patch<const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequestShortcut<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
+    delete(request: ActionApiRequestShortcut<MD, VD>): ActionApiDefinition<MD, VD, []>;
+    delete<const C extends ActionApiCommitTuple<MD>>(request: ActionApiRequestShortcut<MD, VD>, ...commits: C): ActionApiDefinition<MD, VD, C>;
 }
 export interface ActionHandlerFactory<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>> {
     <P = unknown, R = void>(callback: ActionHandlerCallback<MD, VD, P, R>, options?: ActionHandlerOptions<P>): ActionHandlerDefinition<MD, VD, P, R>;
@@ -116,7 +123,7 @@ export interface ActionCallTransformerOptions {
     response?: (data: unknown) => unknown;
 }
 export interface ActionCallCommitOptions {
-    mode?: ModelOneMode | ModelManyMode;
+    mode?: ModelOneMode | ModelManyMode | Record<string, ModelOneMode | ModelManyMode>;
 }
 export interface ActionApiCallOptions extends ActionCallBaseOptions {
     params?: Record<string, string>;
@@ -153,5 +160,6 @@ export interface ActionHandlerCall<P = unknown, T = void> extends ActionCallBase
 }
 export type ActionCall<T = void> = ActionApiCall<T> | ActionHandlerCall<any, T>;
 export type StoreAction<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>, AD extends ActionDefinitions<MD, VD>> = {
-    [K in keyof AD]: AD[K] extends ActionApiDefinition<MD, VD, infer MK> ? MK extends keyof MD ? ActionApiCall<ModelDefinitionInfer<MD, MK>> : ActionApiCall : AD[K] extends ActionHandlerDefinition<MD, VD, infer P, infer R> ? ActionHandlerCall<P, R> : never;
+    [K in keyof AD]: AD[K] extends ActionApiDefinition<MD, VD, infer C> ? C extends readonly ActionApiCommit<MD>[] ? ActionApiCall<ActionApiCommitReturn<MD, C>> : ActionApiCall : AD[K] extends ActionHandlerDefinition<MD, VD, infer P, infer R> ? ActionHandlerCall<P, R> : never;
 };
+export {};

package/dist/runtime/core/types/view.d.ts

@@ -23,7 +23,7 @@ export interface ViewMergeDefinition<MD extends ModelDefinitions, K extends read
     resolver: ViewMergeDefinitionResolver<MD, K, R>;
     options?: ViewDefinitionOptions;
 }
-export type ViewDefinition<MD extends ModelDefinitions> = ViewFromDefinition<MD, keyof MD, unknown> | ViewMergeDefinition<MD, readonly (keyof MD)[], unknown>;
+export type ViewDefinition<MD extends ModelDefinitions> = ViewFromDefinition<MD, any, any> | ViewMergeDefinition<MD, any, any>;
 export type ViewDefinitions<MD extends ModelDefinitions> = Record<string, ViewDefinition<MD>>;
 export type ViewDefinitionInfer<MD extends ModelDefinitions, VD extends ViewDefinition<MD>> = VD extends ViewFromDefinition<MD, infer _K, infer R> ? R : VD extends ViewMergeDefinition<MD, infer _K, infer R> ? R : never;
 export interface ViewFactory<MD extends ModelDefinitions> {

package/dist/runtime/core/utils/action.js

@@ -55,7 +55,7 @@ function resolveApiBody(definition, view, target, options) {
   if (!isPlainObject(body)) {
     return body;
   }
-  if (!isEmptyRecord(target?.aliases())) {
+  if (target && !isEmptyRecord(target.aliases())) {
     return resolveAliasOutbound(body, target.aliases());
   }
   return body;
@@ -87,22 +87,17 @@ function resolveHandlerPayload(definition, options) {
   }
   return void 0;
 }
-function resolveApiCommitTarget(commit, model) {
-  if (commit) {
-    return model[commit.model];
-  }
-  return void 0;
-}
-function resolveApiCommitMode(commit, options) {
-  if (commit) {
-    if (options?.commit?.mode) {
-      return options.commit.mode;
+function resolveCommitMode(commit, options) {
+  const override = options?.commit?.mode;
+  if (override) {
+    if (typeof override === "object") {
+      return override[commit.model] ?? commit.mode;
     }
-    return commit.mode;
+    return override;
   }
-  return void 0;
+  return commit.mode;
 }
-function resolveApiCommitValue(commit, data) {
+function resolveCommitValue(commit, data) {
   if (typeof commit.value === "function") {
     return commit.value(data);
   }
@@ -182,26 +177,27 @@ async function executeHandler(definition, handler) {
     throw handlerError;
   }
 }
-function executeCommit(definition, target, mode, data) {
-  if (!definition.commit) {
-    return;
-  }
-  if (!target || !mode) {
-    throw new ActionCommitError({
-      message: `Model "${definition.commit.model}" is not defined`
-    });
+function executeCommit(definition, model, data, options) {
+  const commits = definition.commits;
+  if (!commits || commits.length === 0) {
+    return data;
   }
+  const plan = [];
   try {
-    definition.logger?.debug("Action commit phase", {
-      action: definition.key,
-      target,
-      mode
-    });
-    if (!isEmptyRecord(target.aliases())) {
-      data = resolveAliasInbound(data, target.aliases());
+    for (const commit of commits) {
+      const target = model[commit.model];
+      if (!target) {
+        throw new ActionCommitError({
+          message: `Model "${commit.model}" is not defined`
+        });
+      }
+      const mode = resolveCommitMode(commit, options);
+      let value = resolveCommitValue(commit, data);
+      if (!isEmptyRecord(target.aliases())) {
+        value = resolveAliasInbound(value, target.aliases());
+      }
+      plan.push({ commit, target, mode, value });
     }
-    const value = resolveApiCommitValue(definition.commit, data);
-    target.commit(mode, value, definition.commit.options);
   } catch (error) {
     const commitError = toError(error, ActionCommitError);
     definition.logger?.error("Action commit error", {
@@ -210,6 +206,26 @@ function executeCommit(definition, target, mode, data) {
     });
     throw commitError;
   }
+  const result = {};
+  for (const entry of plan) {
+    definition.logger?.debug("Action commit phase", {
+      action: definition.key,
+      target: entry.target,
+      mode: entry.mode
+    });
+    try {
+      entry.target.commit(entry.mode, entry.value, entry.commit.options);
+    } catch (error) {
+      const commitError = toError(error, ActionCommitError);
+      definition.logger?.error("Action commit error", {
+        action: definition.key,
+        error: commitError.message
+      });
+      throw commitError;
+    }
+    result[entry.commit.model] = entry.value;
+  }
+  return result;
 }
 export function createAction(definition, model, view) {
   const actionType = isApiDefinition(definition) ? ActionType.API : ActionType.HANDLER;
@@ -258,16 +274,16 @@ export function createAction(definition, model, view) {
       try {
         let data = void 0;
         if (isApiDefinition(definition)) {
-          const target = resolveApiCommitTarget(definition.commit, model);
-          const mode = resolveApiCommitMode(definition.commit, options);
+          const firstCommit = definition.commits?.[0];
+          const bodyTarget = firstCommit ? model[firstCommit.model] : void 0;
           const url = resolveApiUrl(definition, view, options);
           const method = resolveApiMethod(definition, view);
           const headers = resolveApiHeaders(definition, view, options);
           const query = resolveApiQuery(definition, view, options);
-          const body = resolveApiBody(definition, view, target, options);
+          const body = resolveApiBody(definition, view, bodyTarget, options);
           const timeout = resolveApiTimeout(definition, view, options);
           const signal = resolveApiSignal(options, abortController);
-          data = await executeApi(
+          const response = await executeApi(
             definition,
             {
               url,
@@ -280,7 +296,7 @@ export function createAction(definition, model, view) {
             },
             options
           );
-          executeCommit(definition, target, mode, data);
+          data = executeCommit(definition, model, response, options);
         } else if (isHandlerDefinition(definition)) {
           const payload = resolveHandlerPayload(definition, options);
           data = await executeHandler(definition, {

package/dist/runtime/index.d.ts

@@ -8,7 +8,7 @@ export { ViewClone } from "./core/types/view.js";
 export type { ViewDefinitionOptions } from "./core/types/view.js";
 export { ActionStatus, ActionConcurrent, ActionType, ActionApiMethod } from "./core/types/action.js";
 export type { ActionCall, ActionApiCall, ActionHandlerCall, ActionCallOptions, ActionCallBaseOptions, ActionApiCallOptions, ActionHandlerCallOptions, ActionCallTransformerOptions, ActionCallBindOptions, ActionCallCommitOptions, ActionHandlerOptions, ActionResolvedApi, } from "./core/types/action.js";
-export { ActionApiError, ActionHandlerError, ActionCommitError, ActionConcurrentError } from "./core/utils/error.js";
+export { ActionApiError, ActionHandlerError, ActionCommitError, ActionConcurrentError, isError, toError } from "./core/utils/error.js";
 export type { ComposeCallback, ComposeCall, ComposeDefinitions, ComposeContext, StoreCompose, } from "./core/types/compose.js";
 export { useStoreCompose } from "./composables/compose.js";
 export type { UseStoreCompose } from "./composables/compose.js";

package/dist/runtime/index.js

@@ -3,7 +3,7 @@ export { shape } from "./core/layers/shape.js";
 export { ModelType, ModelManyKind, ModelOneMode, ModelManyMode, ModelSilent } from "./core/types/model.js";
 export { ViewClone } from "./core/types/view.js";
 export { ActionStatus, ActionConcurrent, ActionType, ActionApiMethod } from "./core/types/action.js";
-export { ActionApiError, ActionHandlerError, ActionCommitError, ActionConcurrentError } from "./core/utils/error.js";
+export { ActionApiError, ActionHandlerError, ActionCommitError, ActionConcurrentError, isError, toError } from "./core/utils/error.js";
 export { useStoreCompose } from "./composables/compose.js";
 export { useIsolatedActionStatus, useIsolatedActionError, useStoreAction } from "./composables/action.js";
 export { useStoreModel } from "./composables/model.js";

package/package.json

@@ -1,72 +1,73 @@
 {
-  "name": "@diphyx/harlemify",
-  "version": "5.4.1",
-  "description": "API state management for Nuxt powered by Harlem",
-  "keywords": [
-    "nuxt",
-    "nuxt-module",
-    "harlem",
-    "state-management",
-    "api",
-    "zod",
-    "vue",
-    "typescript"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/diphyx/harlemify.git"
-  },
-  "homepage": "https://diphyx.github.io/harlemify/",
-  "bugs": {
-    "url": "https://github.com/diphyx/harlemify/issues"
-  },
-  "license": "MIT",
-  "author": "Amir Reza Dalir",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/types.d.ts",
-      "import": "./dist/module.mjs",
-      "require": "./dist/module.cjs"
+    "name": "@diphyx/harlemify",
+    "version": "6.0.0",
+    "description": "API state management for Nuxt powered by Harlem",
+    "keywords": [
+        "nuxt",
+        "nuxt-module",
+        "harlem",
+        "state-management",
+        "api",
+        "zod",
+        "vue",
+        "typescript"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/diphyx/harlemify.git"
     },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js"
+    "homepage": "https://diphyx.github.io/harlemify/",
+    "bugs": {
+        "url": "https://github.com/diphyx/harlemify/issues"
+    },
+    "license": "MIT",
+    "author": "Amir Reza Dalir",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/types.d.ts",
+            "import": "./dist/module.mjs",
+            "require": "./dist/module.cjs"
+        },
+        "./runtime": {
+            "types": "./dist/runtime/index.d.ts",
+            "import": "./dist/runtime/index.js"
+        }
+    },
+    "main": "./dist/module.cjs",
+    "module": "./dist/module.mjs",
+    "types": "./dist/types.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "cleanup": "pnpm nuxt cleanup && pnpm nuxt cleanup playground",
+        "prepare": "pnpm nuxt prepare && pnpm nuxt prepare playground",
+        "dev": "pnpm nuxt dev playground",
+        "build": "nuxt-module-build build",
+        "lint": "eslint . --fix",
+        "test": "vitest run",
+        "test:e2e": "playwright test"
+    },
+    "dependencies": {
+        "@harlem/core": "^3.1.8",
+        "@nuxt/kit": "^3.14.0 || ^4.0.0",
+        "consola": "^3.4.2",
+        "defu": "^6.1.4",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "@nuxt/eslint-config": "^0.6.2",
+        "@nuxt/module-builder": "^0.8.4",
+        "@nuxt/schema": "^4.3.1",
+        "@nuxt/test-utils": "^3.23.0",
+        "@playwright/test": "^1.58.2",
+        "@types/node": "^22.19.11",
+        "@vitest/coverage-v8": "^2.1.9",
+        "eslint": "^9.39.2",
+        "nuxt": "^4.3.1",
+        "typescript": "^5.9.3",
+        "vitest": "^2.1.9",
+        "vue": "^3.5.28"
     }
-  },
-  "main": "./dist/module.cjs",
-  "module": "./dist/module.mjs",
-  "types": "./dist/types.d.ts",
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "@harlem/core": "^3.1.8",
-    "@nuxt/kit": "^3.14.0 || ^4.0.0",
-    "consola": "^3.4.2",
-    "defu": "^6.1.4",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@nuxt/eslint-config": "^0.6.2",
-    "@nuxt/module-builder": "^0.8.4",
-    "@nuxt/schema": "^4.3.1",
-    "@nuxt/test-utils": "^3.23.0",
-    "@playwright/test": "^1.58.2",
-    "@types/node": "^22.19.11",
-    "@vitest/coverage-v8": "^2.1.9",
-    "eslint": "^9.39.2",
-    "nuxt": "^4.3.1",
-    "typescript": "^5.9.3",
-    "vitest": "^2.1.9",
-    "vue": "^3.5.28"
-  },
-  "scripts": {
-    "cleanup": "pnpm nuxt cleanup && pnpm nuxt cleanup playground",
-    "dev": "pnpm nuxt dev playground",
-    "build": "nuxt-module-build build",
-    "lint": "eslint . --fix",
-    "test": "vitest run",
-    "test:e2e": "playwright test"
-  }
-}
+}