@diphyx/harlemify 4.0.1 → 5.1.0

package/README.md

@@ -2,14 +2,16 @@
 
 > Factory-driven state management for Nuxt powered by [Harlem](https://harlemjs.com/)
 
-## Features
+Define your data **shape** once with Zod — get typed **models**, computed **views**, and async **actions** with a single `createStore` call.
 
-- **Shape-Driven** - Zod shapes define types and identifiers
-- **Three-Layer Architecture** - Model (state), View (computed), Action (async operations)
-- **Chainable Action Builders** - Fluent `api`, `handle`, `commit` chains
-- **Per-Action Status Tracking** - Built-in `loading`, `status`, `error`, `data` on every action
-- **Concurrency Control** - Block, skip, cancel, or allow concurrent calls
-- **SSR Support** - Server-side rendering with automatic hydration
+- **Schema-first** — Define your data shape once, get TypeScript types and validation automatically
+- **Reactive state** — Single items and collections with built-in mutations
+- **Computed views** — Derived read-only state that updates when models change
+- **API integration** — Declarative HTTP actions that fetch and commit data in one step
+- **Status tracking** — Every action exposes loading, error, and status reactively
+- **Concurrency control** — Block, skip, cancel, or allow parallel calls per action
+- **Vue composables** — Reactive helpers for actions, models, and views in components
+- **SSR ready** — Server-side rendering with automatic state hydration
 
 ## Install
 
@@ -17,37 +19,23 @@
 npm install @diphyx/harlemify
 ```
 
-## Setup
-
 ```typescript
 // nuxt.config.ts
 export default defineNuxtConfig({
     modules: ["@diphyx/harlemify"],
-    harlemify: {
-        action: {
-            endpoint: "https://api.example.com",
-        },
-    },
 });
 ```
 
 ## Usage
 
 ```typescript
-// stores/user.ts
-import { createStore, shape, ActionOneMode, ActionManyMode, type ShapeInfer } from "@diphyx/harlemify";
-
-const userShape = shape((factory) => {
-    return {
-        id: factory.number().meta({
-            identifier: true,
-        }),
-        name: factory.string(),
-        email: factory.email(),
-    };
-});
-
-export type User = ShapeInfer<typeof userShape>;
+const userShape = shape((factory) => ({
+    id: factory.number().meta({
+        identifier: true,
+    }),
+    name: factory.string(),
+    email: factory.email(),
+}));
 
 export const userStore = createStore({
     name: "users",
@@ -63,19 +51,17 @@ export const userStore = createStore({
             users: from("list"),
         };
     },
-    action({ api, commit }) {
+    action({ api }) {
         return {
-            list: api
-                .get({
-                    url: "/users",
-                })
-                .commit("list", ActionManyMode.SET),
-            create: api
-                .post({
+            list: api.get(
+                {
                     url: "/users",
-                })
-                .commit("list", ActionManyMode.ADD),
-            clear: commit("list", ActionManyMode.RESET),
+                },
+                {
+                    model: "list",
+                    mode: ModelManyMode.SET,
+                },
+            ),
         };
     },
 });
@@ -83,15 +69,15 @@ export const userStore = createStore({
 
 ```vue
 <script setup>
-const { view, action } = userStore;
+const { execute, loading } = useStoreAction(userStore, "list");
+const { data } = useStoreView(userStore, "users");
 
-await action.list();
+await execute();
 </script>
 
 <template>
-    <div v-if="action.list.loading.value">Loading...</div>
-    <ul v-else>
-        <li v-for="user in view.users.value" :key="user.id">{{ user.name }}</li>
+    <ul v-if="!loading">
+        <li v-for="user in data.value" :key="user.id">{{ user.name }}</li>
     </ul>
 </template>
 ```

package/dist/module.d.mts

@@ -4,7 +4,12 @@ interface RuntimeModelConfig {
     identifier?: string;
 }
 
+declare enum ViewClone {
+    SHALLOW = "shallow",
+    DEEP = "deep"
+}
 interface RuntimeViewConfig {
+    clone?: ViewClone;
 }
 
 interface RuntimeActionConfig {

package/dist/module.d.ts

@@ -4,7 +4,12 @@ interface RuntimeModelConfig {
     identifier?: string;
 }
 
+declare enum ViewClone {
+    SHALLOW = "shallow",
+    DEEP = "deep"
+}
 interface RuntimeViewConfig {
+    clone?: ViewClone;
 }
 
 interface RuntimeActionConfig {

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0 || >=4.0.0"
   },
-  "version": "4.0.1",
+  "version": "5.1.0",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "unknown"

package/dist/runtime/composables/action.d.ts

@@ -1,4 +1,17 @@
-import { type Ref } from "vue";
-import { type ActionError, ActionStatus } from "../core/types/action.js";
+import { type ComputedRef, type Ref } from "vue";
+import { ActionStatus, type ActionCall, type ActionCallOptions } from "../core/types/action.js";
+export interface UseStoreActionOptions {
+    isolated?: boolean;
+}
+export type UseStoreAction<T> = {
+    execute: (options?: ActionCallOptions) => Promise<T>;
+    error: Readonly<Ref<Error | null>>;
+    status: Readonly<Ref<ActionStatus>>;
+    loading: ComputedRef<boolean>;
+    reset: () => void;
+};
+export declare function useIsolatedActionError(): Ref<Error | null>;
 export declare function useIsolatedActionStatus(): Ref<ActionStatus>;
-export declare function useIsolatedActionError(): Ref<ActionError | null>;
+export declare function useStoreAction<A extends Record<string, ActionCall>, K extends keyof A & string, T = Awaited<ReturnType<A[K]>>>(store: {
+    action: A;
+}, key: K, options?: UseStoreActionOptions): UseStoreAction<T>;

package/dist/runtime/composables/action.js

@@ -1,8 +1,52 @@
-import { ref } from "vue";
+import { ref, computed } from "vue";
 import { ActionStatus } from "../core/types/action.js";
+export function useIsolatedActionError() {
+  return ref(null);
+}
 export function useIsolatedActionStatus() {
   return ref(ActionStatus.IDLE);
 }
-export function useIsolatedActionError() {
-  return ref(null);
+export function useStoreAction(store, key, options) {
+  const action = store.action[key];
+  if (!action) {
+    throw new Error(`Action "${key}" not found in store`);
+  }
+  let error;
+  let status;
+  let loading;
+  let reset;
+  if (options?.isolated) {
+    const isolatedError = useIsolatedActionError();
+    const isolatedStatus = useIsolatedActionStatus();
+    error = isolatedError;
+    status = isolatedStatus;
+    loading = computed(() => {
+      return isolatedStatus.value === ActionStatus.PENDING;
+    });
+    reset = () => {
+      isolatedStatus.value = ActionStatus.IDLE;
+      isolatedError.value = null;
+    };
+  } else {
+    error = action.error;
+    status = action.status;
+    loading = action.loading;
+    reset = action.reset;
+  }
+  function execute(callOptions = {}) {
+    if (options?.isolated) {
+      callOptions.bind = {
+        status,
+        error
+      };
+    }
+    return action(callOptions);
+  }
+  return {
+    execute,
+    error,
+    status,
+    loading,
+    reset
+  };
 }

package/dist/runtime/composables/model.d.ts

@@ -0,0 +1,22 @@
+import type { ModelCall, ModelOneCall, ModelManyCall, ModelOneCommit, ModelManyCommit, StoreModel, ModelDefinitions } from "../core/types/model.js";
+export interface UseStoreModelOptions {
+    debounce?: number;
+    throttle?: number;
+}
+type UseStoreModelOne<C extends ModelOneCommit<any>> = {
+    set: C["set"];
+    reset: C["reset"];
+    patch: C["patch"];
+};
+type UseStoreModelMany<C extends ModelManyCommit<any>> = {
+    set: C["set"];
+    reset: C["reset"];
+    patch: C["patch"];
+    add: C["add"];
+    remove: C["remove"];
+};
+export type UseStoreModel<M extends ModelCall<any> = ModelCall<any>> = M extends ModelManyCall<infer S> ? UseStoreModelMany<ModelManyCommit<S>> : M extends ModelOneCall<infer S> ? UseStoreModelOne<ModelOneCommit<S>> : never;
+export declare function useStoreModel<M extends StoreModel<ModelDefinitions>, K extends keyof M & string>(store: {
+    model: M;
+}, key: K, options?: UseStoreModelOptions): UseStoreModel<M[K]>;
+export {};

package/dist/runtime/composables/model.js

@@ -0,0 +1,32 @@
+import { debounce, throttle } from "../core/utils/base.js";
+function isMany(model) {
+  return "add" in model && typeof model.add === "function";
+}
+function wrapCommit(commit, options) {
+  if (options?.debounce) {
+    return debounce(commit, options.debounce);
+  }
+  if (options?.throttle) {
+    return throttle(commit, options.throttle);
+  }
+  return commit;
+}
+export function useStoreModel(store, key, options) {
+  const model = store.model[key];
+  if (!model) {
+    throw new Error(`Model "${key}" not found in store`);
+  }
+  let output = {
+    set: wrapCommit(model.set.bind(model), options),
+    reset: wrapCommit(model.reset.bind(model), options),
+    patch: wrapCommit(model.patch.bind(model), options)
+  };
+  if (isMany(model)) {
+    output = {
+      ...output,
+      add: wrapCommit(model.add.bind(model), options),
+      remove: wrapCommit(model.remove.bind(model), options)
+    };
+  }
+  return output;
+}

package/dist/runtime/composables/view.d.ts

@@ -0,0 +1,33 @@
+import { type ComputedRef, type WatchStopHandle } from "vue";
+import type { ViewCall } from "../core/types/view.js";
+export interface UseStoreViewTrackOptions {
+    deep?: boolean;
+    immediate?: boolean;
+    debounce?: number;
+    throttle?: number;
+}
+export interface UseStoreViewOptions<T> {
+    proxy?: boolean;
+    default?: T;
+}
+export type UseStoreViewData<T> = {
+    value: T;
+} & (T extends Record<string, unknown> ? {
+    [K in keyof T]: T[K];
+} : Record<string, unknown>);
+export type UseStoreViewProxy<T> = {
+    data: UseStoreViewData<T>;
+    track: (handler: (value: T) => void, options?: UseStoreViewTrackOptions) => WatchStopHandle;
+};
+export type UseStoreViewComputed<T> = {
+    data: ComputedRef<T>;
+    track: (handler: (value: T) => void, options?: UseStoreViewTrackOptions) => WatchStopHandle;
+};
+export declare function useStoreView<V extends Record<string, ViewCall>, K extends keyof V & string, T = V[K] extends ComputedRef<infer R> ? R : unknown>(store: {
+    view: V;
+}, key: K, options: UseStoreViewOptions<T> & {
+    proxy: false;
+}): UseStoreViewComputed<T>;
+export declare function useStoreView<V extends Record<string, ViewCall>, K extends keyof V & string, T = V[K] extends ComputedRef<infer R> ? R : unknown>(store: {
+    view: V;
+}, key: K, options?: UseStoreViewOptions<T>): UseStoreViewProxy<T>;

package/dist/runtime/composables/view.js

@@ -0,0 +1,54 @@
+import { computed, watch } from "vue";
+import { debounce, throttle, toReactiveProxy } from "../core/utils/base.js";
+function resolveDefault(view, defaultValue) {
+  if (defaultValue === void 0) {
+    return view;
+  }
+  return computed(() => {
+    const value = view.value;
+    if (value == null) {
+      return defaultValue;
+    }
+    return value;
+  });
+}
+function resolveData(source, proxy) {
+  if (proxy !== false) {
+    return toReactiveProxy(source);
+  }
+  return source;
+}
+export function useStoreView(store, key, options) {
+  if (!store.view[key]) {
+    throw new Error(`View "${key}" not found in store`);
+  }
+  const source = resolveDefault(store.view[key], options?.default);
+  const data = resolveData(source, options?.proxy);
+  function resolveCallback(callback, callbackOptions) {
+    if (callbackOptions?.debounce) {
+      return debounce(callback, callbackOptions.debounce);
+    }
+    if (callbackOptions?.throttle) {
+      return throttle(callback, callbackOptions.throttle);
+    }
+    return callback;
+  }
+  function track(handler, trackOptions) {
+    const callback = resolveCallback(handler, trackOptions);
+    const stop = watch(
+      source,
+      (value) => {
+        callback(value);
+      },
+      {
+        deep: trackOptions?.deep,
+        immediate: trackOptions?.immediate
+      }
+    );
+    return stop;
+  }
+  return {
+    data,
+    track
+  };
+}

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

@@ -1,4 +1,5 @@
 import type { ConsolaInstance } from "consola";
-import type { Model } from "../types/model.js";
+import type { ModelDefinitions } from "../types/model.js";
+import type { ViewDefinitions } from "../types/view.js";
 import { type RuntimeActionConfig, type ActionFactory } from "../types/action.js";
-export declare function createActionFactory<M extends Model, V>(config?: RuntimeActionConfig, logger?: ConsolaInstance, _model?: M, _view?: V): ActionFactory<M, V>;
+export declare function createActionFactory<MD extends ModelDefinitions, VD extends ViewDefinitions<MD>>(config?: RuntimeActionConfig, logger?: ConsolaInstance): ActionFactory<MD, VD>;

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

@@ -1,77 +1,46 @@
-import { buildCommitMethod } from "../utils/action.js";
 import {
-  ActionApiMethod,
-  DEFINITION
+  ActionApiMethod
 } from "../types/action.js";
-export function createActionFactory(config, logger, _model, _view) {
-  function apiCall(apiDefinition) {
-    apiDefinition = {
+export function createActionFactory(config, logger) {
+  function apiCall(request, commit) {
+    const mergedRequest = {
       endpoint: config?.endpoint,
       headers: config?.headers,
       query: config?.query,
       timeout: config?.timeout,
       concurrent: config?.concurrent,
-      ...apiDefinition
-    };
-    const actionDefinition = {
-      api: apiDefinition,
-      logger
+      ...request
     };
+    let key = "";
     return {
-      handle(callback) {
-        const handleDefinition = {
-          api: apiDefinition,
-          handle: callback,
-          logger
-        };
-        return {
-          commit: buildCommitMethod(handleDefinition),
-          get [DEFINITION]() {
-            return handleDefinition;
-          }
-        };
+      get key() {
+        return key;
+      },
+      setKey(value) {
+        key = value;
       },
-      commit: buildCommitMethod(actionDefinition),
-      get [DEFINITION]() {
-        return actionDefinition;
-      }
+      request: mergedRequest,
+      commit,
+      logger
     };
   }
-  function apiGet(definition) {
-    return apiCall({
-      ...definition,
-      method: ActionApiMethod.GET
-    });
+  function apiGet(request, commit) {
+    return apiCall({ ...request, method: ActionApiMethod.GET }, commit);
   }
-  function apiHead(definition) {
-    return apiCall({
-      ...definition,
-      method: ActionApiMethod.HEAD
-    });
+  function apiHead(request, commit) {
+    return apiCall({ ...request, method: ActionApiMethod.HEAD }, commit);
   }
-  function apiPost(definition) {
-    return apiCall({
-      ...definition,
-      method: ActionApiMethod.POST
-    });
+  function apiPost(request, commit) {
+    return apiCall({ ...request, method: ActionApiMethod.POST }, commit);
   }
-  function apiPut(definition) {
-    return apiCall({
-      ...definition,
-      method: ActionApiMethod.PUT
-    });
+  function apiPut(request, commit) {
+    return apiCall({ ...request, method: ActionApiMethod.PUT }, commit);
   }
-  function apiPatch(definition) {
-    return apiCall({
-      ...definition,
-      method: ActionApiMethod.PATCH
-    });
+  function apiPatch(request, commit) {
+    return apiCall({ ...request, method: ActionApiMethod.PATCH }, commit);
   }
-  function apiDelete(definition) {
-    return apiCall({
-      ...definition,
-      method: ActionApiMethod.DELETE
-    });
+  function apiDelete(request, commit) {
+    return apiCall({ ...request, method: ActionApiMethod.DELETE }, commit);
   }
   const api = Object.assign(apiCall, {
     get: apiGet,
@@ -81,22 +50,21 @@ export function createActionFactory(config, logger, _model, _view) {
     patch: apiPatch,
     delete: apiDelete
   });
-  function handle(callback) {
-    const definition = {
-      handle: callback,
-      logger
-    };
+  function handler(callback) {
+    let key = "";
     return {
-      commit: buildCommitMethod(definition),
-      get [DEFINITION]() {
-        return definition;
-      }
+      get key() {
+        return key;
+      },
+      setKey(value) {
+        key = value;
+      },
+      callback,
+      logger
     };
   }
-  const commit = buildCommitMethod({ logger });
   return {
     api,
-    handle,
-    commit
+    handler
   };
 }

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

@@ -3,7 +3,14 @@ import {
 } from "../types/model.js";
 export function createModelFactory(config, logger) {
   function one(shape, options) {
+    let key = "";
     return {
+      get key() {
+        return key;
+      },
+      setKey(value) {
+        key = value;
+      },
       shape,
       kind: ModelKind.OBJECT,
       options: {
@@ -14,7 +21,14 @@ export function createModelFactory(config, logger) {
     };
   }
   function many(shape, options) {
+    let key = "";
     return {
+      get key() {
+        return key;
+      },
+      setKey(value) {
+        key = value;
+      },
       shape,
       kind: ModelKind.ARRAY,
       options: {

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ShapeFactory } from "../types/shape.js";
+import type { ShapeFactory, ShapeRawDefinition } from "../types/shape.js";
 export declare const primitiveField: {
     string: typeof z.string;
     number: typeof z.number;
@@ -42,4 +42,4 @@ export declare const specialField: {
     nullable: typeof z.nullable;
     optional: typeof z.optional;
 };
-export declare function shape<T extends z.ZodRawShape>(definition: T | ((factory: ShapeFactory) => T)): z.ZodObject<T>;
+export declare function shape<T extends ShapeRawDefinition>(definition: T | ((factory: ShapeFactory) => T)): import("../types/shape").ShapeCall<T>;

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { createShape } from "../utils/shape.js";
 export const primitiveField = {
   string: z.string,
   number: z.number,
@@ -43,7 +44,7 @@ export const specialField = {
 };
 export function shape(definition) {
   if (typeof definition === "function") {
-    return z.object(
+    return createShape(
       definition({
         ...primitiveField,
         ...structureField,
@@ -52,5 +53,5 @@ export function shape(definition) {
       })
     );
   }
-  return z.object(definition);
+  return createShape(definition);
 }

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

@@ -1,4 +1,4 @@
 import type { ConsolaInstance } from "consola";
-import type { Model } from "../types/model.js";
+import type { ModelDefinitions } from "../types/model.js";
 import type { RuntimeViewConfig, ViewFactory } from "../types/view.js";
-export declare function createViewFactory<M extends Model>(config?: RuntimeViewConfig, logger?: ConsolaInstance, _model?: M): ViewFactory<M>;
+export declare function createViewFactory<MD extends ModelDefinitions>(config?: RuntimeViewConfig, logger?: ConsolaInstance): ViewFactory<MD>;

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

@@ -1,16 +1,38 @@
-export function createViewFactory(config, logger, _model) {
-  function from(source, resolver) {
+export function createViewFactory(config, logger) {
+  function from(model, resolver, options) {
+    let key = "";
     const definition = {
-      sources: [source],
+      get key() {
+        return key;
+      },
+      setKey(value) {
+        key = value;
+      },
+      model: [model],
       resolver,
+      options: {
+        clone: config?.clone,
+        ...options
+      },
       logger
     };
     return definition;
   }
-  function merge(sources, resolver) {
+  function merge(models, resolver, options) {
+    let key = "";
     return {
-      sources,
+      get key() {
+        return key;
+      },
+      setKey(value) {
+        key = value;
+      },
+      models,
       resolver,
+      options: {
+        clone: config?.clone,
+        ...options
+      },
       logger
     };
   }