@diphyx/harlemify 2.0.0 → 4.0.0

package/README.md

@@ -1,159 +1,104 @@
 # Harlemify
 
-> Schema-driven state management for Nuxt powered by [Harlem](https://harlemjs.com/)
-
-![Harlemify](https://raw.githubusercontent.com/diphyx/harlemify/main/docs/_media/icon.svg)
-
-Define your data schema once with Zod, and Harlemify handles the rest: type-safe API calls, reactive state, request monitoring, and automatic memory management. Your schema becomes the single source of truth for types, validation, and API payloads.
+> Factory-driven state management for Nuxt powered by [Harlem](https://harlemjs.com/)
 
 ## Features
 
-- **Schema-Driven** - Zod schema defines types, validation, and API payloads
-- **Custom Adapters** - Pluggable HTTP adapters for custom request handling
-- **Reactive Memory** - Unit and collection caching with Vue reactivity
-- **Request Monitoring** - Track pending, success, and failed states
-- **SSR Support** - Server-side rendering via Harlem SSR plugin
+- **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
 
-## Installation
+## Install
 
 ```bash
 npm install @diphyx/harlemify
 ```
 
-## Quick Start
+## Setup
 
 ```typescript
 // nuxt.config.ts
 export default defineNuxtConfig({
     modules: ["@diphyx/harlemify"],
     harlemify: {
-        api: {
-            adapter: {
-                baseURL: "https://api.example.com",
-                timeout: 10000,
-            },
+        action: {
+            endpoint: "https://api.example.com",
         },
     },
 });
 ```
 
-```typescript
-// stores/user.ts
-import { z } from "zod";
-import { createStore, Endpoint, EndpointMethod } from "@diphyx/harlemify";
-
-const UserSchema = z.object({
-    id: z.number().meta({ indicator: true }),
-    name: z.string().meta({
-        methods: [EndpointMethod.POST, EndpointMethod.PATCH],
-    }),
-});
-
-export type User = z.infer<typeof UserSchema>;
-
-export const userStore = createStore("user", UserSchema, {
-    [Endpoint.GET_UNITS]: { method: EndpointMethod.GET, url: "/users" },
-    [Endpoint.POST_UNITS]: { method: EndpointMethod.POST, url: "/users" },
-    [Endpoint.PATCH_UNITS]: { method: EndpointMethod.PATCH, url: (p) => `/users/${p.id}` },
-    [Endpoint.DELETE_UNITS]: { method: EndpointMethod.DELETE, url: (p) => `/users/${p.id}` },
-});
-```
-
-## Custom Adapters
-
-Harlemify supports custom HTTP adapters for advanced use cases like streaming responses, file uploads with progress, or custom authentication.
-
-### Adapter Hierarchy
-
-Adapters are resolved in the following order (highest to lowest priority):
-
-1. **Endpoint adapter** - Per-endpoint custom adapter
-2. **Store adapter** - Store-level adapter option
-3. **Module adapter** - Global config in `nuxt.config.ts`
-4. **Default adapter** - Built-in fetch adapter
-
-### Built-in Adapter
-
-Use `defineApiAdapter` to create an adapter with custom options:
+## Usage
 
 ```typescript
-import { defineApiAdapter } from "@diphyx/harlemify";
-
-const customAdapter = defineApiAdapter({
-    baseURL: "/api",
-    timeout: 5000,
-    retry: 3,
-    retryDelay: 1000,
-    retryStatusCodes: [500, 502, 503],
+// 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(),
+    };
 });
-```
-
-### Custom Adapter
-
-Create a fully custom adapter for advanced scenarios:
-
-```typescript
-import type { ApiAdapter, ApiAdapterRequest } from "@diphyx/harlemify";
-
-const streamingAdapter: ApiAdapter<MyType> = async (request: ApiAdapterRequest) => {
-    // Custom fetch logic with streaming, progress, etc.
-    const response = await fetch(request.url, {
-        method: request.method,
-        headers: request.headers,
-        body: JSON.stringify(request.body),
-    });
-
-    const data = await response.json();
-    return { data, status: response.status };
-};
-```
-
-### Using Adapters
 
-**Store-level adapter:**
+export type User = ShapeInfer<typeof userShape>;
 
-```typescript
-export const userStore = createStore(
-    "user",
-    UserSchema,
-    {
-        [Endpoint.GET_UNITS]: { method: EndpointMethod.GET, url: "/users" },
-    },
-    {
-        adapter: customAdapter, // Used for all endpoints in this store
+export const userStore = createStore({
+    name: "users",
+    model({ one, many }) {
+        return {
+            current: one(userShape),
+            list: many(userShape),
+        };
     },
-);
-```
-
-**Endpoint-level adapter:**
-
-```typescript
-export const userStore = createStore("user", UserSchema, {
-    [Endpoint.GET_UNIT]: {
-        method: EndpointMethod.GET,
-        url: (p) => `/users/${p.id}`,
-        adapter: detailAdapter, // Custom adapter for this endpoint only
+    view({ from }) {
+        return {
+            user: from("current"),
+            users: from("list"),
+        };
     },
-    [Endpoint.GET_UNITS]: {
-        method: EndpointMethod.GET,
-        url: "/users",
-        // Uses store or global adapter
+    action({ api, commit }) {
+        return {
+            list: api
+                .get({
+                    url: "/users",
+                })
+                .commit("list", ActionManyMode.SET),
+            create: api
+                .post({
+                    url: "/users",
+                })
+                .commit("list", ActionManyMode.ADD),
+            clear: commit("list", ActionManyMode.RESET),
+        };
     },
 });
 ```
 
-## Why Harlemify?
+```vue
+<script setup>
+const { view, action } = userStore;
 
-|                 |                                                   |
-| --------------- | ------------------------------------------------- |
-| **Type-Safe**   | Full TypeScript support with Zod schema inference |
-| **Declarative** | Define schema once, derive everything else        |
-| **Reactive**    | Powered by Vue's reactivity through Harlem        |
-| **Extensible**  | Custom adapters for any HTTP requirement          |
+await action.list();
+</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>
+</template>
+```
 
 ## Documentation
 
-Full documentation available at [https://diphyx.github.io/harlemify/](https://diphyx.github.io/harlemify/)
+[https://diphyx.github.io/harlemify/](https://diphyx.github.io/harlemify/)
 
 ## License
 

package/dist/module.d.mts

@@ -1,22 +1,33 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
-interface ApiFetchAdapterOptions {
-    baseURL?: string;
+interface RuntimeModelConfig {
+    identifier?: string;
+}
+
+interface RuntimeViewConfig {
+}
+
+interface RuntimeActionConfig {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
     timeout?: number;
-    retry?: number | false;
-    retryDelay?: number;
-    retryStatusCodes?: number[];
-    responseType?: "json" | "text" | "blob" | "arrayBuffer";
+    concurrent?: ActionConcurrent;
+}
+declare enum ActionConcurrent {
+    BLOCK = "block",
+    SKIP = "skip",
+    CANCEL = "cancel",
+    ALLOW = "allow"
 }
 
-type SharedConfig = {
-    api?: {
-        headers?: Record<string, string>;
-        query?: Record<string, unknown>;
-        adapter?: ApiFetchAdapterOptions;
-    };
+type RuntimeConfig = {
+    model?: RuntimeModelConfig;
+    view?: RuntimeViewConfig;
+    action?: RuntimeActionConfig;
+    logger?: number;
 };
 
-declare const _default: _nuxt_schema.NuxtModule<SharedConfig, SharedConfig, false>;
+declare const _default: _nuxt_schema.NuxtModule<RuntimeConfig, RuntimeConfig, false>;
 
 export { _default as default };

package/dist/module.d.ts

@@ -1,22 +1,33 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
-interface ApiFetchAdapterOptions {
-    baseURL?: string;
+interface RuntimeModelConfig {
+    identifier?: string;
+}
+
+interface RuntimeViewConfig {
+}
+
+interface RuntimeActionConfig {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
     timeout?: number;
-    retry?: number | false;
-    retryDelay?: number;
-    retryStatusCodes?: number[];
-    responseType?: "json" | "text" | "blob" | "arrayBuffer";
+    concurrent?: ActionConcurrent;
+}
+declare enum ActionConcurrent {
+    BLOCK = "block",
+    SKIP = "skip",
+    CANCEL = "cancel",
+    ALLOW = "allow"
 }
 
-type SharedConfig = {
-    api?: {
-        headers?: Record<string, string>;
-        query?: Record<string, unknown>;
-        adapter?: ApiFetchAdapterOptions;
-    };
+type RuntimeConfig = {
+    model?: RuntimeModelConfig;
+    view?: RuntimeViewConfig;
+    action?: RuntimeActionConfig;
+    logger?: number;
 };
 
-declare const _default: _nuxt_schema.NuxtModule<SharedConfig, SharedConfig, false>;
+declare const _default: _nuxt_schema.NuxtModule<RuntimeConfig, RuntimeConfig, false>;
 
 export { _default as default };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, addTemplate, addPlugin, addImportsDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addTemplate, addPlugin, addImportsDir, addImports } from '@nuxt/kit';
 
 const module = defineNuxtModule({
   meta: {
@@ -8,13 +8,7 @@ const module = defineNuxtModule({
       nuxt: ">=3.0.0 || >=4.0.0"
     }
   },
-  defaults: {
-    api: {
-      headers: {},
-      query: {},
-      adapter: {}
-    }
-  },
+  defaults: {},
   setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
     addTemplate({
@@ -25,9 +19,13 @@ const module = defineNuxtModule({
       }
     });
     addPlugin(resolve("./runtime", "plugin"));
-    addImportsDir(resolve("./runtime", "core"));
     addImportsDir(resolve("./runtime", "composables"));
-    addImportsDir(resolve("./runtime", "utils"));
+    addImports([
+      {
+        name: "createStore",
+        from: resolve("./runtime/core/store")
+      }
+    ]);
     nuxt.options.build.transpile.push(/@harlem\//);
   }
 });

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

@@ -0,0 +1,4 @@
+import { type Ref } from "vue";
+import { type ActionError, ActionStatus } from "../core/types/action.js";
+export declare function useIsolatedActionStatus(): Ref<ActionStatus>;
+export declare function useIsolatedActionError(): Ref<ActionError | null>;

package/dist/runtime/composables/action.js

@@ -0,0 +1,8 @@
+import { ref } from "vue";
+import { ActionStatus } from "../core/types/action.js";
+export function useIsolatedActionStatus() {
+  return ref(ActionStatus.IDLE);
+}
+export function useIsolatedActionError() {
+  return ref(null);
+}

package/dist/runtime/config.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeModelConfig } from "./core/types/model.js";
+import type { RuntimeViewConfig } from "./core/types/view.js";
+import type { RuntimeActionConfig } from "./core/types/action.js";
+export type RuntimeConfig = {
+    model?: RuntimeModelConfig;
+    view?: RuntimeViewConfig;
+    action?: RuntimeActionConfig;
+    logger?: number;
+};
+export declare const runtimeConfig: RuntimeConfig;

package/dist/runtime/config.js

@@ -0,0 +1,7 @@
+import config from "#build/harlemify.config";
+export const runtimeConfig = {
+  model: config.model ?? {},
+  view: config.view ?? {},
+  action: config.action ?? {},
+  logger: config.logger ?? -999
+};

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

@@ -0,0 +1,4 @@
+import type { ConsolaInstance } from "consola";
+import type { Model } from "../types/model.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>;

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

@@ -0,0 +1,102 @@
+import { buildCommitMethod } from "../utils/action.js";
+import {
+  ActionApiMethod,
+  DEFINITION
+} from "../types/action.js";
+export function createActionFactory(config, logger, _model, _view) {
+  function apiCall(apiDefinition) {
+    apiDefinition = {
+      endpoint: config?.endpoint,
+      headers: config?.headers,
+      query: config?.query,
+      timeout: config?.timeout,
+      concurrent: config?.concurrent,
+      ...apiDefinition
+    };
+    const actionDefinition = {
+      api: apiDefinition,
+      logger
+    };
+    return {
+      handle(callback) {
+        const handleDefinition = {
+          api: apiDefinition,
+          handle: callback,
+          logger
+        };
+        return {
+          commit: buildCommitMethod(handleDefinition),
+          get [DEFINITION]() {
+            return handleDefinition;
+          }
+        };
+      },
+      commit: buildCommitMethod(actionDefinition),
+      get [DEFINITION]() {
+        return actionDefinition;
+      }
+    };
+  }
+  function apiGet(definition) {
+    return apiCall({
+      ...definition,
+      method: ActionApiMethod.GET
+    });
+  }
+  function apiHead(definition) {
+    return apiCall({
+      ...definition,
+      method: ActionApiMethod.HEAD
+    });
+  }
+  function apiPost(definition) {
+    return apiCall({
+      ...definition,
+      method: ActionApiMethod.POST
+    });
+  }
+  function apiPut(definition) {
+    return apiCall({
+      ...definition,
+      method: ActionApiMethod.PUT
+    });
+  }
+  function apiPatch(definition) {
+    return apiCall({
+      ...definition,
+      method: ActionApiMethod.PATCH
+    });
+  }
+  function apiDelete(definition) {
+    return apiCall({
+      ...definition,
+      method: ActionApiMethod.DELETE
+    });
+  }
+  const api = Object.assign(apiCall, {
+    get: apiGet,
+    head: apiHead,
+    post: apiPost,
+    put: apiPut,
+    patch: apiPatch,
+    delete: apiDelete
+  });
+  function handle(callback) {
+    const definition = {
+      handle: callback,
+      logger
+    };
+    return {
+      commit: buildCommitMethod(definition),
+      get [DEFINITION]() {
+        return definition;
+      }
+    };
+  }
+  const commit = buildCommitMethod({ logger });
+  return {
+    api,
+    handle,
+    commit
+  };
+}

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

@@ -0,0 +1,3 @@
+import type { ConsolaInstance } from "consola";
+import { type RuntimeModelConfig, type ModelFactory } from "../types/model.js";
+export declare function createModelFactory(config?: RuntimeModelConfig, logger?: ConsolaInstance): ModelFactory;

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

@@ -0,0 +1,31 @@
+import {
+  ModelKind
+} from "../types/model.js";
+export function createModelFactory(config, logger) {
+  function one(shape, options) {
+    return {
+      shape,
+      kind: ModelKind.OBJECT,
+      options: {
+        identifier: config?.identifier,
+        ...options
+      },
+      logger
+    };
+  }
+  function many(shape, options) {
+    return {
+      shape,
+      kind: ModelKind.ARRAY,
+      options: {
+        identifier: config?.identifier,
+        ...options
+      },
+      logger
+    };
+  }
+  return {
+    one,
+    many
+  };
+}

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

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ShapeFactory } from "../types/shape.js";
+export declare const primitiveField: {
+    string: typeof z.string;
+    number: typeof z.number;
+    boolean: typeof z.boolean;
+    bigint: typeof z.bigint;
+    date: typeof z.date;
+};
+export declare const structureField: {
+    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;
+};
+export declare const formatField: {
+    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;
+};
+export declare const specialField: {
+    any: typeof z.any;
+    unknown: typeof z.unknown;
+    never: typeof z.never;
+    nullable: typeof z.nullable;
+    optional: typeof z.optional;
+};
+export declare function shape<T extends z.ZodRawShape>(definition: T | ((factory: ShapeFactory) => T)): z.ZodObject<T>;

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

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export const primitiveField = {
+  string: z.string,
+  number: z.number,
+  boolean: z.boolean,
+  bigint: z.bigint,
+  date: z.date
+};
+export const structureField = {
+  object: z.object,
+  array: z.array,
+  tuple: z.tuple,
+  record: z.record,
+  map: z.map,
+  set: z.set,
+  enum: z.enum,
+  union: z.union,
+  literal: z.literal
+};
+export const formatField = {
+  email: z.email,
+  url: z.url,
+  uuid: z.uuid,
+  cuid: z.cuid,
+  cuid2: z.cuid2,
+  ulid: z.ulid,
+  nanoid: z.nanoid,
+  jwt: z.jwt,
+  emoji: z.emoji,
+  ipv4: z.ipv4,
+  ipv6: z.ipv6,
+  mac: z.mac,
+  base64: z.base64,
+  base64url: z.base64url,
+  hex: z.hex
+};
+export const specialField = {
+  any: z.any,
+  unknown: z.unknown,
+  never: z.never,
+  nullable: z.nullable,
+  optional: z.optional
+};
+export function shape(definition) {
+  if (typeof definition === "function") {
+    return z.object(
+      definition({
+        ...primitiveField,
+        ...structureField,
+        ...formatField,
+        ...specialField
+      })
+    );
+  }
+  return z.object(definition);
+}

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

@@ -0,0 +1,4 @@
+import type { ConsolaInstance } from "consola";
+import type { Model } 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>;

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

@@ -0,0 +1,21 @@
+export function createViewFactory(config, logger, _model) {
+  function from(source, resolver) {
+    const definition = {
+      sources: [source],
+      resolver,
+      logger
+    };
+    return definition;
+  }
+  function merge(sources, resolver) {
+    return {
+      sources,
+      resolver,
+      logger
+    };
+  }
+  return {
+    from,
+    merge
+  };
+}