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

package/dist/index.mjs

@@ -1,14 +1,349 @@
+// src/index.ts
+export * from "enlace-core";
+
+// src/react/createEnlaceHook.ts
 import {
-  createProxyHandler,
-  executeFetch
-} from "./chunk-PNORT7RX.mjs";
+  createEnlace
+} from "enlace-core";
+
+// src/react/useQueryMode.ts
+import { useRef, useReducer, useEffect } from "react";
+
+// src/react/reducer.ts
+var initialState = {
+  loading: false,
+  fetching: false,
+  ok: void 0,
+  data: void 0,
+  error: void 0
+};
+function hookReducer(state, action) {
+  switch (action.type) {
+    case "RESET":
+      return action.state;
+    case "FETCH_START":
+      return {
+        ...state,
+        loading: state.data === void 0,
+        fetching: true
+      };
+    case "FETCH_SUCCESS":
+      return {
+        loading: false,
+        fetching: false,
+        ok: true,
+        data: action.data,
+        error: void 0
+      };
+    case "FETCH_ERROR":
+      return {
+        loading: false,
+        fetching: false,
+        ok: false,
+        data: void 0,
+        error: action.error
+      };
+    case "SYNC_CACHE":
+      return action.state;
+    default:
+      return state;
+  }
+}
+
+// src/utils/generateTags.ts
+function generateTags(path) {
+  return path.map((_, i) => path.slice(0, i + 1).join("/"));
+}
+
+// src/utils/sortObjectKeys.ts
+function sortObjectKeys(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+  return Object.keys(obj).sort().reduce(
+    (sorted, key) => {
+      sorted[key] = sortObjectKeys(obj[key]);
+      return sorted;
+    },
+    {}
+  );
+}
+
+// src/react/cache.ts
+var cache = /* @__PURE__ */ new Map();
+function createQueryKey(tracked) {
+  return JSON.stringify(
+    sortObjectKeys({
+      path: tracked.path,
+      method: tracked.method,
+      options: tracked.options
+    })
+  );
+}
+function getCache(key) {
+  return cache.get(key);
+}
+function setCache(key, entry) {
+  const existing = cache.get(key);
+  if (existing) {
+    if ("ok" in entry) {
+      delete existing.promise;
+    }
+    Object.assign(existing, entry);
+    existing.subscribers.forEach((cb) => cb());
+  } else {
+    cache.set(key, {
+      data: void 0,
+      error: void 0,
+      ok: void 0,
+      timestamp: 0,
+      tags: [],
+      subscribers: /* @__PURE__ */ new Set(),
+      ...entry
+    });
+  }
+}
+function subscribeCache(key, callback) {
+  let entry = cache.get(key);
+  if (!entry) {
+    cache.set(key, {
+      data: void 0,
+      error: void 0,
+      ok: void 0,
+      timestamp: 0,
+      tags: [],
+      subscribers: /* @__PURE__ */ new Set()
+    });
+    entry = cache.get(key);
+  }
+  entry.subscribers.add(callback);
+  return () => {
+    entry.subscribers.delete(callback);
+  };
+}
+function isStale(key, staleTime) {
+  const entry = cache.get(key);
+  if (!entry) return true;
+  return Date.now() - entry.timestamp > staleTime;
+}
+function clearCache(key) {
+  if (key) {
+    cache.delete(key);
+  } else {
+    cache.clear();
+  }
+}
+function clearCacheByTags(tags) {
+  cache.forEach((entry) => {
+    const hasMatch = entry.tags.some((tag) => tags.includes(tag));
+    if (hasMatch) {
+      entry.data = void 0;
+      entry.error = void 0;
+      entry.ok = void 0;
+      entry.timestamp = 0;
+      delete entry.promise;
+    }
+  });
+}
+
+// src/react/revalidator.ts
+var listeners = /* @__PURE__ */ new Set();
+function invalidateTags(tags) {
+  clearCacheByTags(tags);
+  listeners.forEach((listener) => listener(tags));
+}
+function onRevalidate(callback) {
+  listeners.add(callback);
+  return () => listeners.delete(callback);
+}
+
+// src/react/useQueryMode.ts
+function useQueryMode(api, trackedCall, options) {
+  const { autoGenerateTags, staleTime } = options;
+  const queryKey = createQueryKey(trackedCall);
+  const requestOptions = trackedCall.options;
+  const queryTags = requestOptions?.tags ?? (autoGenerateTags ? generateTags(trackedCall.path) : []);
+  const getCacheState = (includeNeedsFetch = false) => {
+    const cached = getCache(queryKey);
+    const hasCachedData = cached?.data !== void 0;
+    const isFetching = !!cached?.promise;
+    const needsFetch = includeNeedsFetch && (!hasCachedData || isStale(queryKey, staleTime));
+    return {
+      loading: !hasCachedData && (isFetching || needsFetch),
+      fetching: isFetching || needsFetch,
+      ok: cached?.ok,
+      data: cached?.data,
+      error: cached?.error
+    };
+  };
+  const [state, dispatch] = useReducer(hookReducer, null, () => getCacheState(true));
+  const mountedRef = useRef(true);
+  const fetchRef = useRef(null);
+  useEffect(() => {
+    mountedRef.current = true;
+    dispatch({ type: "RESET", state: getCacheState(true) });
+    const unsubscribe = subscribeCache(queryKey, () => {
+      if (mountedRef.current) {
+        dispatch({ type: "SYNC_CACHE", state: getCacheState() });
+      }
+    });
+    const doFetch = () => {
+      const cached2 = getCache(queryKey);
+      if (cached2?.promise) {
+        return;
+      }
+      dispatch({ type: "FETCH_START" });
+      let current = api;
+      for (const segment of trackedCall.path) {
+        current = current[segment];
+      }
+      const method = current[trackedCall.method];
+      const fetchPromise = method(trackedCall.options).then((res) => {
+        if (mountedRef.current) {
+          setCache(queryKey, {
+            data: res.ok ? res.data : void 0,
+            error: res.ok ? void 0 : res.error,
+            ok: res.ok,
+            timestamp: Date.now(),
+            tags: queryTags
+          });
+        }
+      });
+      setCache(queryKey, {
+        promise: fetchPromise,
+        tags: queryTags
+      });
+    };
+    fetchRef.current = doFetch;
+    const cached = getCache(queryKey);
+    if (cached?.data !== void 0 && !isStale(queryKey, staleTime)) {
+      dispatch({ type: "SYNC_CACHE", state: getCacheState() });
+    } else {
+      doFetch();
+    }
+    return () => {
+      mountedRef.current = false;
+      fetchRef.current = null;
+      unsubscribe();
+    };
+  }, [queryKey]);
+  useEffect(() => {
+    if (queryTags.length === 0) return;
+    return onRevalidate((invalidatedTags) => {
+      const hasMatch = invalidatedTags.some((tag) => queryTags.includes(tag));
+      if (hasMatch && mountedRef.current && fetchRef.current) {
+        fetchRef.current();
+      }
+    });
+  }, [JSON.stringify(queryTags)]);
+  return state;
+}
+
+// src/react/types.ts
+var HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
+
+// src/react/trackingProxy.ts
+function createTrackingProxy(onTrack) {
+  const createProxy = (path = []) => {
+    return new Proxy(() => {
+    }, {
+      get(_, prop) {
+        if (HTTP_METHODS.includes(prop)) {
+          const methodFn = (options) => {
+            onTrack({
+              trackedCall: { path, method: prop, options },
+              selectorPath: null,
+              selectorMethod: null
+            });
+            return Promise.resolve({ ok: true, data: void 0 });
+          };
+          onTrack({
+            trackedCall: null,
+            selectorPath: path,
+            selectorMethod: prop
+          });
+          return methodFn;
+        }
+        return createProxy([...path, prop]);
+      }
+    });
+  };
+  return createProxy();
+}
+
+// src/react/useSelectorMode.ts
+import { useRef as useRef2, useReducer as useReducer2 } from "react";
+function useSelectorMode(method, path, autoRevalidateTags) {
+  const [state, dispatch] = useReducer2(hookReducer, initialState);
+  const methodRef = useRef2(method);
+  const triggerRef = useRef2(null);
+  const pathRef = useRef2(path);
+  const autoRevalidateRef = useRef2(autoRevalidateTags);
+  methodRef.current = method;
+  pathRef.current = path;
+  autoRevalidateRef.current = autoRevalidateTags;
+  if (!triggerRef.current) {
+    triggerRef.current = (async (...args) => {
+      dispatch({ type: "FETCH_START" });
+      const res = await methodRef.current(...args);
+      if (res.ok) {
+        dispatch({ type: "FETCH_SUCCESS", data: res.data });
+        const options = args[0];
+        const tagsToInvalidate = options?.revalidateTags ?? (autoRevalidateRef.current ? generateTags(pathRef.current) : []);
+        if (tagsToInvalidate.length > 0) {
+          invalidateTags(tagsToInvalidate);
+        }
+      } else {
+        dispatch({ type: "FETCH_ERROR", error: res.error });
+      }
+      return res;
+    });
+  }
+  return {
+    trigger: triggerRef.current,
+    ...state
+  };
+}
 
