@flightdev/data 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+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,265 @@
+# @flight-framework/data
+
+Data fetching primitives for Flight Framework.
+
+## Installation
+
+```bash
+npm install @flight-framework/data
+```
+
+## Loaders
+
+Loaders run on the server before rendering a page. They fetch data that the page needs.
+
+```tsx
+// src/routes/posts/[slug].page.tsx
+import { useLoaderData } from '@flight-framework/data';
+
+export async function loader({ params }: LoaderContext) {
+    const post = await db.posts.findUnique({
+        where: { slug: params.slug }
+    });
+    
+    if (!post) {
+        throw new Response('Not Found', { status: 404 });
+    }
+    
+    return { post };
+}
+
+export default function PostPage() {
+    const { post } = useLoaderData<typeof loader>();
+    
+    return (
+        <article>
+            <h1>{post.title}</h1>
+            <div>{post.content}</div>
+        </article>
+    );
+}
+```
+
+## Actions
+
+Actions handle form submissions and mutations. They run on the server when a form is submitted.
+
+```tsx
+import { redirect, Form } from '@flight-framework/data';
+
+export async function action({ request }: ActionContext) {
+    const formData = await request.formData();
+    
+    await db.posts.create({
+        data: {
+            title: formData.get('title') as string,
+            content: formData.get('content') as string,
+        }
+    });
+    
+    return redirect('/posts');
+}
+
+export default function NewPostPage() {
+    return (
+        <Form method="post">
+            <input name="title" placeholder="Title" required />
+            <textarea name="content" placeholder="Content" />
+            <button type="submit">Create Post</button>
+        </Form>
+    );
+}
+```
+
+## useFetcher
+
+For data fetching without navigation:
+
+```tsx
+import { useFetcher } from '@flight-framework/data';
+
+function SearchBox() {
+    const fetcher = useFetcher<SearchResult[]>();
+    
+    return (
+        <div>
+            <input
+                type="search"
+                onChange={(e) => fetcher.load(`/api/search?q=${e.target.value}`)}
+            />
+            
+            {fetcher.state === 'loading' && <Spinner />}
+            
+            {fetcher.data?.map(result => (
+                <SearchResultItem key={result.id} result={result} />
+            ))}
+        </div>
+    );
+}
+```
+
+## Response Utilities
+
+```ts
+import { redirect, json, notFound, badRequest } from '@flight-framework/data';
+
+// Redirect
+return redirect('/dashboard');
+
+// JSON response
+return json({ success: true });
+
+// 404 Not Found
+return notFound();
+
+// 400 Bad Request
+return badRequest({ error: 'Invalid input' });
+```
+
+## Type Safety
+
+The `SerializeFrom` utility type extracts the return type of a loader:
+
+```tsx
+import type { SerializeFrom } from '@flight-framework/data';
+
+export async function loader() {
+    return { posts: await getPosts() };
+}
+
+// Type is: { posts: Post[] }
+type LoaderData = SerializeFrom<typeof loader>;
+```
+
+## SSR Integration
+
+Loader data is automatically hydrated from SSR to client:
+
+```tsx
+// entry-server.tsx
+import { hydrateLoaderData } from '@flight-framework/data';
+
+const html = `
+    <html>
+        <body>
+            <div id="root">${content}</div>
+            ${hydrateLoaderData(url, loaderData)}
+        </body>
+    </html>
+`;
+```
+
+---
+
+## Client-Side Data Fetching
+
+For client-side data fetching with caching and deduplication, Flight provides `useFetch` and `useAsyncData`.
+
+### useFetch
+
+Simple, cached data fetching:
+
+```tsx
+// React
+import { useFetch } from '@flight-framework/data/react';
+
+function Users() {
+    const { data, pending, error, refresh } = useFetch<User[]>('/api/users');
+    
+    if (pending) return <p>Loading...</p>;
+    if (error) return <p>Error: {error.message}</p>;
+    
+    return (
+        <div>
+            <button onClick={refresh}>Refresh</button>
+            <ul>{data.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+        </div>
+    );
+}
+```
+
+### Framework Adapters
+
+Import from the adapter for your framework:
+
+```typescript
+// React
+import { useFetch, useAsyncData } from '@flight-framework/data/react';
+
+// Vue
+import { useFetch, useAsyncData } from '@flight-framework/data/vue';
+
+// Svelte
+import { useFetch, useAsyncData } from '@flight-framework/data/svelte';
+
+// Solid
+import { useFetch, useAsyncData } from '@flight-framework/data/solid';
+```
+
+### useAsyncData
+
+For custom fetching logic:
+
+```tsx
+import { useAsyncData } from '@flight-framework/data/react';
+
+function Analytics() {
+    const { data, pending, execute } = useAsyncData(
+        'analytics-weekly',
+        async () => await analyticsAPI.getWeeklyReport()
+    );
+    
+    return (
+        <div>
+            <button onClick={execute}>Refresh</button>
+            {pending ? <Spinner /> : <Chart data={data} />}
+        </div>
+    );
+}
+```
+
+### Options
+
+```typescript
+useFetch('/api/data', {
+    key: 'custom-key',      // Cache key (default: url)
+    immediate: true,        // Fetch on mount (default: true)
+    default: [],            // Default value while loading
+    cache: true,            // Enable caching (default: true)
+    dedupe: true,           // Deduplicate requests (default: true)
+    maxAge: 60000,          // Cache TTL in ms
+    revalidateOnFocus: true // Re-fetch on window focus
+});
+```
+
+### Cache Utilities
+
+```typescript
+import { invalidate, prefetch, clearCache } from '@flight-framework/data';
+
+// Invalidate specific key
+invalidate('/api/users');
+
+// Invalidate by pattern
+invalidate(key => key.startsWith('/api/'));
+
+// Prefetch data
+await prefetch('/api/users');
+
+// Clear all cache
+clearCache();
+```
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| LRU Cache | O(1) operations, memory-bounded |
+| Deduplication | Multiple calls share one request |
+| Stale-While-Revalidate | Instant stale data, background refresh |
+| SSR Hydration | Seamless server-to-client transfer |
+| Framework Agnostic | React, Vue, Svelte, Solid |
+
+## License
+
+MIT

