@diphyx/harlemify 2.0.0 → 3.0.0

package/README.md

@@ -2,25 +2,22 @@
 
 > 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.
-
 ## 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
+- **Free-form Actions** - Define any action with custom naming
+- **Chainable Builders** - Fluent `Endpoint` and `Memory` APIs
+- **Function-based Monitor** - Track status with `pending()`, `success()`, `failed()`, `idle()`
+- **Custom Adapters** - Override HTTP at module, store, endpoint, or call-time
+- **SSR Support** - Server-side rendering with automatic hydration
 
-## Installation
+## Install
 
 ```bash
 npm install @diphyx/harlemify
 ```
 
-## Quick Start
+## Setup
 
 ```typescript
 // nuxt.config.ts
@@ -30,130 +27,59 @@ export default defineNuxtConfig({
         api: {
             adapter: {
                 baseURL: "https://api.example.com",
-                timeout: 10000,
             },
         },
     },
 });
 ```
 
+## Usage
+
 ```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],
-    }),
-});
+enum UserAction {
+    LIST = "list",
+    CREATE = "create",
+}
 
-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}` },
+const userSchema = z.object({
+    id: z.number().meta({ indicator: true }),
+    name: z.string().meta({ actions: [UserAction.CREATE] }),
+    email: z.string().meta({ actions: [UserAction.CREATE] }),
 });
