@diphyx/harlemify 5.0.0 → 5.1.0

package/README.md

@@ -2,16 +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.
 
-- **Single Factory** - Define shape, model, view, and action in one `createStore` call — fully typed end to end
-- **Zod Shapes** - Schema-first design with built-in validation, type inference, and identifier metadata
-- **Reactive Models** - `one()` and `many()` state containers with `set`, `patch`, `add`, `remove`, `reset` mutations
-- **Computed Views** - Derive read-only state from models with `from()` and `merge()` — auto-tracked by Vue
-- **API & Handler Actions** - Declarative HTTP actions with auto-commit, or custom handlers with full model/view access
-- **Action Metadata** - Every action exposes `loading`, `status`, `error`, `data`, and `reset()` out of the box
-- **Concurrency Control** - Block, skip, cancel, or allow parallel calls per action
-- **SSR Ready** - Server-side rendering with automatic state 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
 
@@ -19,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, ModelManyMode, 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",
@@ -65,13 +51,17 @@ export const userStore = createStore({
             users: from("list"),
         };
     },
-    action({ api, handler }) {
+    action({ api }) {
         return {
-            list: api.get({ url: "/users" }, { model: "list", mode: ModelManyMode.SET }),
-            create: api.post({ url: "/users" }, { model: "list", mode: ModelManyMode.ADD }),
-            clear: handler(async ({ model }) => {
-                model.list.reset();
-            }),
+            list: api.get(
+                {
+                    url: "/users",
+                },
+                {
+                    model: "list",
+                    mode: ModelManyMode.SET,
+                },
+            ),
         };
     },
 });
@@ -79,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.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0 || >=4.0.0"
   },
-  "version": "5.0.0",
+  "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 { ActionStatus } from "../core/types/action.js";
-export declare function useIsolatedActionStatus(): Ref<ActionStatus>;
+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 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/types/action.d.ts

@@ -114,9 +114,8 @@ export interface ActionCallOptions {
 }
 export interface ActionCall<T = void> {
     (options?: ActionCallOptions): Promise<T>;
-    readonly loading: ComputedRef<boolean>;
-    readonly status: Readonly<Ref<ActionStatus>>;
     readonly error: Readonly<Ref<Error | null>>;
-    readonly data: DeepReadonly<T> | null;
+    readonly status: Readonly<Ref<ActionStatus>>;
+    readonly loading: ComputedRef<boolean>;
     reset: () => void;
 }

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

@@ -204,7 +204,6 @@ export function createAction(definition, model, view) {
   });
   let currentController = null;
   let abortController = null;
