seitu 0.12.1 → 0.13.0

package/dist/core-BKImMfak.mjs

@@ -0,0 +1,308 @@
+//#region src/core/subscription.ts
+function createReadableSubscription(get, subscribe, notify) {
+	return {
+		get,
+		subscribe(callback, options) {
+			return subscribe(() => callback(get()), options);
+		},
+		"~": {
+			output: null,
+			notify
+		}
+	};
+}
+function createSubscription(options) {
+	const subscribers = /* @__PURE__ */ new Set();
+	const notify = () => subscribers.forEach((cb) => cb());
+	let onEmpty;
+	return {
+		subscribe(callback, opts) {
+			if (subscribers.size === 0 && options?.onFirstSubscribe) onEmpty = options.onFirstSubscribe() ?? void 0;
+			if (opts?.immediate) callback();
+			subscribers.add(callback);
+			return () => {
+				subscribers.delete(callback);
+				if (subscribers.size === 0) {
+					onEmpty?.();
+					onEmpty = void 0;
+				}
+			};
+		},
+		notify
+	};
+}
+//#endregion
+//#region src/core/computed.ts
+function createComputed(source, transform) {
+	const sources = Array.isArray(source) ? source : [source];
+	const isSingle = !Array.isArray(source);
+	const { subscribe, notify } = createSubscription({ onFirstSubscribe() {
+		const unsubscribes = sources.map((s) => s.subscribe(() => notify()));
+		return () => unsubscribes.forEach((u) => u());
+	} });
+	const get = () => transform(isSingle ? sources[0].get() : sources.map((s) => s.get()));
+	return createReadableSubscription(get, subscribe, notify);
+}
+//#endregion
+//#region src/core/debounced.ts
+/**
+* Creates a debounced readable that delays updates from a source subscribable.
+*
+* The debounced store will only emit the latest value after `wait` milliseconds
+* of inactivity from the source.
+*
+* @example
+* ```ts twoslash
+* import { createStore, createDebounced } from 'seitu'
+*
+* const store = createStore('')
+* const debounced = createDebounced(store, 300)
+* debounced.subscribe(value => console.log('debounced:', value))
+* ```
+*/
+function createDebounced(source, wait) {
+	let state = source.get();
+	let timeoutId;
+	const { subscribe, notify } = createSubscription({ onFirstSubscribe() {
+		const unsubscribe = source.subscribe(() => {
+			clearTimeout(timeoutId);
+			timeoutId = setTimeout(() => {
+				state = source.get();
+				notify();
+			}, wait);
+		});
+		return () => {
+			clearTimeout(timeoutId);
+			unsubscribe();
+		};
+	} });
+	const get = () => state;
+	return createReadableSubscription(get, subscribe, notify);
+}
+//#endregion
+//#region src/core/debounced-fn.ts
+/**
+* Wraps a plain function in a debounced callable that also acts as a subscribable.
+*
+* Each call resets the debounce timer. When the timer fires, the wrapped function
+* is invoked and its return value becomes the current state, notifying subscribers.
+*
+* @example
+* ```ts twoslash
+* import { createDebouncedFn } from 'seitu'
+*
+* const search = createDebouncedFn((query: string) => fetch(`/api?q=${query}`), 300)
+* search.subscribe(result => console.log('result:', result))
+* search('hello') // debounced — fires after 300ms of inactivity
+* search.get() // latest return value (undefined until first call)
+* ```
+*/
+function createDebouncedFn(fn, wait) {
+	let state;
+	let timeoutId;
+	const { subscribe, notify } = createSubscription();
+	const get = () => state;
+	return Object.assign((...args) => {
+		clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			state = fn(...args);
+			notify();
+		}, wait);
+	}, createReadableSubscription(get, subscribe, notify));
+}
+//#endregion
+//#region src/utils.ts
+function tryParseJson(value) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+}
+//#endregion
+//#region src/validate.ts
+function validateSchema(schema, value, options) {
+	const parsed = tryParseJson(value);
+	const result = schema["~standard"].validate(parsed);
+	if (result instanceof Promise) throw new TypeError(`[${options.label}] Validation schema should not return a Promise.`);
+	if (!result.issues) return result.value;
+	if (options.onError) {
+		const corrected = options.onError(result.issues, parsed);
+		if (corrected !== void 0) {
+			const validated = schema["~standard"].validate(corrected);
+			if (validated instanceof Promise) throw new TypeError(`[${options.label}] Validation schema should not return a Promise.`);
+			if (validated.issues) console.warn(`[${options.label}] Returned value invalid, returned default value instead`, JSON.stringify(validated.issues, null, 2), { cause: validated.issues });
+			else return validated.value;
+		}
+	} else console.warn(`[${options.label}] Returned value invalid, returned default value instead`, JSON.stringify(result.issues, null, 2), { cause: result.issues });
+	return options.defaultValue;
+}
+//#endregion
+//#region src/core/schema-store.ts
+/**
+* Creates a reactive schema store: state is validated on read, supports partial `set`, and
+* falls back to default values when validation fails.
+*
+* @example
+* ```ts twoslash
+* import { createSchemaStore } from 'seitu'
+* import * as z from 'zod'
+*
+* const store = createSchemaStore({
+*   schema: z.object({ count: z.number(), name: z.string() }),
+*   defaultValue: { count: 0, name: '' },
+* })
+* store.get()
+* store.set({ count: 1, name: 'alice' })
+* store.subscribe(console.log)
+* ```
+*/
+function createSchemaStore(options) {
+	const store = createStore(options.defaultValue);
+	const get = () => {
+		const stored = store.get();
+		return validateSchema(options.schema, stored, {
+			defaultValue: options.defaultValue,
+			label: "createSchemaStore",
+			onError: options.onValidationError ? (issues, parsed) => options.onValidationError({
+				issues: [...issues],
+				value: parsed,
+				defaultValue: options.defaultValue
+			}) : void 0
+		});
+	};
+	return {
+		...createReadableSubscription(get, store.subscribe, store["~"].notify),
+		set: (value) => {
+			const newValue = typeof value === "function" ? value(get()) : value;
+			store.set(newValue);
+		}
+	};
+}
+//#endregion
+//#region src/core/store.ts
+/**
+* Creates a simple reactive store (minimal TanStack Store-style API).
+*
+* - **Standalone**: use `get()`, `set(value | updater)`, `subscribe(callback)` for any state.
+* - **With schema-store**: use as the state backing for a memory provider.
+*
+* @example
+* ```ts twoslash
+* import { createStore } from 'seitu'
+*
+* const store = createStore({ count: 0 })
+* store.set(prev => ({ ...prev, count: prev.count + 1 }))
+* store.subscribe(state => console.log(state))
+* store.get() // { count: 0 }
+* ```
+*/
+function createStore(initial) {
+	let state = initial;
+	const { subscribe, notify } = createSubscription();
+	const get = () => state;
+	return {
+		...createReadableSubscription(get, subscribe, notify),
+		set: (value) => {
+			const next = typeof value === "function" ? value(state) : value;
+			if (next === state) return;
+			state = next;
+			notify();
+		}
+	};
+}
+//#endregion
+//#region src/core/throttled.ts
+/**
+* Creates a throttled readable that rate-limits updates from a source subscribable.
+*
+* Emits the latest value at most once every `wait` milliseconds. The first update
+* fires immediately, then subsequent updates are batched until the interval elapses.
+*
+* @example
+* ```ts twoslash
+* import { createStore, createThrottled } from 'seitu'
+*
+* const store = createStore('')
+* const throttled = createThrottled(store, 300)
+* throttled.subscribe(value => console.log('throttled:', value))
+* ```
+*/
+function createThrottled(source, wait) {
+	let state = source.get();
+	let timeoutId;
+	let hasTrailing = false;
+	const { subscribe, notify } = createSubscription({ onFirstSubscribe() {
+		const unsubscribe = source.subscribe(() => {
+			if (timeoutId) {
+				hasTrailing = true;
+				return;
+			}
+			state = source.get();
+			notify();
+			timeoutId = setTimeout(() => {
+				timeoutId = void 0;
+				if (hasTrailing) {
+					hasTrailing = false;
+					state = source.get();
+					notify();
+				}
+			}, wait);
+		});
+		return () => {
+			clearTimeout(timeoutId);
+			timeoutId = void 0;
+			hasTrailing = false;
+			unsubscribe();
+		};
+	} });
+	const get = () => state;
+	return createReadableSubscription(get, subscribe, notify);
+}
+//#endregion
+//#region src/core/throttled-fn.ts
+/**
+* Wraps a plain function in a throttled callable that also acts as a subscribable.
+*
+* The first call fires immediately. Subsequent calls within the `wait` window are
+* batched — only the last one fires when the interval elapses. The return value of
+* the wrapped function becomes the current state, notifying subscribers.
+*
+* @example
+* ```ts twoslash
+* import { createThrottledFn } from 'seitu'
+*
+* const log = createThrottledFn((msg: string) => console.log(msg), 300)
+* log.subscribe(result => console.log('result:', result))
+* log('hello') // fires immediately
+* log('world') // throttled — fires after 300ms
+* log.get() // latest return value (undefined until first call)
+* ```
+*/
+function createThrottledFn(fn, wait) {
+	let state;
+	let timeoutId;
+	let trailingArgs;
+	const { subscribe, notify } = createSubscription();
+	const get = () => state;
+	return Object.assign((...args) => {
+		if (timeoutId) {
+			trailingArgs = args;
+			return;
+		}
+		state = fn(...args);
+		notify();
+		timeoutId = setTimeout(() => {
+			timeoutId = void 0;
+			if (trailingArgs) {
+				const args = trailingArgs;
+				trailingArgs = void 0;
+				state = fn(...args);
+				notify();
+			}
+		}, wait);
+	}, createReadableSubscription(get, subscribe, notify));
+}
+//#endregion
+export { validateSchema as a, createDebounced as c, createSubscription as d, createSchemaStore as i, createComputed as l, createThrottled as n, tryParseJson as o, createStore as r, createDebouncedFn as s, createThrottledFn as t, createReadableSubscription as u };

