@diphyx/harlemify 3.0.0 → 4.0.1

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

@@ -0,0 +1,163 @@
+import type { ConsolaInstance } from "consola";
+import type { ComputedRef, DeepReadonly, MaybeRefOrGetter, Ref } from "vue";
+import type { Model, ModelShape, MutationsOneOptions, MutationsManyOptions } from "./model.js";
+export interface RuntimeActionConfig {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    timeout?: number;
+    concurrent?: ActionConcurrent;
+}
+export declare const DEFINITION: unique symbol;
+export declare const AUTO: unique symbol;
+export declare enum ActionOneMode {
+    SET = "set",
+    RESET = "reset",
+    PATCH = "patch"
+}
+export declare enum ActionManyMode {
+    SET = "set",
+    RESET = "reset",
+    PATCH = "patch",
+    REMOVE = "remove",
+    ADD = "add"
+}
+export declare enum ActionStatus {
+    IDLE = "idle",
+    PENDING = "pending",
+    SUCCESS = "success",
+    ERROR = "error"
+}
+export declare enum ActionConcurrent {
+    BLOCK = "block",
+    SKIP = "skip",
+    CANCEL = "cancel",
+    ALLOW = "allow"
+}
+export declare enum ActionApiMethod {
+    GET = "GET",
+    HEAD = "HEAD",
+    POST = "POST",
+    PUT = "PUT",
+    PATCH = "PATCH",
+    DELETE = "DELETE"
+}
+export interface ActionApiError extends Error {
+    name: "ActionApiError";
+    status?: number;
+    statusText?: string;
+    data?: unknown;
+}
+export interface ActionHandleError extends Error {
+    name: "ActionHandleError";
+    cause: Error;
+}
+export interface ActionCommitError extends Error {
+    name: "ActionCommitError";
+    cause: Error;
+}
+export interface ActionConcurrentError extends Error {
+    name: "ActionConcurrentError";
+}
+export type ActionError = ActionApiError | ActionHandleError | ActionCommitError | ActionConcurrentError;
+export type ActionApiValue<V, T> = MaybeRefOrGetter<T> | ((view: DeepReadonly<V>) => T);
+export interface ActionApiDefinition<V> {
+    endpoint?: string;
+    url: ActionApiValue<V, string>;
+    method: ActionApiMethod;
+    headers?: ActionApiValue<V, Record<string, string>>;
+    query?: ActionApiValue<V, Record<string, unknown>>;
+    body?: ActionApiValue<V, unknown>;
+    timeout?: number;
+    concurrent?: ActionConcurrent;
+}
+export type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+export type ActionCommitValue<M extends Model, K extends keyof M, Mode> = Mode extends ActionOneMode.SET ? ModelShape<M, K> : Mode extends ActionOneMode.PATCH ? DeepPartial<ModelShape<M, K>> : Mode extends ActionOneMode.RESET ? never : Mode extends ActionManyMode.SET ? ModelShape<M, K>[] : Mode extends ActionManyMode.PATCH ? DeepPartial<ModelShape<M, K>> | DeepPartial<ModelShape<M, K>>[] : Mode extends ActionManyMode.REMOVE ? ModelShape<M, K> | ModelShape<M, K>[] : Mode extends ActionManyMode.ADD ? ModelShape<M, K> | ModelShape<M, K>[] : Mode extends ActionManyMode.RESET ? never : never;
+export type ActionCommitter<M extends Model> = {
+    <K extends keyof M, Mode extends ActionOneMode>(model: K, mode: Mode, ...args: Mode extends ActionOneMode.RESET ? [] : [value: ActionCommitValue<M, K, Mode>, options?: MutationsOneOptions]): void;
+    <K extends keyof M, Mode extends ActionManyMode>(model: K, mode: Mode, ...args: Mode extends ActionManyMode.RESET ? [] : [value: ActionCommitValue<M, K, Mode>, options?: MutationsManyOptions]): void;
+};
+export interface ActionHandleContext<M extends Model, V, ApiResponse = unknown> {
+    api: <T = ApiResponse>() => Promise<T>;
+    view: DeepReadonly<V>;
+    commit: ActionCommitter<M>;
+}
+export interface ActionHandleContextNoApi<M extends Model, V> {
+    view: DeepReadonly<V>;
+    commit: ActionCommitter<M>;
+}
+export type ActionHandleCallback<M extends Model, V, R = void, ApiResponse = unknown> = (context: ActionHandleContext<M, V, ApiResponse>) => Promise<R>;
+export type ActionHandleCallbackNoApi<M extends Model, V, R = void> = (context: ActionHandleContextNoApi<M, V>) => Promise<R>;
+export type ActionHandleResolver<R = void> = (...args: unknown[]) => Promise<R>;
+export interface ActionDefinition<M extends Model, V, R = void> {
+    api?: ActionApiDefinition<V>;
+    handle?: ActionHandleCallback<M, V, R, unknown> | ActionHandleCallbackNoApi<M, V, R>;
+    commit?: {
+        model: keyof M;
+        mode: ActionOneMode | ActionManyMode;
+        value?: unknown;
+        options?: MutationsOneOptions | MutationsManyOptions;
+    };
+    logger?: ConsolaInstance;
+}
+export type ActionDefinitions<M extends Model, V> = Record<string, ActionDefinition<M, V, unknown>>;
+export interface ActionCommitMethod<M extends Model, V, R> {
+    <K extends keyof M, Mode extends ActionOneMode>(model: K, mode: Mode, ...args: Mode extends ActionOneMode.RESET ? [] : [value?: ActionCommitValue<M, K, Mode> | typeof AUTO, options?: MutationsOneOptions]): ActionCommitChain<M, V, R>;
+    <K extends keyof M, Mode extends ActionManyMode>(model: K, mode: Mode, ...args: Mode extends ActionManyMode.RESET ? [] : [value?: ActionCommitValue<M, K, Mode> | typeof AUTO, options?: MutationsManyOptions]): ActionCommitChain<M, V, R>;
+}
+export interface ActionApiChain<M extends Model, V, ApiResponse> {
+    handle<R>(callback: ActionHandleCallback<M, V, R, ApiResponse>): ActionHandleChain<M, V, R>;
+    commit: ActionCommitMethod<M, V, ApiResponse>;
+    readonly [DEFINITION]: ActionDefinition<M, V, ApiResponse>;
+}
+export interface ActionHandleChain<M extends Model, V, R> {
+    commit: ActionCommitMethod<M, V, R>;
+    readonly [DEFINITION]: ActionDefinition<M, V, R>;
+}
+export interface ActionCommitChain<M extends Model, V, R> {
+    readonly [DEFINITION]: ActionDefinition<M, V, R>;
+}
+export type ActionApiShortcutDefinition<V> = Omit<ActionApiDefinition<V>, "method">;
+export interface ActionApiFactory<M extends Model, V> {
+    <A>(definition: ActionApiDefinition<V>): ActionApiChain<M, V, A>;
+    get<A>(definition: ActionApiShortcutDefinition<V>): ActionApiChain<M, V, A>;
+    head<A>(definition: ActionApiShortcutDefinition<V>): ActionApiChain<M, V, A>;
+    post<A>(definition: ActionApiShortcutDefinition<V>): ActionApiChain<M, V, A>;
+    put<A>(definition: ActionApiShortcutDefinition<V>): ActionApiChain<M, V, A>;
+    patch<A>(definition: ActionApiShortcutDefinition<V>): ActionApiChain<M, V, A>;
+    delete<A>(definition: ActionApiShortcutDefinition<V>): ActionApiChain<M, V, A>;
+}
+export interface ActionFactory<M extends Model, V> {
+    api: ActionApiFactory<M, V>;
+    handle<R>(callback: ActionHandleCallbackNoApi<M, V, R>): ActionHandleChain<M, V, R>;
+    commit: ActionCommitMethod<M, V, void>;
+}
+export interface ActionCallBind {
+    status?: Ref<ActionStatus>;
+    error?: Ref<ActionError | null>;
+}
+export interface ActionCallCommit {
+    mode?: ActionOneMode | ActionManyMode;
+}
+export interface ActionCallPayload<V, T = unknown, R = T> {
+    headers?: Record<string, string> | ((view: DeepReadonly<V>) => Record<string, string>);
+    query?: Record<string, unknown> | ((view: DeepReadonly<V>) => Record<string, unknown>);
+    body?: unknown | ((view: DeepReadonly<V>) => unknown);
+    timeout?: number;
+    signal?: AbortSignal;
+    transformer?: (response: T) => R;
+    concurrent?: ActionConcurrent;
+    bind?: ActionCallBind;
+    commit?: ActionCallCommit;
+}
+export interface Action<V, T = void> {
+    (payload?: ActionCallPayload<V, T>): Promise<T>;
+    <R>(payload: ActionCallPayload<V, T, R>): Promise<R>;
+    readonly loading: ComputedRef<boolean>;
+    readonly status: Readonly<Ref<ActionStatus>>;
+    readonly error: Readonly<Ref<ActionError | null>>;
+    readonly data: DeepReadonly<T> | null;
+    reset: () => void;
+}

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