-```
-
-## 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:
-
-```typescript
-import { defineApiAdapter } from "@diphyx/harlemify";
-
-const customAdapter = defineApiAdapter({
-    baseURL: "/api",
-    timeout: 5000,
-    retry: 3,
-    retryDelay: 1000,
-    retryStatusCodes: [500, 502, 503],
-});
-```
-
-### 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:**
-
-```typescript
-export const userStore = createStore(
-    "user",
-    UserSchema,
-    {
-        [Endpoint.GET_UNITS]: { method: EndpointMethod.GET, url: "/users" },
+export const userStore = createStore("user", userSchema, {
+    [UserAction.LIST]: {
+        endpoint: Endpoint.get("/users"),
+        memory: Memory.units(),
     },
-    {
-        adapter: customAdapter, // Used for all endpoints in this store
-    },
-);
-```
-
-**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
-    },
-    [Endpoint.GET_UNITS]: {
-        method: EndpointMethod.GET,
-        url: "/users",
-        // Uses store or global adapter
+    [UserAction.CREATE]: {
+        endpoint: Endpoint.post("/users"),
+        memory: Memory.units().add(),
     },
 });
 ```
 
-## Why Harlemify?
+```vue
+<script setup>
+const { users, listUser, userMonitor } = useStoreAlias(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 listUser();
+</script>
+
+<template>
+    <div v-if="userMonitor.list.pending()">Loading...</div>
+    <ul v-else>
+        <li v-for="user in users" :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.json

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

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

@@ -1,30 +1,22 @@
 import type { ComputedRef } from "vue";
-import { EndpointMethod } from "../utils/endpoint.js";
-import type { Store } from "../core/store.js";
-import type { Pluralize, Capitalize } from "../utils/transform.js";
-import type { EndpointStatusFlag } from "../utils/endpoint.js";
-type Indicator<T, I extends keyof T> = Required<Pick<T, I>>;
-type PartialWithIndicator<T, I extends keyof T> = Indicator<T, I> & Partial<T>;
+import type { ActionFunction, ActionStatus, ActionsConfig, Store, StoreMemory } from "../core/store.js";
+import type { Capitalize, Pluralize } from "../utils/transform.js";
 type MemoryState<E extends string, T> = {
     [P in E]: ComputedRef<T | null>;
 } & {
     [P in Pluralize<E>]: ComputedRef<T[]>;
 };
-type MemoryAction<A extends string, E extends string, U> = {
-    [K in `${A}${Capitalize<E>}`]: (unit: U) => void;
-} & {
-    [K in `${A}${Capitalize<Pluralize<E>>}`]: (units: U[]) => void;
+type AliasActions<E extends string, A extends ActionsConfig<S>, S> = {
+    [K in keyof A as `${K & string}${Capitalize<E>}`]: ActionFunction<S>;
 };
-type EndpointAction<E extends string, T> = {
-    [M in EndpointMethod as `${M}${Capitalize<E>}`]: (unit?: Partial<T>) => Promise<T>;
-} & {
-    [M in EndpointMethod as `${M}${Capitalize<Pluralize<E>>}`]: (units?: Partial<T>[]) => Promise<T[]>;
+type AliasMemory<E extends string, S, I extends keyof S> = {
+    [K in `${E}Memory`]: StoreMemory<S, I>;
 };
-type EndpointMonitor<E extends string> = {
-    [M in EndpointMethod as `${M}${Capitalize<E>}${EndpointStatusFlag}`]: ComputedRef<boolean>;
-} & {
-    [M in EndpointMethod as `${M}${Capitalize<Pluralize<E>>}${EndpointStatusFlag}`]: ComputedRef<boolean>;
+type AliasMonitor<E extends string, A extends ActionsConfig<any>> = {
+    [K in `${E}Monitor`]: {
+        [ActionName in keyof A]: ActionStatus;
+    };
 };
-type StoreAlias<E extends string, T, I extends keyof T = keyof T> = MemoryState<E, T> & MemoryAction<"set", E, T | null> & MemoryAction<"edit", E, PartialWithIndicator<T, I>> & MemoryAction<"drop", E, PartialWithIndicator<T, I>> & EndpointAction<E, T> & EndpointMonitor<E>;
-export declare function useStoreAlias<E extends string, T, I extends keyof T = keyof T>(store: Store<E, T, I>): StoreAlias<E, T, I>;
+export type StoreAlias<E extends string, S, I extends keyof S, A extends ActionsConfig<S>> = MemoryState<E, S> & AliasActions<E, A, S> & AliasMemory<E, S, I> & AliasMonitor<E, A>;
+export declare function useStoreAlias<E extends string, S, I extends keyof S, A extends ActionsConfig<S>>(store: Store<E, S, I, A>): StoreAlias<E, S, I, A>;
 export {};

package/dist/runtime/composables/use.js

@@ -1,25 +1,14 @@
 import { capitalize } from "../utils/transform.js";
-import { EndpointMethod, EndpointStatus, makeEndpointStatusFlag } from "../utils/endpoint.js";
-import { StoreMemoryAction } from "../core/store.js";
 export function useStoreAlias(store) {
-  const capitalizedUnit = capitalize(store.alias.unit);
-  const capitalizedUnits = capitalize(store.alias.units);
+  const capitalizedEntity = capitalize(store.alias.unit);
   const output = {
     [store.alias.unit]: store.unit,
-    [store.alias.units]: store.units
+    [store.alias.units]: store.units,
+    [`${store.alias.unit}Memory`]: store.memory,
+    [`${store.alias.unit}Monitor`]: store.monitor
   };
-  for (const action of Object.values(StoreMemoryAction)) {
-    output[`${action}${capitalizedUnit}`] = store.memory[`${action}Unit`];
-    output[`${action}${capitalizedUnits}`] = store.memory[`${action}Units`];
-  }
-  for (const method of Object.values(EndpointMethod)) {
-    output[`${method}${capitalizedUnit}`] = store.endpoint[`${method}Unit`];
-    output[`${method}${capitalizedUnits}`] = store.endpoint[`${method}Units`];
-    for (const status of Object.values(EndpointStatus)) {
-      const statusFlag = makeEndpointStatusFlag(status);
-      output[`${method}${capitalizedUnit}${statusFlag}`] = store.monitor[`${method}Unit${statusFlag}`];
-      output[`${method}${capitalizedUnits}${statusFlag}`] = store.monitor[`${method}Units${statusFlag}`];
-    }
+  for (const actionName in store.action) {
+    output[`${actionName}${capitalizedEntity}`] = store.action[actionName];
   }
   return output;
 }

package/dist/runtime/core/api.d.ts

@@ -1,6 +1,6 @@
 import type { MaybeRefOrGetter } from "vue";
 import { EndpointMethod } from "../utils/endpoint.js";
-import { type ApiAdapter } from "./adapter.js";
+import type { ApiAdapter } from "../utils/adapter.js";
 export type ApiRequestHeader = MaybeRefOrGetter<Record<string, unknown>>;
 export type ApiRequestQuery = MaybeRefOrGetter<Record<string, unknown>>;
 export type ApiRequestBody = MaybeRefOrGetter<string | number | ArrayBuffer | FormData | Blob | Record<string, any>>;

package/dist/runtime/core/api.js

@@ -1,6 +1,6 @@
 import { toValue } from "vue";
+import { defineApiAdapter } from "../utils/adapter.js";
 import { EndpointMethod } from "../utils/endpoint.js";
-import { defineApiAdapter } from "./adapter.js";
 export function createApi(options) {
   const defaultAdapter = options?.adapter ?? defineApiAdapter();
   async function request(url, requestOptions) {
@@ -9,14 +9,8 @@ export function createApi(options) {
       method: requestOptions?.action ?? EndpointMethod.GET,
       url,
       body: toValue(requestOptions?.body),
-      query: {
-        ...toValue(options?.query),
-        ...toValue(requestOptions?.query)
-      },
-      headers: {
-        ...toValue(options?.headers),
-        ...toValue(requestOptions?.headers)
-      },
+      query: Object.assign({}, toValue(options?.query), toValue(requestOptions?.query)),
+      headers: Object.assign({}, toValue(options?.headers), toValue(requestOptions?.headers)),
       signal: requestOptions?.signal
     };
     const response = await adapter(adapterRequest);

package/dist/runtime/core/store.d.ts

@@ -1,75 +1,69 @@
 import type { z } from "zod";
 import type { ComputedRef } from "vue";
 import type { Extension, BaseState } from "@harlem/core";
-import { Endpoint, EndpointStatus } from "../utils/endpoint.js";
-import type { EndpointMethodOptions } from "./api.js";
-import type { ApiAdapter } from "./adapter.js";
-import type { EndpointDefinition, EndpointStatusName } from "../utils/endpoint.js";
+import { EndpointStatus } from "../utils/endpoint.js";
+import type { ApiAdapter } from "../utils/adapter.js";
 import type { Pluralize } from "../utils/transform.js";
-export declare enum StoreMemoryAction {
-    SET = "set",
-    EDIT = "edit",
-    DROP = "drop"
+import type { EndpointDefinition } from "../utils/endpoint.js";
+import type { MemoryDefinition } from "../utils/memory.js";
+export interface ActionDefinition<S = Record<string, unknown>> {
+    endpoint: EndpointDefinition<S>;
+    memory?: MemoryDefinition;
 }
-export declare enum StoreMemoryPosition {
-    FIRST = "first",
-    LAST = "last"
+export interface ActionOptions {
+    query?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    signal?: AbortSignal;
+    validate?: boolean;
+    adapter?: ApiAdapter<any>;
+}
+export interface ActionStatus {
+    current: () => EndpointStatus;
+    pending: () => boolean;
+    success: () => boolean;
+    failed: () => boolean;
+    idle: () => boolean;
 }
 export interface StoreHooks {
     before?: () => Promise<void> | void;
     after?: (error?: Error) => Promise<void> | void;
 }
-export interface StoreOptions {
+export interface StoreOptions<_A extends ActionsConfig<any> = ActionsConfig<any>> {
     adapter?: ApiAdapter<any>;
     indicator?: string;
     hooks?: StoreHooks;
     extensions?: Extension<BaseState>[];
 }
-type Indicator<T, I extends keyof T> = Required<Pick<T, I>>;
-type WithIndicator<T, I extends keyof T> = Indicator<T, I> & T;
-type PartialWithIndicator<T, I extends keyof T> = Indicator<T, I> & Partial<T>;
-type StoreEndpointReadOptions = Omit<EndpointMethodOptions<any>, "body">;
-type StoreEndpointWriteOptions = EndpointMethodOptions<any> & {
-    validate?: boolean;
-};
-type StoreEndpointWriteMultipleOptions = StoreEndpointWriteOptions & {
-    position?: StoreMemoryPosition;
-};
-type StoreMemory<T = unknown, I extends keyof T = keyof T> = {
-    setUnit: (unit: T | null) => void;
-    setUnits: (units: T[]) => void;
-    editUnit: (unit: PartialWithIndicator<T, I>) => void;
-    editUnits: (units: PartialWithIndicator<T, I>[]) => void;
-    dropUnit: (unit: PartialWithIndicator<T, I>) => void;
-    dropUnits: (units: PartialWithIndicator<T, I>[]) => void;
+export type ActionsConfig<S = Record<string, unknown>> = Record<string, ActionDefinition<S>>;
+export type ActionFunction<S> = (params?: Partial<S>, options?: ActionOptions) => Promise<S | S[] | boolean>;
+export type StoreActions<A extends ActionsConfig<S>, S> = {
+    [K in keyof A]: ActionFunction<S>;
 };
-type StoreEndpoint<T = unknown, I extends keyof T = keyof T> = {
-    getUnit: (unit?: PartialWithIndicator<T, I>, options?: StoreEndpointReadOptions) => Promise<T>;
-    getUnits: (options?: StoreEndpointReadOptions) => Promise<T[]>;
-    postUnit: (unit: WithIndicator<T, I>, options?: StoreEndpointWriteOptions) => Promise<T>;
-    postUnits: (units: WithIndicator<T, I>[], options?: StoreEndpointWriteMultipleOptions) => Promise<T[]>;
-    putUnit: (unit: WithIndicator<T, I>, options?: StoreEndpointWriteOptions) => Promise<T>;
-    putUnits: (units: WithIndicator<T, I>[], options?: StoreEndpointWriteOptions) => Promise<T[]>;
-    patchUnit: (unit: PartialWithIndicator<T, I>, options?: StoreEndpointWriteOptions) => Promise<Partial<T>>;
-    patchUnits: (units: PartialWithIndicator<T, I>[], options?: StoreEndpointWriteOptions) => Promise<Partial<T>[]>;
-    deleteUnit: (unit: PartialWithIndicator<T, I>, options?: StoreEndpointReadOptions) => Promise<boolean>;
-    deleteUnits: (units: PartialWithIndicator<T, I>[], options?: StoreEndpointReadOptions) => Promise<boolean>;
+export type StoreMonitor<A extends ActionsConfig<any>> = {
+    [K in keyof A]: ActionStatus;
 };
-type StoreMonitor = {
-    [K in Endpoint as EndpointStatusName<K, EndpointStatus>]: ComputedRef<boolean>;
+export type StoreMemory<T, I extends keyof T> = {
+    set: (data: T | T[] | null) => void;
+    edit: (data: PartialWithIndicator<T, I> | PartialWithIndicator<T, I>[], options?: {
+        deep?: boolean;
+    }) => void;
+    drop: (data: PartialWithIndicator<T, I> | PartialWithIndicator<T, I>[]) => void;
 };
-export type Store<E extends string = string, T = unknown, I extends keyof T = keyof T> = {
+export type Store<E extends string = string, S = unknown, I extends keyof S = keyof S, A extends ActionsConfig<S> = ActionsConfig<S>> = {
     store: any;
     alias: {
         unit: E;
         units: Pluralize<E>;
     };
     indicator: I;
-    unit: ComputedRef<T | null>;
-    units: ComputedRef<T[]>;
-    memory: StoreMemory<T, I>;
-    endpoint: StoreEndpoint<T, I>;
-    monitor: StoreMonitor;
+    unit: ComputedRef<S | null>;
+    units: ComputedRef<S[]>;
+    action: StoreActions<A, S>;
+    memory: StoreMemory<S, I>;
+    monitor: StoreMonitor<A>;
 };
-export declare function createStore<E extends string, T extends z.ZodRawShape, S extends z.infer<z.ZodObject<T>> = z.infer<z.ZodObject<T>>, I extends keyof S = "id" & keyof S>(entity: E, schema: z.ZodObject<T>, endpoints?: Partial<Record<Endpoint, EndpointDefinition<Partial<S>>>>, options?: StoreOptions): Store<E, S, I>;
+type Indicator<T, I extends keyof T> = Required<Pick<T, I>>;
+type PartialWithIndicator<T, I extends keyof T> = Indicator<T, I> & Partial<T>;
+export declare function createStore<E extends string, T extends z.ZodRawShape, A extends ActionsConfig<z.infer<z.ZodObject<T>>>, S extends z.infer<z.ZodObject<T>> = z.infer<z.ZodObject<T>>, I extends keyof S = "id" & keyof S>(entity: E, schema: z.ZodObject<T>, actions: A, options?: StoreOptions<A>): Store<E, S, I, A>;
 export {};