package/dist/core.d.mts

@@ -0,0 +1,2 @@
+import { S as createSubscription, _ as Readable, a as Store, b as Writable, c as SchemaStoreOptions, d as createDebouncedFn, f as Debounced, g as Clearable, h as createComputed, i as createThrottled, l as createSchemaStore, m as Computed, n as createThrottledFn, o as createStore, p as createDebounced, r as Throttled, s as SchemaStore, t as ThrottledFn, u as DebouncedFn, v as Subscribable, x as createReadableSubscription, y as SubscribeOptions } from "./index-ChvHgGIa.mjs";
+export { Clearable, Computed, Debounced, DebouncedFn, Readable, SchemaStore, SchemaStoreOptions, Store, Subscribable, SubscribeOptions, Throttled, ThrottledFn, Writable, createComputed, createDebounced, createDebouncedFn, createReadableSubscription, createSchemaStore, createStore, createSubscription, createThrottled, createThrottledFn };

package/dist/core.mjs

@@ -0,0 +1,2 @@
+import { c as createDebounced, d as createSubscription, i as createSchemaStore, l as createComputed, n as createThrottled, r as createStore, s as createDebouncedFn, t as createThrottledFn, u as createReadableSubscription } from "./core-BKImMfak.mjs";
+export { createComputed, createDebounced, createDebouncedFn, createReadableSubscription, createSchemaStore, createStore, createSubscription, createThrottled, createThrottledFn };