-// src/core/index.ts
-function createEnlace(baseUrl, defaultOptions = {}) {
-  return createProxyHandler(baseUrl, defaultOptions);
+// src/react/createEnlaceHook.ts
+function createEnlaceHook(baseUrl, defaultOptions = {}, hookOptions = {}) {
+  const api = createEnlace(baseUrl, defaultOptions);
+  const {
+    autoGenerateTags = true,
+    autoRevalidateTags = true,
+    staleTime = 0
+  } = hookOptions;
+  function useEnlaceHook(selectorOrQuery) {
+    let trackingResult = {
+      trackedCall: null,
+      selectorPath: null,
+      selectorMethod: null
+    };
+    const trackingProxy = createTrackingProxy((result2) => {
+      trackingResult = result2;
+    });
+    const result = selectorOrQuery(
+      trackingProxy
+    );
+    if (typeof result === "function") {
+      const actualResult = selectorOrQuery(api);
+      return useSelectorMode(
+        actualResult,
+        trackingResult.selectorPath ?? [],
+        autoRevalidateTags
+      );
+    }
+    return useQueryMode(
+      api,
+      trackingResult.trackedCall,
+      { autoGenerateTags, staleTime }
+    );
+  }
+  return useEnlaceHook;
 }
 export {
-  createEnlace,
-  createProxyHandler,
-  executeFetch
+  HTTP_METHODS,
+  clearCache,
+  createEnlaceHook,
+  invalidateTags,
+  onRevalidate
 };

package/dist/next/hook/index.d.mts

@@ -0,0 +1,124 @@
+import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } 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 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 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;
+};
+/** 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;
+};
+
+/**
+ * Handler function called after successful mutations to trigger server-side revalidation.
+ * @param tags - Cache tags to revalidate
+ * @param paths - URL paths to revalidate
+ */
+type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+/** Next.js-specific options (third argument for createEnlace) */
+type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & {
+    /**
+     * Handler called after successful mutations to trigger server-side revalidation.
+     * Receives auto-generated or manually specified tags and paths.
+     * @example
+     * ```ts
+     * createEnlace("http://localhost:3000/api/", {}, {
+     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     * });
+     * ```
+     */
+    revalidator?: RevalidateHandler;
+};
+/** Next.js hook options (third argument for createEnlaceHook) - extends React's EnlaceHookOptions */
+type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
+/** Per-request options for Next.js fetch - extends React's base options */
+type NextRequestOptionsBase = ReactRequestOptionsBase & {
+    /** Time in seconds to revalidate, or false to disable */
+    revalidate?: number | false;
+    /**
+     * URL paths to revalidate after mutation
+     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
+     * You must implement the revalidation logic in the revalidator.
+     */
+    revalidatePaths?: string[];
+    /**
+     * Skip server-side revalidation for this request.
+     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
+     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
+     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
+     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     */
+    skipRevalidator?: boolean;
+};
+
+type NextQueryFn<TSchema, TData, TError> = QueryFn<TSchema, TData, TError, NextRequestOptionsBase>;
+type NextSelectorFn<TSchema, TMethod> = SelectorFn<TSchema, TMethod, NextRequestOptionsBase>;
+type NextEnlaceHook<TSchema> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
+};
+/**
+ * Creates a React hook for making API calls in Next.js Client Components.
+ * Uses Next.js-specific features like revalidator for server-side cache invalidation.
+ *
+ * @example
+ * const useAPI = createEnlaceHook<ApiSchema>('https://api.com', {}, {
+ *   revalidator: (tags) => revalidateTagsAction(tags),
+ *   staleTime: 5000,
+ * });
+ *
+ * // Query mode - auto-fetch
+ * const { loading, data, error } = useAPI((api) => api.posts.get());
+ *
+ * // Selector mode - trigger for mutations
+ * const { trigger } = useAPI((api) => api.posts.delete);
+ */
+declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema>;
+
+export { createEnlaceHook };