@@ -0,0 +1,39 @@
+export const DEFINITION = Symbol("definition");
+export const AUTO = Symbol("auto");
+export var ActionOneMode = /* @__PURE__ */ ((ActionOneMode2) => {
+  ActionOneMode2["SET"] = "set";
+  ActionOneMode2["RESET"] = "reset";
+  ActionOneMode2["PATCH"] = "patch";
+  return ActionOneMode2;
+})(ActionOneMode || {});
+export var ActionManyMode = /* @__PURE__ */ ((ActionManyMode2) => {
+  ActionManyMode2["SET"] = "set";
+  ActionManyMode2["RESET"] = "reset";
+  ActionManyMode2["PATCH"] = "patch";
+  ActionManyMode2["REMOVE"] = "remove";
+  ActionManyMode2["ADD"] = "add";
+  return ActionManyMode2;
+})(ActionManyMode || {});
+export var ActionStatus = /* @__PURE__ */ ((ActionStatus2) => {
+  ActionStatus2["IDLE"] = "idle";
+  ActionStatus2["PENDING"] = "pending";
+  ActionStatus2["SUCCESS"] = "success";
+  ActionStatus2["ERROR"] = "error";
+  return ActionStatus2;
+})(ActionStatus || {});
+export var ActionConcurrent = /* @__PURE__ */ ((ActionConcurrent2) => {
+  ActionConcurrent2["BLOCK"] = "block";
+  ActionConcurrent2["SKIP"] = "skip";
+  ActionConcurrent2["CANCEL"] = "cancel";
+  ActionConcurrent2["ALLOW"] = "allow";
+  return ActionConcurrent2;
+})(ActionConcurrent || {});
+export var ActionApiMethod = /* @__PURE__ */ ((ActionApiMethod2) => {
+  ActionApiMethod2["GET"] = "GET";
+  ActionApiMethod2["HEAD"] = "HEAD";
+  ActionApiMethod2["POST"] = "POST";
+  ActionApiMethod2["PUT"] = "PUT";
+  ActionApiMethod2["PATCH"] = "PATCH";
+  ActionApiMethod2["DELETE"] = "DELETE";
+  return ActionApiMethod2;
+})(ActionApiMethod || {});

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