-  let globalData = null;
   const globalError = ref(null);
   const globalStatus = ref(ActionStatus.IDLE);
   const loading = computed(() => {
@@ -270,7 +269,6 @@ export function createAction(definition, model, view) {
         } else {
           data = await executeHandler(definition, model, view);
         }
-        globalData = data;
         activeStatus.value = ActionStatus.SUCCESS;
         definition.logger?.debug("Action success", {
           action: definition.key
@@ -288,22 +286,18 @@ export function createAction(definition, model, view) {
     return currentController;
   }
   const action = Object.assign(execute, {
-    get loading() {
-      return loading;
-    },
     get error() {
       return readonly(globalError);
     },
     get status() {
       return readonly(globalStatus);
     },
-    get data() {
-      return globalData;
+    get loading() {
+      return loading;
     },
     reset() {
       globalError.value = null;
       globalStatus.value = ActionStatus.IDLE;
-      globalData = null;
     }
   });
   return action;

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

@@ -1,4 +1,14 @@
 export declare function trimStart(value: string, char: string): string;
 export declare function trimEnd(value: string, char: string): string;
+export declare function isObject(value: unknown): value is object;
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 export declare function isEmptyRecord(record: Record<string, unknown> | undefined): record is undefined;
+type ReferenceProxy<T> = {
+    value: T;
+} & Record<string | symbol, unknown>;
+export declare function toReactiveProxy<T>(reference: {
+    value: T;
+}): ReferenceProxy<T>;
+export declare function debounce<T extends (...args: any[]) => any>(callback: T, delay: number): T;
+export declare function throttle<T extends (...args: any[]) => any>(callback: T, delay: number): T;
+export {};

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

@@ -4,8 +4,11 @@ export function trimStart(value, char) {
 export function trimEnd(value, char) {
   return value.replace(new RegExp(`${char}+$`), "");
 }
+export function isObject(value) {
+  return value != null && typeof value === "object";
+}
 export function isPlainObject(value) {
-  if (!value || typeof value !== "object") {
+  if (!isObject(value)) {
     return false;
   }
   if (Array.isArray(value)) {
@@ -22,3 +25,85 @@ export function isEmptyRecord(record) {
   }
   return false;
 }
+export function toReactiveProxy(reference) {
+  function get(_target, prop) {
+    if (prop === "value") {
+      return reference.value;
+    }
+    if (!isObject(reference.value)) {
+      return void 0;
+    }
+    return reference.value[prop];
+  }
+  function has(_target, prop) {
+    if (prop === "value") {
+      return true;
+    }
+    if (!isObject(reference.value)) {
+      return false;
+    }
+    return prop in reference.value;
+  }
+  function ownKeys() {
+    if (!isObject(reference.value)) {
+      return [];
+    }
+    return Reflect.ownKeys(reference.value);
+  }
+  function getOwnPropertyDescriptor(_target, prop) {
+    if (!isObject(reference.value) || !(prop in reference.value)) {
+      return void 0;
+    }
+    return {
+      configurable: true,
+      enumerable: true,
+      value: reference.value[prop]
+    };
+  }
+  return new Proxy(
+    {},
+    {
+      get,
+      has,
+      ownKeys,
+      getOwnPropertyDescriptor
+    }
+  );
+}
+export function debounce(callback, delay) {
+  let timer = null;
+  return (...args) => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      callback(...args);
+    }, delay);
+  };
+}
+export function throttle(callback, delay) {
+  let lastCall = 0;
+  let timer = null;
+  return (...args) => {
+    const now = Date.now();
+    const remaining = delay - (now - lastCall);
+    if (remaining <= 0) {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      lastCall = now;
+      callback(...args);
+      return;
+    }
+    if (timer) {
+      return;
+    }
+    timer = setTimeout(() => {
+      lastCall = Date.now();
+      timer = null;
+      callback(...args);
+    }, remaining);
+  };
+}

package/dist/runtime/index.d.ts

@@ -9,5 +9,10 @@ export type { ViewDefinitionOptions } from "./core/types/view.js";
 export { ActionStatus, ActionConcurrent, ActionApiMethod } from "./core/types/action.js";
 export type { ActionCall, ActionCallOptions, ActionCallTransformerOptions, ActionCallBindOptions, ActionCallCommitOptions, ActionResolvedApi, } from "./core/types/action.js";
 export { ActionApiError, ActionHandlerError, ActionCommitError, ActionConcurrentError } from "./core/utils/error.js";
-export { useIsolatedActionStatus, useIsolatedActionError } from "./composables/action.js";
+export { useIsolatedActionStatus, useIsolatedActionError, useStoreAction } from "./composables/action.js";
+export type { UseStoreActionOptions, UseStoreAction } from "./composables/action.js";
+export { useStoreModel } from "./composables/model.js";
+export type { UseStoreModelOptions, UseStoreModel } from "./composables/model.js";
+export { useStoreView } from "./composables/view.js";
+export type { UseStoreViewOptions, UseStoreViewProxy, UseStoreViewComputed, UseStoreViewData, UseStoreViewTrackOptions, } from "./composables/view.js";
 export type { RuntimeConfig } from "./config.js";

package/dist/runtime/index.js

@@ -4,4 +4,6 @@ export { ModelKind, ModelOneMode, ModelManyMode } from "./core/types/model.js";
 export { ViewClone } from "./core/types/view.js";
 export { ActionStatus, ActionConcurrent, ActionApiMethod } from "./core/types/action.js";
 export { ActionApiError, ActionHandlerError, ActionCommitError, ActionConcurrentError } from "./core/utils/error.js";
-export { useIsolatedActionStatus, useIsolatedActionError } from "./composables/action.js";
+export { useIsolatedActionStatus, useIsolatedActionError, useStoreAction } from "./composables/action.js";
+export { useStoreModel } from "./composables/model.js";
+export { useStoreView } from "./composables/view.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diphyx/harlemify",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "API state management for Nuxt powered by Harlem",
   "keywords": [
     "nuxt",