package/dist/next/hook/index.d.ts

@@ -0,0 +1,124 @@
+import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } 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 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 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;
+};
+/** 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;
+};
+
+/**
+ * Handler function called after successful mutations to trigger server-side revalidation.
+ * @param tags - Cache tags to revalidate
+ * @param paths - URL paths to revalidate
+ */
+type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+/** Next.js-specific options (third argument for createEnlace) */
+type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & {
+    /**
+     * Handler called after successful mutations to trigger server-side revalidation.
+     * Receives auto-generated or manually specified tags and paths.
+     * @example
+     * ```ts
+     * createEnlace("http://localhost:3000/api/", {}, {
+     *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
+     * });
+     * ```
+     */
+    revalidator?: RevalidateHandler;
+};
+/** Next.js hook options (third argument for createEnlaceHook) - extends React's EnlaceHookOptions */
+type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
+/** Per-request options for Next.js fetch - extends React's base options */
+type NextRequestOptionsBase = ReactRequestOptionsBase & {
+    /** Time in seconds to revalidate, or false to disable */
+    revalidate?: number | false;
+    /**
+     * URL paths to revalidate after mutation
+     * This doesn't do anything on the client by itself - it's passed to the revalidator handler.
+     * You must implement the revalidation logic in the revalidator.
+     */
+    revalidatePaths?: string[];
+    /**
+     * Skip server-side revalidation for this request.
+     * Useful when autoRevalidateTags is enabled but you want to opt-out for specific mutations.
+     * You can still pass empty [] to revalidateTags to skip triggering revalidation.
+     * But this flag can be used if you want to revalidate client-side and skip server-side entirely.
+     * Eg. you don't fetch any data on server component and you might want to skip the overhead of revalidation.
+     */
+    skipRevalidator?: boolean;
+};
+
+type NextQueryFn<TSchema, TData, TError> = QueryFn<TSchema, TData, TError, NextRequestOptionsBase>;
+type NextSelectorFn<TSchema, TMethod> = SelectorFn<TSchema, TMethod, NextRequestOptionsBase>;
+type NextEnlaceHook<TSchema> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>): UseEnlaceQueryResult<TData, TError>;
+};
+/**
+ * Creates a React hook for making API calls in Next.js Client Components.
+ * Uses Next.js-specific features like revalidator for server-side cache invalidation.
+ *
+ * @example
+ * const useAPI = createEnlaceHook<ApiSchema>('https://api.com', {}, {
+ *   revalidator: (tags) => revalidateTagsAction(tags),
+ *   staleTime: 5000,
+ * });
+ *
+ * // Query mode - auto-fetch
+ * const { loading, data, error } = useAPI((api) => api.posts.get());
+ *
+ * // Selector mode - trigger for mutations
+ * const { trigger } = useAPI((api) => api.posts.delete);
+ */
+declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema>;
+
+export { createEnlaceHook };