@@ -0,0 +1,70 @@
+import type { ConsolaInstance } from "consola";
+import type { Shape, ShapeType } from "./shape.js";
+export interface RuntimeModelConfig {
+    identifier?: string;
+}
+export declare enum ModelKind {
+    OBJECT = "object",
+    ARRAY = "array"
+}
+export interface ModelOneOptions<S extends Shape> {
+    identifier?: keyof S;
+    default?: S;
+}
+export interface ModelManyOptions<S extends Shape> {
+    identifier?: keyof S;
+    default?: S[];
+}
+export interface ModelOneDefinition<S extends Shape> {
+    shape: ShapeType<S>;
+    kind: ModelKind.OBJECT;
+    options?: ModelOneOptions<S>;
+    logger?: ConsolaInstance;
+}
+export interface ModelManyDefinition<S extends Shape> {
+    shape: ShapeType<S>;
+    kind: ModelKind.ARRAY;
+    options?: ModelManyOptions<S>;
+    logger?: ConsolaInstance;
+}
+export type ModelDefinition<S extends Shape> = ModelOneDefinition<S> | ModelManyDefinition<S>;
+export type Model = Record<string, ModelDefinition<any>>;
+export type ModelInstance<M extends Model, K extends keyof M> = M[K] extends ModelOneDefinition<infer S> ? S | null : M[K] extends ModelManyDefinition<infer S> ? S[] : never;
+export type ModelShape<M extends Model, K extends keyof M> = M[K] extends ModelDefinition<infer S> ? S : never;
+export type ModelOneKey<M extends Model> = {
+    [K in keyof M]: M[K] extends ModelOneDefinition<infer _S> ? K : never;
+}[keyof M];
+export type ModelManyKey<M extends Model> = {
+    [K in keyof M]: M[K] extends ModelManyDefinition<infer _S> ? K : never;
+}[keyof M];
+export type ModelStateOf<M extends Model> = {
+    [K in keyof M]: ModelInstance<M, K>;
+};
+export interface ModelFactory {
+    one<S extends Shape>(shape: ShapeType<S>, options?: ModelOneOptions<S>): ModelOneDefinition<S>;
+    many<S extends Shape>(shape: ShapeType<S>, options?: ModelManyOptions<S>): ModelManyDefinition<S>;
+}
+export interface MutationsOneOptions {
+    deep?: boolean;
+}
+export interface MutationsManyOptions {
+    by?: string;
+    prepend?: boolean;
+    unique?: boolean;
+    deep?: boolean;
+}
+export interface MutationsOne<S extends Shape> {
+    set: (value: S) => void;
+    reset: () => void;
+    patch: (value: Partial<S>, options?: MutationsOneOptions) => void;
+}
+export interface MutationsMany<S extends Shape> {
+    set: (value: S[]) => void;
+    reset: () => void;
+    patch: (value: Partial<S> | Partial<S>[], options?: MutationsManyOptions) => void;
+    remove: (value: S | S[], options?: MutationsManyOptions) => void;
+    add: (value: S | S[], options?: MutationsManyOptions) => void;
+}
+export type Mutations<M extends Model> = {
+    [K in keyof M]: M[K] extends ModelOneDefinition<infer S> ? MutationsOne<S> : M[K] extends ModelManyDefinition<infer S> ? MutationsMany<S> : never;
+};

