@getforma/core 0.9.0 → 1.0.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 /// <reference path="./jsx.d.ts" />
-import { S as SignalGetter } from './signal-B4_wQJHs.cjs';
-export { c as createSignal } from './signal-B4_wQJHs.cjs';
+import { S as SignalGetter } from './signal-YlS1kgfh.cjs';
+export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-YlS1kgfh.cjs';
+export { R as Resource, a as ResourceOptions, c as createResource } from './resource-DK98lW5e.cjs';
 export { getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, trigger } from 'alien-signals';
 
 declare function createEffect(fn: () => void | (() => void)): () => void;
@@ -284,65 +285,6 @@ type Dispatch<A> = (action: A) => void;
  */
 declare function createReducer<S, A>(reducer: (state: S, action: A) => S, initialState: S): [state: SignalGetter<S>, dispatch: Dispatch<A>];
 
-/**
- * Forma Reactive - Resource
- *
- * Async data fetching primitive with reactive loading/error state.
- * Tracks a source signal and refetches when it changes.
- *
- * SolidJS equivalent: createResource
- * React equivalent: use() + Suspense (React 19), or useSWR/react-query
- */
-
-interface Resource<T> {
-    /** The resolved data (or undefined while loading). */
-    (): T | undefined;
-    /** True while the fetcher is running. */
-    loading: SignalGetter<boolean>;
-    /** The error if the fetcher rejected (or undefined). */
-    error: SignalGetter<unknown>;
-    /** Manually refetch with the current source value. */
-    refetch: () => void;
-    /** Manually set the data (overrides fetcher result). */
-    mutate: (value: T | undefined) => void;
-}
-interface ResourceOptions<T> {
-    /** Initial value before first fetch resolves. */
-    initialValue?: T;
-}
-/**
- * Create an async resource that fetches data reactively.
- *
- * When `source` changes, the fetcher re-runs automatically.
- * Provides reactive `loading` and `error` signals.
- *
- * ```ts
- * const [userId, setUserId] = createSignal(1);
- *
- * const user = createResource(
- *   userId,                                    // source signal
- *   (id) => fetch(`/api/users/${id}`).then(r => r.json()), // fetcher
- * );
- *
- * internalEffect(() => {
- *   if (user.loading()) console.log('Loading...');
- *   else if (user.error()) console.log('Error:', user.error());
- *   else console.log('User:', user());
- * });
- *
- * setUserId(2); // automatically refetches
- * ```
- *
- * Without a source signal (static fetch):
- * ```ts
- * const posts = createResource(
- *   () => true,  // constant source — fetches once
- *   () => fetch('/api/posts').then(r => r.json()),
- * );
- * ```
- */
-declare function createResource<T, S = true>(source: SignalGetter<S>, fetcher: (source: S) => Promise<T>, options?: ResourceOptions<T>): Resource<T>;
-
 type ErrorHandler = (error: unknown, info?: {
     source?: string;
 }) => void;