package/dist/cache-DU1v4CKe.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @flightdev/data - Fetcher
+ *
+ * High-performance data fetching with:
+ * - Request deduplication
+ * - Stale-while-revalidate
+ * - SSR hydration
+ * - Framework-agnostic core
+ *
+ * Zero external dependencies.
+ *
+ * @module @flightdev/data/fetcher
+ */
+type FetchStatus = 'idle' | 'pending' | 'success' | 'error';
+interface FetchState<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    status: FetchStatus;
+    isStale: boolean;
+}
+interface UseFetchOptions<T> {
+    /** Cache key (default: url) */
+    key?: string;
+    /** Fetch immediately on mount (default: true) */
+    immediate?: boolean;
+    /** Default value while loading */
+    default?: T;
+    /** Transform response data */
+    transform?: (data: unknown) => T;
+    /** Enable caching (default: true) */
+    cache?: boolean;
+    /** Enable request deduplication (default: true) */
+    dedupe?: boolean;
+    /** Cache TTL in milliseconds */
+    maxAge?: number;
+    /** Custom fetch options */
+    fetchOptions?: RequestInit;
+    /** Revalidate on window focus */
+    revalidateOnFocus?: boolean;
+    /** Revalidate on reconnect */
+    revalidateOnReconnect?: boolean;
+}
+interface UseFetchReturn<T> {
+    data: T | undefined;
+    pending: boolean;
+    error: Error | undefined;
+    status: FetchStatus;
+    isStale: boolean;
+    refresh: () => Promise<void>;
+    execute: () => Promise<void>;
+}
+interface UseAsyncDataOptions<T> {
+    /** Default value while loading */
+    default?: T;
+    /** Fetch immediately (default: true) */
+    immediate?: boolean;
+    /** Transform response data */
+    transform?: (data: unknown) => T;
+    /** Cache TTL in milliseconds */
+    maxAge?: number;
+}
+interface UseAsyncDataReturn<T> {
+    data: T | undefined;
+    pending: boolean;
+    error: Error | undefined;
+    status: FetchStatus;
+    execute: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Cancel an in-flight request
+ */
+declare function cancelRequest(key: string): boolean;
+interface FetchDataOptions<T> extends UseFetchOptions<T> {
+    signal?: AbortSignal;
+}
+/**
+ * Core fetch function - framework agnostic
+ */
+declare function fetchData<T>(url: string | null, options?: FetchDataOptions<T>): Promise<FetchState<T>>;
+/**
+ * Core async data function - framework agnostic
+ */
+declare function asyncData<T>(key: string, fetcher: () => Promise<T>, options?: UseAsyncDataOptions<T>): Promise<FetchState<T>>;
+/**
+ * Invalidate cache entries
+ */
+declare function invalidate(pattern: string | RegExp | ((key: string) => boolean)): number;
+/**
+ * Prefetch data and store in cache
+ */
+declare function prefetch<T>(url: string, options?: UseFetchOptions<T>): Promise<void>;
+/**
+ * Get data from cache without fetching
+ */
+declare function getCachedData<T>(key: string): T | undefined;
+/**
+ * Manually set cache data
+ */
+declare function setCachedData<T>(key: string, data: T, options?: {
+    maxAge?: number;
+}): void;
+interface HydrationData {
+    [key: string]: unknown;
+}
+/**
+ * Create hydration script for SSR
+ */
+declare function createFetchHydrationScript(data: HydrationData): string;
+/**
+ * Hydrate cache from SSR data
+ */
+declare function hydrateFetchData(): void;
+declare const isServer: boolean;
+declare const isClient: boolean;
+
+/**
+ * @flightdev/data - LRU Cache
+ *
+ * High-performance LRU (Least Recently Used) cache with O(1) operations.
+ * Uses doubly-linked list + Map for optimal performance.
+ *
+ * Zero external dependencies.
+ *
+ * @module @flightdev/data/cache
+ */
+interface CacheOptions {
+    /** Maximum number of entries (default: 100) */
+    maxSize?: number;
+    /** Default TTL in milliseconds (default: 5 minutes) */
+    defaultMaxAge?: number;
+}
+interface SetOptions {
+    /** TTL in milliseconds for this entry */
+    maxAge?: number;
+}
+/**
+ * High-performance LRU Cache
+ *
+ * - O(1) get, set, delete operations
+ * - Memory-bounded with auto-eviction
+ * - TTL support per entry
+ * - Zero dependencies
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<User>({ maxSize: 100 });
+ * cache.set('user:1', userData, { maxAge: 60000 });
+ * const user = cache.get('user:1');
+ * ```
+ */
+declare class LRUCache<T = unknown> {
+    private map;
+    private head;
+    private tail;
+    private size;
+    private readonly maxSize;
+    private readonly defaultMaxAge;
+    constructor(options?: CacheOptions);
+    /**
+     * Get value from cache
+     * Returns undefined if not found or expired
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set value in cache
+     */
+    set(key: string, value: T, options?: SetOptions): void;
+    /**
+     * Delete entry from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    getSize(): number;
+    /**
+     * Get all keys (for invalidation patterns)
+     */
+    keys(): string[];
+    /**
+     * Invalidate entries matching a pattern
+     */
+    invalidate(pattern: string | RegExp | ((key: string) => boolean)): number;
+    private isExpired;
+    private addToFront;
+    private removeFromList;
+    private moveToFront;
+    private evictLRU;
+}
+/**
+ * Get the global cache instance
+ */
+declare function getCache<T = unknown>(): LRUCache<T>;
+/**
+ * Configure the global cache
+ */
+declare function configureCache(options: CacheOptions): void;
+/**
+ * Clear the global cache
+ */
+declare function clearCache(): void;
+/**
+ * Invalidate cache entries matching pattern
+ */
+declare function invalidateCache(pattern: string | RegExp | ((key: string) => boolean)): number;
+
+export { type CacheOptions as C, type FetchStatus as F, LRUCache as L, type SetOptions as S, type UseFetchOptions as U, asyncData as a, createFetchHydrationScript as b, cancelRequest as c, isServer as d, isClient as e, fetchData as f, getCachedData as g, hydrateFetchData as h, invalidate as i, type FetchState as j, type UseFetchReturn as k, type UseAsyncDataOptions as l, type UseAsyncDataReturn as m, getCache as n, configureCache as o, prefetch as p, clearCache as q, invalidateCache as r, setCachedData as s };