package/dist/runtime/core/types/model.js

@@ -0,0 +1,5 @@
+export var ModelKind = /* @__PURE__ */ ((ModelKind2) => {
+  ModelKind2["OBJECT"] = "object";
+  ModelKind2["ARRAY"] = "array";
+  return ModelKind2;
+})(ModelKind || {});

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

@@ -0,0 +1,46 @@
+import type { z } from "zod";
+export type ShapeDefinition = z.ZodObject<z.ZodRawShape>;
+export type ShapeType<S> = z.ZodType<S>;
+export type ShapeInfer<T extends z.ZodType<any>> = z.infer<T>;
+export type Shape = Record<string, unknown>;
+export interface ShapeMeta {
+    identifier?: string;
+    defaults: Record<string, unknown>;
+    fields: string[];
+}
+export interface ShapeFactory {
+    string: typeof z.string;
+    number: typeof z.number;
+    boolean: typeof z.boolean;
+    bigint: typeof z.bigint;
+    date: typeof z.date;
+    object: typeof z.object;
+    array: typeof z.array;
+    tuple: typeof z.tuple;
+    record: typeof z.record;
+    map: typeof z.map;
+    set: typeof z.set;
+    enum: typeof z.enum;
+    union: typeof z.union;
+    literal: typeof z.literal;
+    email: typeof z.email;
+    url: typeof z.url;
+    uuid: typeof z.uuid;
+    cuid: typeof z.cuid;
+    cuid2: typeof z.cuid2;
+    ulid: typeof z.ulid;
+    nanoid: typeof z.nanoid;
+    jwt: typeof z.jwt;
+    emoji: typeof z.emoji;
+    ipv4: typeof z.ipv4;
+    ipv6: typeof z.ipv6;
+    mac: typeof z.mac;
+    base64: typeof z.base64;
+    base64url: typeof z.base64url;
+    hex: typeof z.hex;
+    any: typeof z.any;
+    unknown: typeof z.unknown;
+    never: typeof z.never;
+    nullable: typeof z.nullable;
+    optional: typeof z.optional;
+}

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