package/dist/index-ChvHgGIa.d.mts

@@ -0,0 +1,207 @@
+import { i as StandardSchemaV1, r as ValidationSchemaOutput, t as ValidationSchemaErrorProps } from "./validate-BzLxGOQt.mjs";
+
+//#region src/core/subscription.d.ts
+interface SubscribeOptions {
+  /**
+   * When `true`, the callback is invoked immediately with the current value upon subscribing.
+   */
+  immediate?: boolean;
+}
+interface Subscribable<V> {
+  'subscribe': (callback: (value: V) => any, options?: SubscribeOptions) => () => void;
+  '~': {
+    /**
+     * Type type with returned value of the subscription.
+     */
+    output: V;
+    /**
+     * A function that notifies all subscribers that the value has changed.
+     */
+    notify: () => void;
+  };
+}
+interface Readable<T> {
+  get: () => T;
+}
+interface Writable<T, P = T> {
+  set: (value: T | ((prev: P) => T)) => any;
+}
+interface Clearable {
+  clear: () => void;
+}
+declare function createReadableSubscription<T>(get: () => T, subscribe: (callback: () => any, options?: SubscribeOptions) => () => void, notify: () => void): Readable<T> & Subscribable<T>;
+declare function createSubscription(options?: {
+  onFirstSubscribe?: () => (void | (() => void));
+}): {
+  subscribe: (callback: () => any, options?: SubscribeOptions) => () => void;
+  notify: () => void;
+};
+//#endregion
+//#region src/core/computed.d.ts
+interface Computed<T> extends Readable<T>, Subscribable<T> {}
+type Source<T = unknown> = Readable<T> & Subscribable<T>;
+type SourceValues<S extends readonly Source[]> = { [K in keyof S]: S[K] extends Source<infer V> ? V : never };
+/**
+ * Creates a computed (derived) subscription from a subscription or an array of subscriptions.
+ * The computed value is updated whenever any subscription updates.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createComputed, createStore } from 'seitu'
+ *
+ * const count = createStore({ a: 1, b: 2 })
+ * const sum = createComputed(count, s => s.a + s.b)
+ * sum.get() // 3
+ * ```
+ *
+ * @example
+ * ```ts twoslash
+ * import { createComputed, createStore } from 'seitu'
+ *
+ * const a = createStore(1)
+ * const b = createStore(2)
+ * const sum = createComputed([a, b], ([a, b]) => a + b)
+ * sum.get() // 3
+ * ```
+ */
+declare function createComputed<S extends readonly Source[], R>(sources: [...S], transform: (values: SourceValues<S>) => R): Computed<R>;
+declare function createComputed<T, R>(source: Source<T>, transform: (value: T) => R): Computed<R>;
+//#endregion
+//#region src/core/debounced.d.ts
+interface Debounced<T> extends Readable<T>, Subscribable<T> {}
+/**
+ * Creates a debounced readable that delays updates from a source subscribable.
+ *
+ * The debounced store will only emit the latest value after `wait` milliseconds
+ * of inactivity from the source.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createStore, createDebounced } from 'seitu'
+ *
+ * const store = createStore('')
+ * const debounced = createDebounced(store, 300)
+ * debounced.subscribe(value => console.log('debounced:', value))
+ * ```
+ */
+declare function createDebounced<T>(source: Readable<T> & Subscribable<T>, wait: number): Debounced<T>;
+//#endregion
+//#region src/core/debounced-fn.d.ts
+interface DebouncedFn<F extends (...args: any[]) => any> extends Readable<ReturnType<F> | undefined>, Subscribable<ReturnType<F> | undefined> {
+  (...args: Parameters<F>): void;
+}
+/**
+ * Wraps a plain function in a debounced callable that also acts as a subscribable.
+ *
+ * Each call resets the debounce timer. When the timer fires, the wrapped function
+ * is invoked and its return value becomes the current state, notifying subscribers.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createDebouncedFn } from 'seitu'
+ *
+ * const search = createDebouncedFn((query: string) => fetch(`/api?q=${query}`), 300)
+ * search.subscribe(result => console.log('result:', result))
+ * search('hello') // debounced — fires after 300ms of inactivity
+ * search.get() // latest return value (undefined until first call)
+ * ```
+ */
+declare function createDebouncedFn<F extends (...args: any[]) => any>(fn: F, wait: number): DebouncedFn<F>;
+//#endregion
+//#region src/core/schema-store.d.ts
+interface SchemaStore<O> extends Subscribable<O>, Readable<O>, Writable<O, O> {}
+interface SchemaStoreOptions<S extends StandardSchemaV1<unknown>> {
+  schema: S;
+  defaultValue: ValidationSchemaOutput<S>;
+  /**
+   * Handle validation errors.
+   *
+   * If returns a value, it will be validated and used as the store value.
+   * If returns undefined, the default value will be returned.
+   */
+  onValidationError?: (props: ValidationSchemaErrorProps<ValidationSchemaOutput<S>>) => void | ValidationSchemaOutput<S>;
+}
+/**
+ * Creates a reactive schema store: state is validated on read, supports partial `set`, and
+ * falls back to default values when validation fails.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createSchemaStore } from 'seitu'
+ * import * as z from 'zod'
+ *
+ * const store = createSchemaStore({
+ *   schema: z.object({ count: z.number(), name: z.string() }),
+ *   defaultValue: { count: 0, name: '' },
+ * })
+ * store.get()
+ * store.set({ count: 1, name: 'alice' })
+ * store.subscribe(console.log)
+ * ```
+ */
+declare function createSchemaStore<S extends StandardSchemaV1<unknown>>(options: SchemaStoreOptions<S>): SchemaStore<ValidationSchemaOutput<S>>;
+//#endregion
+//#region src/core/store.d.ts
+interface Store<T> extends Readable<T>, Writable<T, T>, Subscribable<T> {}
+/**
+ * Creates a simple reactive store (minimal TanStack Store-style API).
+ *
+ * - **Standalone**: use `get()`, `set(value | updater)`, `subscribe(callback)` for any state.
+ * - **With schema-store**: use as the state backing for a memory provider.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createStore } from 'seitu'
+ *
+ * const store = createStore({ count: 0 })
+ * store.set(prev => ({ ...prev, count: prev.count + 1 }))
+ * store.subscribe(state => console.log(state))
+ * store.get() // { count: 0 }
+ * ```
+ */
+declare function createStore<T>(initial: T): Store<T>;
+//#endregion
+//#region src/core/throttled.d.ts
+interface Throttled<T> extends Readable<T>, Subscribable<T> {}
+/**
+ * Creates a throttled readable that rate-limits updates from a source subscribable.
+ *
+ * Emits the latest value at most once every `wait` milliseconds. The first update
+ * fires immediately, then subsequent updates are batched until the interval elapses.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createStore, createThrottled } from 'seitu'
+ *
+ * const store = createStore('')
+ * const throttled = createThrottled(store, 300)
+ * throttled.subscribe(value => console.log('throttled:', value))
+ * ```
+ */
+declare function createThrottled<T>(source: Readable<T> & Subscribable<T>, wait: number): Throttled<T>;
+//#endregion
+//#region src/core/throttled-fn.d.ts
+interface ThrottledFn<F extends (...args: any[]) => any> extends Readable<ReturnType<F> | undefined>, Subscribable<ReturnType<F> | undefined> {
+  (...args: Parameters<F>): void;
+}
+/**
+ * Wraps a plain function in a throttled callable that also acts as a subscribable.
+ *
+ * The first call fires immediately. Subsequent calls within the `wait` window are
+ * batched — only the last one fires when the interval elapses. The return value of
+ * the wrapped function becomes the current state, notifying subscribers.
+ *
+ * @example
+ * ```ts twoslash
+ * import { createThrottledFn } from 'seitu'
+ *
+ * const log = createThrottledFn((msg: string) => console.log(msg), 300)
+ * log.subscribe(result => console.log('result:', result))
+ * log('hello') // fires immediately
+ * log('world') // throttled — fires after 300ms
+ * log.get() // latest return value (undefined until first call)
+ * ```
+ */
+declare function createThrottledFn<F extends (...args: any[]) => any>(fn: F, wait: number): ThrottledFn<F>;
+//#endregion
+export { createSubscription as S, Readable as _, Store as a, Writable as b, SchemaStoreOptions as c, createDebouncedFn as d, Debounced as f, Clearable as g, createComputed as h, createThrottled as i, createSchemaStore as l, Computed as m, createThrottledFn as n, createStore as o, createDebounced as p, Throttled as r, SchemaStore as s, ThrottledFn as t, DebouncedFn as u, Subscribable as v, createReadableSubscription as x, SubscribeOptions as y };