@@ -1052,400 +994,4 @@ declare function onResize(el: HTMLElement, handler: (entry: ResizeObserverEntry)
 declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit): () => void;
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-interface TypedStorage<T> {
-    get(): T | null;
-    set(value: T): void;
-    remove(): void;
-    key: string;
-}
-interface StorageOptions<T> {
-    serialize?: (v: T) => string;
-    deserialize?: (s: string) => T;
-    /** Optional validator — return true if the deserialized value is valid. */
-    validate?: (v: unknown) => v is T;
-}
-
-/**
- * Forma Storage - Local
- *
- * Typed localStorage wrapper with graceful error handling.
- * Zero dependencies — native browser APIs only.
- */
-
-/**
- * Create a typed localStorage wrapper for the given key.
- *
- * ```ts
- * const store = createLocalStorage<{ name: string }>('user');
- * store.set({ name: 'Alice' });
- * store.get(); // { name: 'Alice' }
- * store.remove();
- * ```
- */
-declare function createLocalStorage<T>(key: string, options?: StorageOptions<T>): TypedStorage<T>;
-
-/**
- * Forma Storage - Session
- *
- * Typed sessionStorage wrapper with graceful error handling.
- * Zero dependencies — native browser APIs only.
- */
-
-/**
- * Create a typed sessionStorage wrapper for the given key.
- *
- * ```ts
- * const store = createSessionStorage<{ token: string }>('auth');
- * store.set({ token: 'abc123' });
- * store.get(); // { token: 'abc123' }
- * store.remove();
- * ```
- */
-declare function createSessionStorage<T>(key: string, options?: StorageOptions<T>): TypedStorage<T>;
-
-/**
- * Forma Storage - IndexedDB
- *
- * Simplified IndexedDB wrapper with lazy connection and promise-based API.
- * Zero dependencies — native browser APIs only.
- */
-interface IDBStore<T> {
-    get(key: string): Promise<T | undefined>;
-    set(key: string, value: T): Promise<void>;
-    delete(key: string): Promise<void>;
-    getAll(): Promise<T[]>;
-    keys(): Promise<string[]>;
-    clear(): Promise<void>;
-}
-/**
- * Create a simplified IndexedDB store.
- *
- * ```ts
- * const store = createIndexedDB<User>('myApp', 'users');
- * await store.set('u1', { name: 'Alice' });
- * const user = await store.get('u1'); // { name: 'Alice' }
- * ```
- */
-declare function createIndexedDB<T>(dbName: string, storeName?: string): IDBStore<T>;
-
-/**
- * Forma HTTP - Fetch
- *
- * Typed fetch wrapper with reactive signal integration.
- * Zero dependencies — native browser APIs only.
- */
-interface FetchOptions<T> extends Omit<RequestInit, 'signal'> {
-    base?: string;
-    params?: Record<string, string>;
-    timeout?: number;
-    transform?: (data: unknown) => T;
-}
-interface FetchResult<T> {
-    data: () => T | null;
-    error: () => Error | null;
-    loading: () => boolean;
-    refetch: () => Promise<void>;
-    abort: () => void;
-}
-/**
- * Create a reactive fetch that exposes data/error/loading as signals.
- *
- * If `url` is a signal getter (function), an effect auto-refetches when it
- * changes.
- *
- * ```ts
- * const { data, loading, error, refetch, abort } = createFetch<User[]>('/api/users');
- * ```
- */
-declare function createFetch<T>(url: string | (() => string), options?: FetchOptions<T>): FetchResult<T>;
-/**
- * One-shot fetch that returns parsed JSON.
- *
- * ```ts
- * const users = await fetchJSON<User[]>('/api/users');
- * ```
- */
-declare function fetchJSON<T>(url: string, options?: RequestInit): Promise<T>;
-
-/**
- * Forma HTTP - Server-Sent Events
- *
- * Reactive SSE wrapper with signal integration.
- * Zero dependencies — native browser APIs only.
- */
-interface SSEOptions<T = unknown> {
-    withCredentials?: boolean;
-    headers?: Record<string, string>;
-    /** Custom parser for incoming messages. Defaults to JSON.parse with raw data fallback. */
-    parse?: (data: string) => T;
-}
-interface SSEConnection<T = unknown> {
-    data: () => T | null;
-    error: () => Event | null;
-    connected: () => boolean;
-    close: () => void;
-    on(event: string, handler: (data: unknown) => void): () => void;
-}
-/**
- * Create a reactive Server-Sent Events connection.
- *
- * ```ts
- * const sse = createSSE<{ message: string }>('/api/events');
- * createEffect(() => {
- *   const msg = sse.data();
- *   if (msg) console.log(msg.message);
- * });
- * ```
- */
-declare function createSSE<T = unknown>(url: string, options?: SSEOptions<T>): SSEConnection<T>;
-
-/**
- * Forma HTTP - WebSocket
- *
- * Reactive WebSocket wrapper with auto-reconnect and signal integration.
- * Zero dependencies — native browser APIs only.
- */
-type WSStatus = 'connecting' | 'open' | 'closed' | 'error';
-interface WSOptions<TReceive = unknown> {
-    protocols?: string | string[];
-    reconnect?: boolean;
-    reconnectInterval?: number;
-    maxReconnects?: number;
-    /** Custom parser for incoming messages. Defaults to JSON.parse with raw data fallback. */
-    parse?: (data: string) => TReceive;
-}
-interface WSConnection<TSend = unknown, TReceive = unknown> {
-    data: () => TReceive | null;
-    status: () => WSStatus;
-    send(data: TSend): void;
-    close(): void;
-    on(handler: (data: TReceive) => void): () => void;
-}
-/**
- * Create a reactive WebSocket connection with auto-reconnect.
- *
- * ```ts
- * const ws = createWebSocket<string, ChatMessage>('wss://chat.example.com');
- * ws.send('hello');
- * createEffect(() => {
- *   const msg = ws.data();
- *   if (msg) console.log(msg);
- * });
- * ```
- */
-declare function createWebSocket<TSend = unknown, TReceive = unknown>(url: string, options?: WSOptions<TReceive>): WSConnection<TSend, TReceive>;
-
-/**
- * FormaJS Server - Action
- *
- * Creates an action that wraps a server function with optimistic UI support.
- * The action immediately applies an optimistic update, then reconciles when
- * the server responds (or rolls back on error).
- */
-
-interface ActionOptions<Args extends unknown[], Result> {
-    /**
-     * Apply an optimistic update immediately when the action is called.
-     * This runs BEFORE the server function.
-     * Store whatever you need to roll back in the return value or via closures.
-     */
-    optimistic?: (...args: Args) => void;
-    /**
-     * Called when the server function resolves successfully.
-     * Use this to apply the server result to local state.
-     */
-    onSuccess?: (result: Result, ...args: Args) => void;
-    /**
-     * Called when the server function rejects.
-     * Use this to roll back the optimistic update.
-     */
-    onError?: (error: unknown, ...args: Args) => void;
-    /**
-     * Resources to refetch after the action completes successfully.
-     * Used with single-flight mutations: if the server response includes
-     * revalidation data, these resources are updated without a refetch.
-     */
-    invalidates?: Resource<unknown>[];
-}
-interface Action<Args extends unknown[], Result> {
-    /** Execute the action. */
-    (...args: Args): Promise<Result>;
-    /** Whether the action is currently in-flight. */
-    pending: () => boolean;
-    /** The last error from the action (or undefined). */
-    error: () => unknown;
-    /** Clear the error state. */
-    clearError: () => void;
-}
-/**
- * Create an action that wraps a server function with optimistic UI.
- *
- * ```ts
- * const addTodo = createAction(
- *   serverCreateTodo,
- *   {
- *     optimistic: (text) => {
- *       // Immediately add to local list
- *       setTodos(prev => [...prev, { text, done: false, id: 'temp' }]);
- *     },
- *     onSuccess: (result) => {
- *       // Replace temp item with server result
- *       setTodos(prev => prev.map(t => t.id === 'temp' ? result : t));
- *     },
- *     onError: (err, text) => {
- *       // Remove the optimistic item
- *       setTodos(prev => prev.filter(t => t.id !== 'temp'));
- *     },
- *     invalidates: [todosResource],
- *   },
- * );
- *
- * // Use:
- * await addTodo('Buy milk');
- * ```
- */
-declare function createAction<Args extends unknown[], Result>(serverFn: (...args: Args) => Promise<Result>, options?: ActionOptions<Args, Result>): Action<Args, Result>;
-
-/**
- * FormaJS Server - Mutation
- *
- * Single-flight mutation pattern: the server response carries both the
- * mutation result AND fresh data for dependent resources in one round trip.
- *
- * Without single-flight:
- *   Client -> Server: createTodo("Buy milk")
- *   Server -> Client: { id: 1, text: "Buy milk" }
- *   Client -> Server: GET /api/todos (refetch to update list)
- *   Server -> Client: [all todos]
- *
- * With single-flight:
- *   Client -> Server: createTodo("Buy milk")
- *   Server -> Client: { data: {...}, __revalidate: { "/api/todos": [all todos] } }
- *   (No second request needed!)
- */
-
-interface MutationResponse<T> {
-    /** The mutation result. */
-    data: T;
-    /**
-     * Fresh data for dependent resources, keyed by resource identifier.
-     * When present, the client updates these resources directly instead of refetching.
-     */
-    __revalidate?: Record<string, unknown>;
-}
-/**
- * Register a resource with a key so it can be revalidated by single-flight mutations.
- *
- * ```ts
- * const todos = createResource(
- *   () => true,
- *   () => fetch('/api/todos').then(r => r.json()),
- * );
- * registerResource('/api/todos', todos);
- * ```
- */
-declare function registerResource(key: string, resource: Resource<unknown>): void;
-/**
- * Unregister a resource (call on cleanup/unmount).
- */
-declare function unregisterResource(key: string): void;
-/**
- * Apply revalidation data from a single-flight mutation response.
- * For each key in the revalidate map, find the matching resource
- * and mutate it directly with the fresh data (skipping a refetch).
- */
-declare function applyRevalidation(revalidateData: Record<string, unknown>): void;
-/**
- * Listen for revalidation events dispatched by $$serverFunction.
- * Call this once during app initialization to enable automatic
- * single-flight mutation handling.
- *
- * ```ts
- * // In your app entry:
- * import { enableAutoRevalidation } from 'forma/server/mutation';
- * enableAutoRevalidation();
- * ```
- */
-declare function enableAutoRevalidation(): () => void;
-/**
- * Wrap a server function response to include revalidation data.
- * Use this on the server side to enable single-flight mutations.
- *
- * ```ts
- * // Server-side:
- * async function createTodo(text: string) {
- *   "use server";
- *   const newTodo = await db.insert('todos', { text, done: false });
- *   const allTodos = await db.query('todos');
- *   return withRevalidation(newTodo, {
- *     '/api/todos': allTodos,
- *   });
- * }
- * ```
- */
-declare function withRevalidation<T>(data: T, revalidate: Record<string, unknown>): MutationResponse<T>;
-
-/**
- * FormaJS Server - RPC Client
- *
- * Provides the client-side stub function that replaces "use server" function
- * bodies after compilation. Each call becomes a fetch POST to the server endpoint.
- */
-/**
- * Create an RPC stub function for a server function.
- * This replaces the original function body on the client side.
- *
- * @param endpoint - The RPC endpoint path (e.g. "/rpc/createTodo_a1b2c3")
- * @returns An async function that sends args to the server and returns the result
- */
-declare function $$serverFunction<T extends (...args: unknown[]) => Promise<unknown>>(endpoint: string): T;
-
-/**
- * FormaJS Server - RPC Handler
- *
- * Server-side registry and request handler for "use server" functions.
- * Framework-agnostic — works with any Node.js HTTP server, Express, Hono, etc.
- */
-type ServerFunction = (...args: unknown[]) => Promise<unknown>;
-/**
- * Register a server function at a specific endpoint.
- * Called by the server-side compiled output.
- */
-declare function registerServerFunction(endpoint: string, fn: ServerFunction): void;
-/**
- * Get a registered server function by endpoint.
- */
-declare function getServerFunction(endpoint: string): ServerFunction | undefined;
-/**
- * Get all registered server function endpoints.
- */
-declare function getRegisteredEndpoints(): string[];
-interface RPCRequest {
-    args: unknown[];
-}
-interface RPCResponse {
-    data?: unknown;
-    error?: string;
-    __revalidate?: Record<string, unknown>;
-}
-declare function handleRPC(endpoint: string, body: RPCRequest, revalidateData?: Record<string, unknown>): Promise<RPCResponse>;
-/**
- * Create a middleware-style handler for use with Express-like frameworks.
- *
- * ```ts
- * import { createRPCMiddleware } from 'forma/server/rpc-handler';
- * app.use('/rpc', createRPCMiddleware());
- * ```
- */
-declare function createRPCMiddleware(): (req: {
-    url: string;
-    method: string;
-    body?: unknown;
-}, res: {
-    json: (data: unknown) => void;
-    status: (code: number) => {
-        json: (data: unknown) => void;
-    };
-}) => Promise<void>;
-
-export { $, $$, $$serverFunction, type Action, type ActionOptions, Fragment, type IslandHydrateFn, type MutationResponse, type RPCRequest, type RPCResponse, activateIslands, addClass, applyRevalidation, batch, children, cleanup, closest, createAction, createBus, createComputed, createContext, createEffect, createErrorBoundary, createFetch, createHistory, createIndexedDB, createList, createLocalStorage, createMemo, createPortal, createRPCMiddleware, createReducer, createRef, createResource, createRoot, createSSE, createSessionStorage, createShow, createStore, createSuspense, createSwitch, createText, createWebSocket, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, fragment, getRegisteredEndpoints, getServerFunction, h, handleRPC, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, registerResource, registerServerFunction, removeClass, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, untrack, withRevalidation };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, untrack };