@flightdev/data 0.0.6

package/dist/chunk-NOWQL3EM.js

@@ -0,0 +1,398 @@
+// src/cache.ts
+var LRUCache = class {
+  map = /* @__PURE__ */ new Map();
+  head = null;
+  tail = null;
+  size = 0;
+  maxSize;
+  defaultMaxAge;
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 100;
+    this.defaultMaxAge = options.defaultMaxAge ?? 5 * 60 * 1e3;
+  }
+  /**
+   * Get value from cache
+   * Returns undefined if not found or expired
+   */
+  get(key) {
+    const entry = this.map.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (this.isExpired(entry)) {
+      this.delete(key);
+      return void 0;
+    }
+    this.moveToFront(entry);
+    return entry.value;
+  }
+  /**
+   * Set value in cache
+   */
+  set(key, value, options = {}) {
+    const existingEntry = this.map.get(key);
+    if (existingEntry) {
+      existingEntry.value = value;
+      existingEntry.timestamp = Date.now();
+      existingEntry.maxAge = options.maxAge ?? this.defaultMaxAge;
+      this.moveToFront(existingEntry);
+      return;
+    }
+    const entry = {
+      key,
+      value,
+      timestamp: Date.now(),
+      maxAge: options.maxAge ?? this.defaultMaxAge,
+      prev: null,
+      next: null
+    };
+    this.map.set(key, entry);
+    this.size++;
+    this.addToFront(entry);
+    if (this.size > this.maxSize) {
+      this.evictLRU();
+    }
+  }
+  /**
+   * Delete entry from cache
+   */
+  delete(key) {
+    const entry = this.map.get(key);
+    if (!entry) {
+      return false;
+    }
+    this.removeFromList(entry);
+    this.map.delete(key);
+    this.size--;
+    return true;
+  }
+  /**
+   * Check if key exists and is not expired
+   */
+  has(key) {
+    const entry = this.map.get(key);
+    if (!entry) {
+      return false;
+    }
+    if (this.isExpired(entry)) {
+      this.delete(key);
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Clear all entries
+   */
+  clear() {
+    this.map.clear();
+    this.head = null;
+    this.tail = null;
+    this.size = 0;
+  }
+  /**
+   * Get current cache size
+   */
+  getSize() {
+    return this.size;
+  }
+  /**
+   * Get all keys (for invalidation patterns)
+   */
+  keys() {
+    return Array.from(this.map.keys());
+  }
+  /**
+   * Invalidate entries matching a pattern
+   */
+  invalidate(pattern) {
+    let count = 0;
+    const keysToDelete = [];
+    for (const key of this.map.keys()) {
+      let shouldDelete = false;
+      if (typeof pattern === "string") {
+        shouldDelete = key === pattern || key.startsWith(pattern);
+      } else if (pattern instanceof RegExp) {
+        shouldDelete = pattern.test(key);
+      } else {
+        shouldDelete = pattern(key);
+      }
+      if (shouldDelete) {
+        keysToDelete.push(key);
+      }
+    }
+    for (const key of keysToDelete) {
+      this.delete(key);
+      count++;
+    }
+    return count;
+  }
+  // ========================================================================
+  // Private Methods
+  // ========================================================================
+  isExpired(entry) {
+    if (!entry.maxAge) return false;
+    return Date.now() - entry.timestamp > entry.maxAge;
+  }
+  addToFront(entry) {
+    entry.next = this.head;
+    entry.prev = null;
+    if (this.head) {
+      this.head.prev = entry;
+    }
+    this.head = entry;
+    if (!this.tail) {
+      this.tail = entry;
+    }
+  }
+  removeFromList(entry) {
+    if (entry.prev) {
+      entry.prev.next = entry.next;
+    } else {
+      this.head = entry.next;
+    }
+    if (entry.next) {
+      entry.next.prev = entry.prev;
+    } else {
+      this.tail = entry.prev;
+    }
+    entry.prev = null;
+    entry.next = null;
+  }
+  moveToFront(entry) {
+    if (this.head === entry) {
+      return;
+    }
+    this.removeFromList(entry);
+    this.addToFront(entry);
+  }
+  evictLRU() {
+    if (!this.tail) return;
+    const lruKey = this.tail.key;
+    this.removeFromList(this.tail);
+    this.map.delete(lruKey);
+    this.size--;
+  }
+};
+var globalCache = null;
+function getCache() {
+  if (!globalCache) {
+    globalCache = new LRUCache();
+  }
+  return globalCache;
+}
+function configureCache(options) {
+  globalCache = new LRUCache(options);
+}
+function clearCache() {
+  if (globalCache) {
+    globalCache.clear();
+  }
+}
+function invalidateCache(pattern) {
+  if (!globalCache) return 0;
+  return globalCache.invalidate(pattern);
+}
+
+// src/fetcher.ts
+var inFlightRequests = /* @__PURE__ */ new Map();
+async function deduplicatedFetch(key, fetcher, options = {}) {
+  const { dedupe = true } = options;
+  if (!dedupe) {
+    return fetcher();
+  }
+  const existing = inFlightRequests.get(key);
+  if (existing) {
+    existing.subscribers++;
+    return existing.promise;
+  }
+  const controller = new AbortController();
+  const promise = fetcher();
+  const inFlight = {
+    promise,
+    controller,
+    subscribers: 1
+  };
+  inFlightRequests.set(key, inFlight);
+  try {
+    const result = await promise;
+    return result;
+  } finally {
+    inFlightRequests.delete(key);
+  }
+}
+function cancelRequest(key) {
+  const inFlight = inFlightRequests.get(key);
+  if (inFlight) {
+    inFlight.controller.abort();
+    inFlightRequests.delete(key);
+    return true;
+  }
+  return false;
+}
+async function fetchData(url, options = {}) {
+  if (!url) {
+    return {
+      data: options.default,
+      error: void 0,
+      status: "idle",
+      isStale: false
+    };
+  }
+  const {
+    key = url,
+    cache: useCache = true,
+    dedupe = true,
+    maxAge,
+    transform,
+    fetchOptions,
+    signal
+  } = options;
+  const cacheInstance = getCache();
+  if (useCache) {
+    const cached = cacheInstance.get(key);
+    if (cached !== void 0) {
+      return {
+        data: cached,
+        error: void 0,
+        status: "success",
+        isStale: false
+      };
+    }
+  }
+  try {
+    const result = await deduplicatedFetch(key, async () => {
+      const response = await fetch(url, {
+        ...fetchOptions,
+        signal,
+        headers: {
+          "Accept": "application/json",
+          ...fetchOptions?.headers
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const data = await response.json();
+      return transform ? transform(data) : data;
+    }, { dedupe });
+    if (useCache) {
+      cacheInstance.set(key, result, { maxAge });
+    }
+    return {
+      data: result,
+      error: void 0,
+      status: "success",
+      isStale: false
+    };
+  } catch (error) {
+    if (useCache) {
+      const stale = cacheInstance.get(key);
+      if (stale !== void 0) {
+        return {
+          data: stale,
+          error: error instanceof Error ? error : new Error(String(error)),
+          status: "error",
+          isStale: true
+        };
+      }
+    }
+    return {
+      data: options.default,
+      error: error instanceof Error ? error : new Error(String(error)),
+      status: "error",
+      isStale: false
+    };
+  }
+}
+async function asyncData(key, fetcher, options = {}) {
+  const { maxAge, transform } = options;
+  const cacheInstance = getCache();
+  const cached = cacheInstance.get(key);
+  if (cached !== void 0) {
+    return {
+      data: cached,
+      error: void 0,
+      status: "success",
+      isStale: false
+    };
+  }
+  try {
+    const result = await deduplicatedFetch(key, fetcher);
+    const transformed = transform ? transform(result) : result;
+    cacheInstance.set(key, transformed, { maxAge });
+    return {
+      data: transformed,
+      error: void 0,
+      status: "success",
+      isStale: false
+    };
+  } catch (error) {
+    return {
+      data: options.default,
+      error: error instanceof Error ? error : new Error(String(error)),
+      status: "error",
+      isStale: false
+    };
+  }
+}
+function invalidate(pattern) {
+  for (const key of inFlightRequests.keys()) {
+    let shouldCancel = false;
+    if (typeof pattern === "string") {
+      shouldCancel = key === pattern || key.startsWith(pattern);
+    } else if (pattern instanceof RegExp) {
+      shouldCancel = pattern.test(key);
+    } else {
+      shouldCancel = pattern(key);
+    }
+    if (shouldCancel) {
+      cancelRequest(key);
+    }
+  }
+  return invalidateCache(pattern);
+}
+async function prefetch(url, options) {
+  await fetchData(url, { ...options, immediate: true });
+}
+function getCachedData(key) {
+  return getCache().get(key);
+}
+function setCachedData(key, data, options) {
+  getCache().set(key, data, options);
+}
+var isBrowser = typeof window !== "undefined";
+function createFetchHydrationScript(data) {
+  const serialized = JSON.stringify(data).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+  return `<script>window.__FLIGHT_FETCH_DATA__ = ${serialized};</script>`;
+}
+function hydrateFetchData() {
+  if (!isBrowser) return;
+  const hydrated = window.__FLIGHT_FETCH_DATA__;
+  if (!hydrated) return;
+  const cache = getCache();
+  for (const [key, value] of Object.entries(hydrated)) {
+    cache.set(key, value);
+  }
+  delete window.__FLIGHT_FETCH_DATA__;
+}
+var isServer = !isBrowser;
+var isClient = isBrowser;
+
+export {
+  LRUCache,
+  getCache,
+  configureCache,
+  clearCache,
+  invalidateCache,
+  cancelRequest,
+  fetchData,
+  asyncData,
+  invalidate,
+  prefetch,
+  getCachedData,
+  setCachedData,
+  createFetchHydrationScript,
+  hydrateFetchData,
+  isServer,
+  isClient
+};

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+export { C as CacheOptions, j as FetchState, F as FetchStatus, L as LRUCache, S as SetOptions, l as UseAsyncDataOptions, m as UseAsyncDataReturn, U as UseFetchOptions, k as UseFetchReturn, a as asyncData, c as cancelRequest, q as clearCache, o as configureCache, b as createFetchHydrationScript, f as fetchData, n as getCache, g as getCachedData, h as hydrateFetchData, i as invalidate, r as invalidateCache, e as isClient, d as isServer, p as prefetch, s as setCachedData } from './cache-DU1v4CKe.js';
+
+/**
+ * Type definitions for @flightdev/data
+ */
+/**
+ * Context passed to loader functions
+ */
+interface LoaderContext {
+    /** Route parameters from dynamic segments */
+    params: Record<string, string>;
+    /** Incoming request object (server-side only) */
+    request: Request;
+    /** URL search params */
+    searchParams: URLSearchParams;
+}
+/**
+ * Loader function signature
+ * Runs on the server before rendering the page
+ */
+type LoaderFunction<T = unknown> = (context: LoaderContext) => Promise<T> | T;
+/**
+ * Context passed to action functions
+ */
+interface ActionContext {
+    /** Route parameters from dynamic segments */
+    params: Record<string, string>;
+    /** Incoming request with form data */
+    request: Request;
+    /** URL search params */
+    searchParams: URLSearchParams;
+}
+/**
+ * Action function signature
+ * Handles form submissions and mutations
+ */
+type ActionFunction<T = unknown> = (context: ActionContext) => Promise<T | Response> | T | Response;
+/**
+ * Utility type to extract the return type of a loader
+ * Removes Promise wrapper if present
+ */
+type SerializeFrom<T> = T extends (...args: unknown[]) => infer R ? R extends Promise<infer U> ? U : R : never;
+/**
+ * Fetcher state for client-side data fetching
+ */
+type FetcherState<T = unknown> = {
+    state: 'idle';
+    data: undefined;
+    error: undefined;
+} | {
+    state: 'loading';
+    data: undefined;
+    error: undefined;
+} | {
+    state: 'success';
+    data: T;
+    error: undefined;
+} | {
+    state: 'error';
+    data: undefined;
+    error: Error;
+};
+
+/**
+ * @flightdev/data - Data Hooks
+ *
+ * Framework-agnostic data hooks with React 19 support.
+ *
+ * Philosophy:
+ * - Zero external dependencies
+ * - Framework agnostic (React, Vue, Solid, etc.)
+ * - User decides how to provide/consume data
+ * - SSR/Hydration support built-in
+ *
+ * @module @flightdev/data/hooks
+ */
+
+/**
+ * Set loader data in store (used during SSR hydration)
+ */
+declare function setLoaderData(key: string, data: unknown): void;
+/**
+ * Get loader data from store
+ */
+declare function getLoaderData<T>(key: string): T | undefined;
+/**
+ * Set action data in store
+ */
+declare function setActionData(key: string, data: unknown): void;
+/**
+ * Get action data from store
+ */
+declare function getActionData<T>(key: string): T | undefined;
+/**
+ * Clear all data stores (for testing/cleanup)
+ */
+declare function clearDataStores(): void;
+/**
+ * Universal `use()` hook - Suspense-aware promise unwrapping
+ *
+ * Works like React 19's use() hook but framework-agnostic.
+ * For React: integrates with Suspense
+ * For others: provides consistent API
+ *
+ * @example
+ * ```typescript
+ * const data = use(fetchData());
+ * return <div>{data.name}</div>;
+ * ```
+ */
+declare function use<T>(promise: Promise<T>): T;
+/**
+ * useLoaderData - Access loader data
+ *
+ * Framework-aware: Uses React hooks when available,
+ * falls back to store-based implementation otherwise.
+ *
+ * @example
+ * ```typescript
+ * export async function loader({ params }: LoaderContext) {
+ *     const user = await db.users.find(params.id);
+ *     return { user };
+ * }
+ *
+ * export default function UserPage() {
+ *     const { user } = useLoaderData<typeof loader>();
+ *     return <h1>{user.name}</h1>;
+ * }
+ * ```
+ */
+declare function useLoaderData<T extends (...args: never[]) => unknown>(): SerializeFrom<T>;
+/**
+ * useActionData - Access action result
+ *
+ * @example
+ * ```typescript
+ * export async function action({ request }: ActionContext) {
+ *     const formData = await request.formData();
+ *     const result = await processForm(formData);
+ *     return result;
+ * }
+ *
+ * export default function FormPage() {
+ *     const actionData = useActionData<typeof action>();
+ *     return actionData?.error ? <p>{actionData.error}</p> : null;
+ * }
+ * ```
+ */
+declare function useActionData<T>(): T | undefined;
+/**
+ * useFetcher - Client-side data fetching
+ *
+ * @example
+ * ```typescript
+ * function SearchBox() {
+ *     const fetcher = useFetcher<SearchResult[]>();
+ *
+ *     return (
+ *         <div>
+ *             <input
+ *                 onChange={e => fetcher.load(`/api/search?q=${e.target.value}`)}
+ *             />
+ *             {fetcher.state === 'loading' && <Spinner />}
+ *             {fetcher.data?.map(result => (
+ *                 <SearchResult key={result.id} {...result} />
+ *             ))}
+ *             {fetcher.error && <ErrorMessage error={fetcher.error} />}
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+declare function useFetcher<T>(): {
+    state: FetcherState<T>['state'];
+    data: T | undefined;
+    error: Error | undefined;
+    submit: (data: FormData | Record<string, string>, options?: {
+        method?: string;
+        action?: string;
+    }) => void;
+    load: (href: string) => void;
+    reset: () => void;
+};
+/**
+ * Create hydration script for SSR
+ * Injects loader data into the page for client hydration
+ */
+declare function createHydrationScript(pathname: string, loaderData: unknown, actionData?: unknown): string;
+/**
+ * Hydrate data from SSR script (call on client initialization)
+ */
+declare function hydrateFromWindow(): void;
+
+/**
+ * Form Component
+ *
+ * Enhanced form that integrates with Flight actions.
+ * Handles submission, loading states, and redirects.
+ */
+declare let Form: unknown;
+
+/**
+ * Response Utilities
+ *
+ * Helper functions for creating standard responses in loaders and actions.
+ */
+/**
+ * Create a redirect response
+ *
+ * @example
+ * ```ts
+ * export async function action({ request }: ActionContext) {
+ *     await saveData(request);
+ *     return redirect('/success');
+ * }
+ * ```
+ */
+declare function redirect(url: string, init?: ResponseInit): Response;
+/**
+ * Create a JSON response
+ *
+ * @example
+ * ```ts
+ * export async function loader() {
+ *     const data = await fetchData();
+ *     return json({ data });
+ * }
+ * ```
+ */
+declare function json<T>(data: T, init?: ResponseInit): Response;
+/**
+ * Create a deferred response for streaming SSR
+ * Allows returning promises that resolve during streaming
+ *
+ * @example
+ * ```ts
+ * export async function loader() {
+ *     return defer({
+ *         // Critical data - blocks render
+ *         user: await getUser(),
+ *         // Deferred data - streams in later
+ *         posts: getPosts(), // No await!
+ *     });
+ * }
+ * ```
+ */
+declare function defer<T extends Record<string, unknown>>(data: T): T;
+/**
+ * Check if a response is a redirect
+ */
+declare function isRedirectResponse(response: Response): boolean;
+/**
+ * Check if a response is JSON
+ */
+declare function isJsonResponse(response: Response): boolean;
+
+/**
+ * Server Utilities
+ *
+ * Functions for running loaders and actions on the server.
+ * These are used by the Flight SSR runtime.
+ */
+
+/**
+ * Run a loader function and return the result
+ */
+declare function runLoader<T>(loader: LoaderFunction<T>, context: LoaderContext): Promise<T | Response>;
+/**
+ * Run an action function and return the result
+ */
+declare function runAction<T>(action: ActionFunction<T>, context: ActionContext): Promise<T | Response>;
+/**
+ * Generate script tag for hydrating loader data
+ */
+declare function hydrateLoaderData(pathname: string, data: unknown): string;
+
+export { type ActionContext, type ActionFunction, Form, type LoaderContext, type LoaderFunction, type SerializeFrom, clearDataStores, createHydrationScript, defer, getActionData, getLoaderData, hydrateFromWindow, hydrateLoaderData, isJsonResponse, isRedirectResponse, json, redirect, runAction, runLoader, setActionData, setLoaderData, use, useActionData, useFetcher, useLoaderData };