@@ -0,0 +1,29 @@
+import type { ConsolaInstance } from "consola";
+import type { Model, ModelInstance } from "./model.js";
+export interface RuntimeViewConfig {
+}
+export type ViewFromResolver<M extends Model, K extends keyof M, R> = (model: ModelInstance<M, K>) => R;
+export type ModelInstanceTuple<M extends Model, K extends readonly (keyof M)[]> = {
+    [I in keyof K]: K[I] extends keyof M ? ModelInstance<M, K[I]> : never;
+};
+export type ViewMergeResolver<M extends Model, K extends readonly (keyof M)[], R> = (...values: [...ModelInstanceTuple<M, K>]) => R;
+export interface ViewFromDefinition<M extends Model, K extends keyof M, R = ModelInstance<M, K>> {
+    sources: readonly [K];
+    resolver?: ViewFromResolver<M, K, R>;
+    logger?: ConsolaInstance;
+}
+export interface ViewMergeDefinition<M extends Model, K extends readonly (keyof M)[], R> {
+    sources: K;
+    resolver: ViewMergeResolver<M, K, R>;
+    logger?: ConsolaInstance;
+}
+export type ViewDefinition<M extends Model> = ViewFromDefinition<M, keyof M, unknown> | ViewMergeDefinition<M, readonly (keyof M)[], unknown>;
+export type ViewDefinitions<M extends Model> = Record<string, ViewDefinition<M>>;
+export type ViewResult<M extends Model, VD extends ViewDefinition<M>> = VD extends ViewFromDefinition<M, infer _K, infer R> ? R : VD extends ViewMergeDefinition<M, infer _K, infer R> ? R : never;
+export interface ViewFactory<M extends Model> {
+    from<K extends keyof M>(source: K): ViewFromDefinition<M, K, ModelInstance<M, K>>;
+    from<K extends keyof M, R>(source: K, resolver: ViewFromResolver<M, K, R>): ViewFromDefinition<M, K, R>;
+    merge<K1 extends keyof M, K2 extends keyof M, R>(sources: readonly [K1, K2], resolver: (v1: ModelInstance<M, K1>, v2: ModelInstance<M, K2>) => R): ViewMergeDefinition<M, readonly [K1, K2], R>;
+    merge<K1 extends keyof M, K2 extends keyof M, K3 extends keyof M, R>(sources: readonly [K1, K2, K3], resolver: (v1: ModelInstance<M, K1>, v2: ModelInstance<M, K2>, v3: ModelInstance<M, K3>) => R): ViewMergeDefinition<M, readonly [K1, K2, K3], R>;
+    merge<K extends readonly (keyof M)[], R>(sources: K, resolver: ViewMergeResolver<M, K, R>): ViewMergeDefinition<M, K, R>;
+}

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

@@ -0,0 +1,4 @@
+import { type Action, type ActionCommitMethod, type ActionDefinition } from "../types/action.js";
+import type { Model, Mutations } from "../types/model.js";
+export declare function buildCommitMethod<M extends Model, V, R>(definition: ActionDefinition<M, V, R>): ActionCommitMethod<M, V, R>;
+export declare function createAction<M extends Model, V, R>(definition: ActionDefinition<M, V, R>, mutations: Mutations<M>, view: V, key: string): Action<V, R>;

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