package/dist/{react/hooks.d.ts → react.d.mts}

@@ -1,9 +1,11 @@
-import type { Readable, Subscribable } from '../core/index';
-import * as React from 'react';
-export interface UseSubscriptionOptions<S extends Subscribable<any> & Readable<any>, R = S['~']['output']> {
-    selector?: (value: S['~']['output']) => R;
-    deps?: React.DependencyList;
-    isEqual?: (prev: R, next: R) => boolean;
+import { _ as Readable, v as Subscribable } from "./index-ChvHgGIa.mjs";
+import * as React$1 from "react";
+
+//#region src/react/hooks.d.ts
+interface UseSubscriptionOptions<S extends Subscribable<any> & Readable<any>, R = S['~']['output']> {
+  selector?: (value: S['~']['output']) => R;
+  deps?: React$1.DependencyList;
+  isEqual?: (prev: R, next: R) => boolean;
 }
 /**
  * Use this hook to subscribe to a reactive value. Accepts a subscription object
@@ -95,4 +97,68 @@ export interface UseSubscriptionOptions<S extends Subscribable<any> & Readable<a
  * }
  * ```
  */
-export declare function useSubscription<S extends Subscribable<any> & Readable<any>, R = S['~']['output']>(source: S | (() => S), options?: UseSubscriptionOptions<S, R>): R;
+declare function useSubscription<S extends Subscribable<any> & Readable<any>, R = S['~']['output']>(source: S | (() => S), options?: UseSubscriptionOptions<S, R>): R;
+//#endregion
+//#region src/react/components.d.ts
+interface SubscriptionProps<S extends Subscribable<any> & Readable<any>, R = S['~']['output']> extends Pick<UseSubscriptionOptions<S, R>, 'selector'> {
+  value: S;
+  children: (value: R) => React.ReactNode;
+}
+/**
+ * Declarative component that subscribes to a reactive value and passes it to a render function.
+ * Re-renders when the value (or selected value) changes. Use when you prefer a component API
+ * over the useSubscription hook.
+ *
+ * @example Basic usage
+ * ```tsx twoslash title="/app/page.tsx"
+ * 'use client'
+ *
+ * import { createWebStorage } from 'seitu/web'
+ * import { Subscription } from 'seitu/react'
+ * import * as z from 'zod'
+ *
+ * const sessionStorage = createWebStorage({
+ *   type: 'sessionStorage',
+ *   schemas: { count: z.number(), name: z.string() },
+ *   defaultValues: { count: 0, name: '' },
+ * })
+ *
+ * export default function Page() {
+ *   return (
+ *     <Subscription value={sessionStorage}>
+ *       {(value) => <div>{value.count}</div>}
+ *     </Subscription>
+ *   )
+ * }
+ * ```
+ *
+ * @example With selector
+ * ```tsx twoslash title="/app/page.tsx"
+ * 'use client'
+ *
+ * import { createWebStorage } from 'seitu/web'
+ * import { Subscription } from 'seitu/react'
+ * import * as z from 'zod'
+ *
+ * const sessionStorage = createWebStorage({
+ *   type: 'sessionStorage',
+ *   schemas: { count: z.number(), name: z.string() },
+ *   defaultValues: { count: 0, name: '' },
+ * })
+ *
+ * export default function Page() {
+ *   return (
+ *     <Subscription value={sessionStorage} selector={(v) => v.count}>
+ *       {(count) => <div>{count}</div>}
+ *     </Subscription>
+ *   )
+ * }
+ * ```
+ */
+declare function Subscription<S extends Subscribable<any> & Readable<any>, R = S['~']['output']>({
+  value,
+  selector,
+  children
+}: SubscriptionProps<S, R>): React$1.ReactNode;
+//#endregion
+export { Subscription, SubscriptionProps, UseSubscriptionOptions, useSubscription };