enlace 0.0.0-alpha.4 → 0.0.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Enlace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,417 @@
+# enlace
+
+Type-safe API client with React hooks and Next.js integration.
+
+## Installation
+
+```bash
+npm install enlace
+```
+
+## Quick Start
+
+```typescript
+import { createEnlaceHook, Endpoint } from "enlace";
+
+type ApiSchema = {
+  posts: {
+    $get: Endpoint<Post[]>;
+    $post: Endpoint<Post, ApiError, CreatePost>;
+    _: {
+      $get: Endpoint<Post>;
+      $delete: Endpoint<void>;
+    };
+  };
+};
+
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com");
+```
+
+## Schema Conventions
+
+Defining a schema is **recommended** for full type safety, but **optional**. You can go without types:
+
+```typescript
+// Without schema (untyped, but still works!)
+const useAPI = createEnlaceHook("https://api.example.com");
+const { data } = useAPI((api) => api.any.path.you.want.get());
+```
+
+```typescript
+// With schema (recommended for type safety)
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com");
+```
+
+### Schema Structure
+
+- `$get`, `$post`, `$put`, `$patch`, `$delete` — HTTP method endpoints
+- `_` — Dynamic path segment (e.g., `/users/:id`)
+
+```typescript
+import { Endpoint } from "enlace";
+
+type ApiSchema = {
+  users: {
+    $get: Endpoint<User[]>;           // GET /users
+    $post: Endpoint<User>;            // POST /users
+    _: {                              // /users/:id
+      $get: Endpoint<User>;           // GET /users/:id
+      $put: Endpoint<User>;           // PUT /users/:id
+      $delete: Endpoint<void>;        // DELETE /users/:id
+      profile: {
+        $get: Endpoint<Profile>;      // GET /users/:id/profile
+      };
+    };
+  };
+};
+
+// Usage
+api.users.get();              // GET /users
+api.users[123].get();         // GET /users/123
+api.users[123].profile.get(); // GET /users/123/profile
+```
+
+### Endpoint Type
+
+```typescript
+type Endpoint<TData, TError = unknown, TBody = never> = {
+  data: TData;    // Response data type
+  error: TError;  // Error response type
+  body: TBody;    // Request body type
+};
+
+// Examples
+type GetUsers = Endpoint<User[]>;                      // GET, no body
+type CreateUser = Endpoint<User, ApiError, CreateUserInput>;  // POST with body
+type DeleteUser = Endpoint<void, NotFoundError>;       // DELETE, no response data
+```
+
+## React Hooks
+
+### Query Mode (Auto-Fetch)
+
+For GET requests that fetch data automatically:
+
+```typescript
+function Posts({ page, limit }: { page: number; limit: number }) {
+  const { data, loading, error, ok } = useAPI((api) =>
+    api.posts.get({ query: { page, limit, published: true } })
+  );
+
+  if (loading) return <div>Loading...</div>;
+  if (!ok) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {data.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Features:**
+- Auto-fetches on mount
+- Re-fetches when dependencies change (no deps array needed!)
+- Returns cached data while revalidating
+
+```typescript
+function Post({ id }: { id: number }) {
+  // Automatically re-fetches when `id` or query values change
+  const { data } = useAPI((api) => api.posts[id].get({ query: { include: "author" } }));
+  return <div>{data?.title}</div>;
+}
+```
+
+### Selector Mode (Manual Trigger)
+
+For mutations or lazy-loaded requests:
+
+```typescript
+function DeleteButton({ id }: { id: number }) {
+  const { trigger, loading } = useAPI((api) => api.posts[id].delete);
+
+  return (
+    <button onClick={() => trigger()} disabled={loading}>
+      {loading ? "Deleting..." : "Delete"}
+    </button>
+  );
+}
+```
+
+**With request body:**
+
+```typescript
+function CreatePost() {
+  const { trigger, loading, data } = useAPI((api) => api.posts.post);
+
+  const handleSubmit = async (title: string) => {
+    const result = await trigger({ body: { title } });
+    if (result.ok) {
+      console.log("Created:", result.data);
+    }
+  };
+
+  return <button onClick={() => handleSubmit("New Post")}>Create</button>;
+}
+```
+
+## Caching & Auto-Revalidation
+
+### Automatic Cache Tags (Zero Config)
+
+**Tags are automatically generated from URL paths** — no manual configuration needed:
+
+```typescript
+// GET /posts       → tags: ['posts']
+// GET /posts/123   → tags: ['posts', 'posts/123']
+// GET /users/5/posts → tags: ['users', 'users/5', 'users/5/posts']
+```
+
+**Mutations automatically revalidate matching tags:**
+
+```typescript
+const { trigger } = useAPI((api) => api.posts.post);
+
+// POST /posts automatically revalidates 'posts' tag
+// All queries with 'posts' tag will refetch!
+trigger({ body: { title: "New Post" } });
+```
+
+This means in most cases, **you don't need to specify any tags manually**. The cache just works.
+
+### How It Works
+
+1. **Queries** automatically cache with tags derived from the URL
+2. **Mutations** automatically revalidate tags derived from the URL
+3. All queries matching those tags refetch automatically
+
+```typescript
+// Component A: fetches posts (cached with tag 'posts')
+const { data } = useAPI((api) => api.posts.get());
+
+// Component B: creates a post
+const { trigger } = useAPI((api) => api.posts.post);
+trigger({ body: { title: "New" } });
+// → Automatically revalidates 'posts' tag
+// → Component A refetches automatically!
+```
+
+### Stale Time
+
+Control how long cached data is considered fresh:
+
+```typescript
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {}, {
+  staleTime: 5000, // 5 seconds
+});
+```
+
+- `staleTime: 0` (default) — Always revalidate on mount
+- `staleTime: 5000` — Data is fresh for 5 seconds
+- `staleTime: Infinity` — Never revalidate automatically
+
+### Manual Tag Override (Optional)
+
+Override auto-generated tags when needed:
+
+```typescript
+// Custom cache tags
+const { data } = useAPI((api) => api.posts.get({ tags: ["my-custom-tag"] }));
+
+// Custom revalidation tags
+trigger({
+  body: { title: "New" },
+  revalidateTags: ["posts", "dashboard"], // Override auto-generated
+});
+```
+
+### Disable Auto-Revalidation
+
+```typescript
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {}, {
+  autoGenerateTags: false,     // Disable auto tag generation
+  autoRevalidateTags: false,   // Disable auto revalidation
+});
+```
+
+## Hook Options
+
+```typescript
+const useAPI = createEnlaceHook<ApiSchema>(
+  "https://api.example.com",
+  {
+    // Default fetch options
+    headers: { Authorization: "Bearer token" },
+  },
+  {
+    // Hook options
+    autoGenerateTags: true,    // Auto-generate cache tags from URL
+    autoRevalidateTags: true,  // Auto-revalidate after mutations
+    staleTime: 0,              // Cache freshness duration (ms)
+  }
+);
+```
+
+## Return Types
+
+### Query Mode
+
+```typescript
+type UseEnlaceQueryResult<TData, TError> = {
+  loading: boolean;   // No cached data and fetching
+  fetching: boolean;  // Request in progress
+  ok: boolean | undefined;
+  data: TData | undefined;
+  error: TError | undefined;
+};
+```
+
+### Selector Mode
+
+```typescript
+type UseEnlaceSelectorResult<TMethod> = {
+  trigger: TMethod;   // Function to trigger the request
+  loading: boolean;
+  fetching: boolean;
+  ok: boolean | undefined;
+  data: TData | undefined;
+  error: TError | undefined;
+};
+```
+
+---
+
+## Next.js Integration
+
+### Server Components
+
+Use `createEnlace` from `enlace/next` for server components:
+
+```typescript
+import { createEnlace } from "enlace/next";
+
+const api = createEnlace<ApiSchema>("https://api.example.com", {}, {
+  autoGenerateTags: true,
+});
+
+export default async function Page() {
+  const { data } = await api.posts.get({
+    revalidate: 60, // ISR: revalidate every 60 seconds
+  });
+
+  return <PostList posts={data} />;
+}
+```
+
+### Client Components
+
+Use `createEnlaceHook` from `enlace/next/hook` for client components:
+
+```typescript
+"use client";
+
+import { createEnlaceHook } from "enlace/next/hook";
+
+const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com");
+```
+
+### Server-Side Revalidation
+
+Trigger Next.js cache revalidation after mutations:
+
+```typescript
+// actions.ts
+"use server";
+
+import { revalidateTag, revalidatePath } from "next/cache";
+
+export async function revalidateAction(tags: string[], paths: string[]) {
+  for (const tag of tags) {
+    revalidateTag(tag);
+  }
+  for (const path of paths) {
+    revalidatePath(path);
+  }
+}
+```
+
+```typescript
+// useAPI.ts
+import { createEnlaceHook } from "enlace/next/hook";
+import { revalidateAction } from "./actions";
+
+const useAPI = createEnlaceHook<ApiSchema>("/api", {}, {
+  revalidator: revalidateAction,
+});
+```
+
+**In components:**
+
+```typescript
+function CreatePost() {
+  const { trigger } = useAPI((api) => api.posts.post);
+
+  const handleCreate = () => {
+    trigger({
+      body: { title: "New Post" },
+      revalidateTags: ["posts"],      // Passed to revalidator
+      revalidatePaths: ["/posts"],    // Passed to revalidator
+    });
+  };
+}
+```
+
+### Next.js Request Options
+
+```typescript
+api.posts.get({
+  tags: ["posts"],           // Next.js cache tags
+  revalidate: 60,            // ISR revalidation (seconds)
+  revalidateTags: ["posts"], // Tags to invalidate after mutation
+  revalidatePaths: ["/"],    // Paths to revalidate after mutation
+  skipRevalidator: false,    // Skip server-side revalidation
+});
+```
+
+### Relative URLs
+
+Works with Next.js API routes:
+
+```typescript
+// Client component calling /api/posts
+const useAPI = createEnlaceHook<ApiSchema>("/api");
+```
+
+---
+
+## API Reference
+
+### `createEnlaceHook<TSchema>(baseUrl, options?, hookOptions?)`
+
+Creates a React hook for making API calls.
+
+**Parameters:**
+- `baseUrl` — Base URL for requests
+- `options` — Default fetch options (headers, cache, etc.)
+- `hookOptions` — Hook configuration
+
+**Hook Options:**
+```typescript
+type EnlaceHookOptions = {
+  autoGenerateTags?: boolean;    // default: true
+  autoRevalidateTags?: boolean;  // default: true
+  staleTime?: number;            // default: 0
+};
+```
+
+### Re-exports from enlace-core
+
+- `Endpoint` — Type helper for schema definition
+- `EnlaceResponse` — Response type
+- `EnlaceOptions` — Fetch options type
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,121 +1,97 @@
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-type SchemaMethod = "$get" | "$post" | "$put" | "$patch" | "$delete";
-type EnlaceResponse<TData, TError> = {
-    ok: true;
-    status: number;
-    data: TData;
-    error?: never;
-} | {
-    ok: false;
-    status: number;
-    data?: never;
-    error: TError;
-};
-type EnlaceOptions = Omit<RequestInit, "method" | "body">;
-type FetchExecutor<TOptions = EnlaceOptions, TRequestOptions = RequestOptions<unknown>> = <TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: TOptions, requestOptions?: TRequestOptions) => Promise<EnlaceResponse<TData, TError>>;
-type RequestOptions<TBody = never> = {
-    body?: TBody;
-    query?: Record<string, string | number | boolean | undefined>;
-    headers?: HeadersInit;
-    cache?: RequestCache;
+import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+export * from 'enlace-core';
+
+/** Per-request options for React hooks */
+type ReactRequestOptionsBase = {
+    /**
+     * Cache tags for caching (GET requests only)
+     * This will auto generate tags from the URL path if not provided and autoGenerateTags is enabled.
+     * But can be manually specified to override auto-generation.
+     * */
+    tags?: string[];
+    /** Tags to invalidate after mutation (triggers refetch in matching queries) */
+    revalidateTags?: string[];
 };
-type MethodDefinition = {
+type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
+type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
+type SelectorFn<TSchema, TMethod, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => TMethod;
+type HookState = {
+    loading: boolean;
+    fetching: boolean;
+    ok: boolean | undefined;
     data: unknown;
     error: unknown;
-    body?: unknown;
 };
-/**
- * Helper to define an endpoint with proper typing.
- * Provides cleaner syntax than writing { data, error, body } manually.
- *
- * @example
- * type MyApi = {
- *   posts: {
- *     $get: Endpoint<Post[], ApiError>;
- *     $post: Endpoint<Post, ApiError, CreatePost>;  // with body
- *     _: {
- *       $get: Endpoint<Post, NotFoundError>;
- *     };
- *   };
- * };
- */
-type Endpoint<TData, TError, TBody = never> = [TBody] extends [never] ? {
-    data: TData;
-    error: TError;
-} : {
+type TrackedCall = {
+    path: string[];
+    method: string;
+    options: unknown;
+};
+declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete"];
+type ExtractData<T> = T extends (...args: any[]) => Promise<EnlaceResponse<infer D, unknown>> ? D : never;
+type ExtractError<T> = T extends (...args: any[]) => Promise<EnlaceResponse<unknown, infer E>> ? E : never;
+/** Discriminated union for hook response state - enables type narrowing on ok check */
+type HookResponseState<TData, TError> = {
+    ok: undefined;
+    data: undefined;
+    error: undefined;
+} | {
+    ok: true;
     data: TData;
+    error: undefined;
+} | {
+    ok: false;
+    data: undefined;
     error: TError;
-    body: TBody;
-};
-type ExtractMethodDef<TSchema, TMethod extends SchemaMethod> = TSchema extends {
-    [K in TMethod]: infer M;
-} ? M extends MethodDefinition ? M : never : never;
-type ExtractData<TSchema, TMethod extends SchemaMethod> = ExtractMethodDef<TSchema, TMethod> extends {
-    data: infer D;
-} ? D : never;
-type ExtractError<TSchema, TMethod extends SchemaMethod> = ExtractMethodDef<TSchema, TMethod> extends {
-    error: infer E;
-} ? E : never;
-type ExtractBody<TSchema, TMethod extends SchemaMethod> = ExtractMethodDef<TSchema, TMethod> extends {
-    body: infer B;
-} ? B : never;
-type HasMethod<TSchema, TMethod extends SchemaMethod> = TSchema extends {
-    [K in TMethod]: MethodDefinition;
-} ? true : false;
-type MethodFn<TSchema, TMethod extends SchemaMethod, TRequestOptionsBase = object> = HasMethod<TSchema, TMethod> extends true ? ExtractBody<TSchema, TMethod> extends never ? (options?: RequestOptions<never> & TRequestOptionsBase) => Promise<EnlaceResponse<ExtractData<TSchema, TMethod>, ExtractError<TSchema, TMethod>>> : (options: RequestOptions<ExtractBody<TSchema, TMethod>> & TRequestOptionsBase) => Promise<EnlaceResponse<ExtractData<TSchema, TMethod>, ExtractError<TSchema, TMethod>>> : never;
-type IsSpecialKey<K> = K extends SchemaMethod | "_" ? true : false;
-type StaticPathKeys<TSchema> = {
-    [K in keyof TSchema as IsSpecialKey<K> extends true ? never : K extends string ? K : never]: TSchema[K];
 };
-type ExtractDynamicSchema<TSchema> = TSchema extends {
-    _: infer D;
-} ? D : never;
-type MethodOrPath<TSchema, TMethodName extends string, TSchemaMethod extends SchemaMethod, TRequestOptionsBase = object> = TMethodName extends keyof TSchema ? EnlaceClient<TSchema[TMethodName], TRequestOptionsBase> : MethodFn<TSchema, TSchemaMethod, TRequestOptionsBase>;
-type HttpMethods<TSchema, TRequestOptionsBase = object> = {
-    get: MethodOrPath<TSchema, "get", "$get", TRequestOptionsBase>;
-    post: MethodOrPath<TSchema, "post", "$post", TRequestOptionsBase>;
-    put: MethodOrPath<TSchema, "put", "$put", TRequestOptionsBase>;
-    patch: MethodOrPath<TSchema, "patch", "$patch", TRequestOptionsBase>;
-    delete: MethodOrPath<TSchema, "delete", "$delete", TRequestOptionsBase>;
-};
-type DynamicAccess<TSchema, TRequestOptionsBase = object> = ExtractDynamicSchema<TSchema> extends never ? object : {
-    [key: string]: EnlaceClient<ExtractDynamicSchema<TSchema>, TRequestOptionsBase>;
-    [key: number]: EnlaceClient<ExtractDynamicSchema<TSchema>, TRequestOptionsBase>;
+/** Result when hook is called with query function (auto-fetch mode) */
+type UseEnlaceQueryResult<TData, TError> = {
+    loading: boolean;
+    fetching: boolean;
+} & HookResponseState<TData, TError>;
+/** Result when hook is called with method selector (trigger mode) */
+type UseEnlaceSelectorResult<TMethod> = {
+    trigger: TMethod;
+    loading: boolean;
+    fetching: boolean;
+} & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
+
+type EnlaceHookOptions = {
+    /**
+     * Auto-generate cache tags from URL path for GET requests.
+     * e.g., `/posts/1` generates tags `['posts', 'posts/1']`
+     * @default true
+     */
+    autoGenerateTags?: boolean;
+    /** Auto-revalidate generated tags after successful mutations. @default true */
+    autoRevalidateTags?: boolean;
+    /** Time in ms before cached data is considered stale. @default 0 (always stale) */
+    staleTime?: number;
 };
-type MethodNameKeys = "get" | "post" | "put" | "patch" | "delete";
-type EnlaceClient<TSchema, TRequestOptionsBase = object> = HttpMethods<TSchema, TRequestOptionsBase> & DynamicAccess<TSchema, TRequestOptionsBase> & {
-    [K in keyof StaticPathKeys<TSchema> as K extends MethodNameKeys ? never : K]: EnlaceClient<TSchema[K], TRequestOptionsBase>;
+type EnlaceHook<TSchema> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
 };
-type WildcardMethodFn<TRequestOptionsBase = object> = (options?: RequestOptions<unknown> & TRequestOptionsBase) => Promise<EnlaceResponse<unknown, unknown>>;
 /**
- * Wildcard client type - allows any path access when no schema is provided.
- * All methods are available at every level and return unknown types.
- */
-type WildcardClient<TRequestOptionsBase = object> = {
-    get: WildcardMethodFn<TRequestOptionsBase>;
-    post: WildcardMethodFn<TRequestOptionsBase>;
-    put: WildcardMethodFn<TRequestOptionsBase>;
-    patch: WildcardMethodFn<TRequestOptionsBase>;
-    delete: WildcardMethodFn<TRequestOptionsBase>;
-} & {
-    [key: string]: WildcardClient<TRequestOptionsBase>;
-    [key: number]: WildcardClient<TRequestOptionsBase>;
-};
-
-declare function createProxyHandler<TSchema extends object, TOptions = EnlaceOptions>(baseUrl: string, defaultOptions: TOptions, path?: string[], fetchExecutor?: FetchExecutor<TOptions, RequestOptions<unknown>>): TSchema;
-
-declare function executeFetch<TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: EnlaceOptions, requestOptions?: RequestOptions<unknown>): Promise<EnlaceResponse<TData, TError>>;
-
-/**
- * Creates an API client.
+ * Creates a React hook for making API calls.
+ * Called at module level to create a reusable hook.
  *
  * @example
- * // Typed mode - with schema
- * const api = createEnlace<MyApi>('https://api.example.com');
+ * const useAPI = createEnlaceHook<ApiSchema>('https://api.com');
  *
- * // Untyped mode - no schema
- * const api = createEnlace('https://api.example.com');
+ * // Query mode - auto-fetch (auto-tracks changes, no deps array needed)
+ * const { loading, data, error } = useAPI((api) => api.posts.get({ query: { userId } }));
+ *
+ * // Selector mode - typed trigger for lazy calls
+ * const { trigger, loading, data, error } = useAPI((api) => api.posts.delete);
+ * onClick={() => trigger({ body: { id: 1 } })}
  */
-declare function createEnlace<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions): unknown extends TSchema ? WildcardClient : EnlaceClient<TSchema>;
+declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema>;
+
+type Listener = (tags: string[]) => void;
+declare function invalidateTags(tags: string[]): void;
+declare function onRevalidate(callback: Listener): () => void;
+
+declare function clearCache(key?: string): void;
 
-export { type Endpoint, type EnlaceClient, type EnlaceOptions, type EnlaceResponse, type FetchExecutor, type HttpMethod, type MethodDefinition, type RequestOptions, type SchemaMethod, type WildcardClient, createEnlace, createProxyHandler, executeFetch };
+export { type ApiClient, type EnlaceHookOptions, HTTP_METHODS, type HookState, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, clearCache, createEnlaceHook, invalidateTags, onRevalidate };