@@ -0,0 +1,294 @@
+import { defu } from "defu";
+import { ref, computed, readonly, toValue, nextTick } from "vue";
+import {
+  ActionApiMethod,
+  ActionStatus,
+  ActionConcurrent,
+  DEFINITION
+} from "../types/action.js";
+import { createCommitter, executeCommit } from "./model.js";
+class ApiError extends Error {
+  name = "ActionApiError";
+  constructor(message, options) {
+    super(message);
+    this.status = options?.status;
+    this.statusText = options?.statusText;
+    this.data = options?.data;
+  }
+}
+class HandleError extends Error {
+  name = "ActionHandleError";
+  constructor(cause) {
+    super(cause.message);
+    this.cause = cause;
+  }
+}
+class CommitError extends Error {
+  name = "ActionCommitError";
+  constructor(cause) {
+    super(cause.message);
+    this.cause = cause;
+  }
+}
+class ConcurrentError extends Error {
+  name = "ActionConcurrentError";
+  constructor() {
+    super("Action is already pending");
+  }
+}
+function createApiError(message, options) {
+  return new ApiError(message, options);
+}
+function createHandleError(cause) {
+  return new HandleError(cause);
+}
+function createCommitError(cause) {
+  return new CommitError(cause);
+}
+function createConcurrentError() {
+  return new ConcurrentError();
+}
+export function buildCommitMethod(definition) {
+  function commit(model, mode, value, options) {
+    return {
+      [DEFINITION]: {
+        ...definition,
+        commit: {
+          model,
+          mode,
+          value,
+          options
+        }
+      }
+    };
+  }
+  return commit;
+}
+function resolveApiValue(value, view, fallback) {
+  if (typeof value === "function") {
+    const handler = value;
+    return handler(view) || fallback;
+  }
+  return toValue(value) || fallback;
+}
+function resolveApiUrl(definition, view) {
+  const endpoint = (definition.endpoint ?? "").replace(/\/+$/, "");
+  const path = resolveApiValue(definition.url, view);
+  if (endpoint) {
+    return `${endpoint}/${path.replace(/^\/+/, "")}`;
+  }
+  return path;
+}
+function resolveApiHeaders(definition, view, payload) {
+  const initial = resolveApiValue(definition.headers, view, {});
+  const custom = resolveApiValue(payload?.headers, view, {});
+  return defu(custom, initial);
+}
+function resolveApiQuery(definition, view, payload) {
+  const initial = resolveApiValue(definition.query, view, {});
+  const custom = resolveApiValue(payload?.query, view, {});
+  return defu(custom, initial);
+}
+function resolveApiBody(definition, view, payload) {
+  if (definition.method === ActionApiMethod.GET || definition.method === ActionApiMethod.HEAD) {
+    return void 0;
+  }
+  const initial = resolveApiValue(definition.body, view, {});
+  const custom = resolveApiValue(payload?.body, view, {});
+  return defu(custom, initial);
+}
+export function createAction(definition, mutations, view, key) {
+  const globalError = ref(null);
+  const globalStatus = ref(ActionStatus.IDLE);
+  const loading = computed(() => {
+    return globalStatus.value === ActionStatus.PENDING;
+  });
+  let data = null;
+  let currentController = null;
+  let abortController = null;
+  async function execute(payload) {
+    await nextTick();
+    if (loading.value) {
+      const concurrent = payload?.concurrent ?? definition.api?.concurrent ?? ActionConcurrent.BLOCK;
+      switch (concurrent) {
+        case ActionConcurrent.BLOCK: {
+          definition.logger?.error("Action blocked by concurrent guard", {
+            action: key
+          });
+          throw createConcurrentError();
+        }
+        case ActionConcurrent.SKIP: {
+          definition.logger?.warn("Action skipped by concurrent guard", {
+            action: key
+          });
+          return currentController;
+        }
+        case ActionConcurrent.CANCEL: {
+          definition.logger?.warn("Action cancelling previous execution", {
+            action: key
+          });
+          abortController?.abort();
+        }
+      }
+    }
+    abortController = new AbortController();
+    const activeStatus = payload?.bind?.status ?? globalStatus;
+    const activeError = payload?.bind?.error ?? globalError;
+    activeStatus.value = ActionStatus.PENDING;
+    activeError.value = null;
+    currentController = (async () => {
+      try {
+        let result;
+        const committer = createCommitter(mutations);
+        if (definition.api) {
+          let response;
+          try {
+            const apiPayload = {
+              ...payload,
+              signal: payload?.signal ?? abortController.signal
+            };
+            const url = resolveApiUrl(definition.api, view);
+            definition.logger?.debug("Action API request", {
+              action: key,
+              method: definition.api.method,
+              url
+            });
+            response = await $fetch(url, {
+              method: definition.api.method,
+              headers: resolveApiHeaders(definition.api, view, apiPayload),
+              query: resolveApiQuery(definition.api, view, apiPayload),
+              body: resolveApiBody(definition.api, view, apiPayload),
+              timeout: apiPayload?.timeout ?? definition.api.timeout,
+              signal: apiPayload?.signal
+            });
+            definition.logger?.debug("Action API response received", {
+              action: key,
+              method: definition.api.method,
+              url
+            });
+          } catch (error) {
+            const errorMessage = error?.message ?? "API request failed";
+            const errorOptions = {
+              status: error?.status ?? error?.response?.status,
+              statusText: error?.statusText ?? error?.response?.statusText,
+              data: error?.data ?? error?.response?._data
+            };
+            definition.logger?.error("Action API error", {
+              action: key,
+              error: errorMessage
+            });
+            throw createApiError(errorMessage, errorOptions);
+          }
+          if (definition.handle) {
+            const handler = definition.handle;
+            try {
+              definition.logger?.debug("Action handle phase", {
+                action: key
+              });
+              result = await handler({
+                view,
+                commit: committer,
+                async api() {
+                  return response;
+                }
+              });
+            } catch (handleError) {
+              if (handleError instanceof ApiError || handleError instanceof HandleError) {
+                throw handleError;
+              }
+              definition.logger?.error("Action handle error", {
+                action: key,
+                error: handleError?.message
+              });
+              throw createHandleError(handleError);
+            }
+          } else {
+            result = response;
+          }
+        } else if (definition.handle) {
+          const handler = definition.handle;
+          try {
+            definition.logger?.debug("Action handle phase", {
+              action: key
+            });
+            result = await handler({
+              view,
+              commit: committer
+            });
+          } catch (handleError) {
+            if (handleError instanceof HandleError) {
+              throw handleError;
+            }
+            definition.logger?.error("Action handle error", {
+              action: key,
+              error: handleError?.message
+            });
+            throw createHandleError(handleError);
+          }
+        } else {
+          result = void 0;
+        }
+        if (payload?.transformer) {
+          result = payload.transformer(result);
+        }
+        if (definition.commit) {
+          try {
+            definition.logger?.debug("Action commit phase", {
+              action: key,
+              model: definition.commit.model,
+              mode: definition.commit.mode
+            });
+            executeCommit(
+              {
+                ...definition.commit,
+                mode: payload?.commit?.mode ?? definition.commit.mode
+              },
+              mutations,
+              result
+            );
+          } catch (commitError) {
+            definition.logger?.error("Action commit error", {
+              action: key,
+              error: commitError?.message
+            });
+            throw createCommitError(commitError);
+          }
+        }
+        data = result;
+        activeStatus.value = ActionStatus.SUCCESS;
+        definition.logger?.debug("Action success", {
+          action: key
+        });
+        return result;
+      } catch (actionError) {
+        activeError.value = actionError;
+        activeStatus.value = ActionStatus.ERROR;
+        throw actionError;
+      } finally {
+        currentController = null;
+        abortController = null;
+      }
+    })();
+    return currentController;
+  }
+  const action = Object.assign(execute, {
+    get loading() {
+      return loading;
+    },
+    get error() {
+      return readonly(globalError);
+    },
+    get status() {
+      return readonly(globalStatus);
+    },
+    get data() {
+      return data;
+    },
+    reset() {
+      globalError.value = null;
+      globalStatus.value = ActionStatus.IDLE;
+      data = null;
+    }
+  });
+  return action;
+}

package/dist/runtime/core/utils/model.d.ts

@@ -0,0 +1,12 @@
+import type { Store as SourceStore, BaseState } from "@harlem/core";
+import { type Model, type ModelStateOf, type MutationsOneOptions, type MutationsManyOptions, type Mutations } from "../types/model.js";
+import { type ActionCommitter, ActionOneMode, ActionManyMode } from "../types/action.js";
+export declare function initializeState<M extends Model>(model: M): ModelStateOf<M>;
+export declare function createMutations<M extends Model>(source: SourceStore<BaseState>, model: M): Mutations<M>;
+export declare function executeCommit<M extends Model>(definition: {
+    model: keyof M;
+    mode: ActionOneMode | ActionManyMode;
+    value?: unknown;
+    options?: MutationsOneOptions | MutationsManyOptions;
+}, mutations: Mutations<M>, result?: unknown): void;
+export declare function createCommitter<M extends Model>(mutations: Mutations<M>): ActionCommitter<M>;