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

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 };

package/dist/index.d.ts

@@ -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 };