@echojs-ecosystem/url-state 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+
+# @echojs-ecosystem/url-state
+
+**Type-safe URL search params — nuqs-style, signal-native.**
+
+[![npm](https://img.shields.io/npm/v/@echojs-ecosystem/url-state)](https://www.npmjs.com/package/@echojs-ecosystem/url-state)
+[![docs](https://img.shields.io/badge/docs-echojs.dev-blue)](https://echojs.dev/docs/packages/url-state)
+
+</div>
+
+---
+
+Manage **query string state** with typed parsers, defaults, and router integration. Built for EchoJS signals — no React hooks.
+
+## Features
+
+- **`createQueryParam`** — single typed param
+- **`createQueryParams`** — object of params with batch updates
+- **Rich parsers** — string, int, float, bool, literal, array, JSON + Standard Schema
+- **Router adapter** — auto-sync with `@echojs-ecosystem/router/hyperdom`
+- **History control** — `push` / `replace` per update
+- **`urlKeys`** — remap param names in the URL
+
+## Install
+
+```bash
+npm install @echojs-ecosystem/url-state @echojs-ecosystem/reactivity
+```
+
+## Quick start
+
+```ts
+import {
+  createQueryParams,
+  parseAsInteger,
+  parseAsString,
+  parseAsBoolean,
+} from "@echojs-ecosystem/url-state";
+
+const filters = createQueryParams({
+  q: parseAsString.withDefault(""),
+  page: parseAsInteger.withDefault(1),
+  inStock: parseAsBoolean.withDefault(false),
+});
+
+filters.value(); // { q: "", page: 1, inStock: false }
+filters.set({ q: "bike", page: 2 });
+filters.update((v) => ({ ...v, page: v.page + 1 }));
+filters.reset();
+```
+
+### With router
+
+```ts
+import { createRouter } from "@echojs-ecosystem/router/hyperdom";
+
+export const appRouter = createRouter({ routes });
+
+export const filters = appRouter.createQueryParams({
+  q: parseAsString.withDefault(""),
+  page: parseAsInteger.withDefault(1),
+});
+```
+
+## Parsers
+
+| Parser | Example |
+|--------|---------|
+| `parseAsString` | `?q=hello` |
+| `parseAsInteger` / `parseAsFloat` | `?page=2` |
+| `parseAsBoolean` | `?open=true` |
+| `parseAsLiteral(["a","b"])` | Enum values |
+| `parseAsArrayOf` | `?tag=a&tag=b` |
+| `parseAsJson(schema)` | Complex objects |
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| [`@echojs-ecosystem/router`](https://www.npmjs.com/package/@echojs-ecosystem/router) | SPA URL sync |
+| [`@echojs-ecosystem/reactivity`](https://www.npmjs.com/package/@echojs-ecosystem/reactivity) | Signal-backed param state |
+
+## Documentation
+
+[echojs.dev/docs/packages/url-state](https://echojs.dev/docs/packages/url-state)

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+import { ReadValue, Signal } from '@echojs-ecosystem/reactivity';
+
+type DebounceController = {
+    kind: "debounce";
+    ms: number;
+    schedule(fn: () => void): void;
+    cancel(): void;
+};
+declare const debounce: (ms: number) => DebounceController;
+
+type ThrottleController = {
+    kind: "throttle";
+    ms: number;
+    schedule(fn: () => void): void;
+    cancel(): void;
+};
+declare const throttle: (ms: number) => ThrottleController;
+
+type SearchParamValue = string | readonly string[] | null;
+
+type HistoryMode = "replace" | "push";
+/**
+ * Whether default values appear in the URL for the whole query-params group.
+ *
+ * - `"hide"` — defaults omitted (`?page=1` absent when default is `1`)
+ * - `"show"` — defaults serialized in the URL
+ */
+type DefaultVisibility = "hide" | "show";
+/** @deprecated Use {@link DefaultVisibility} */
+type DefaultVisibilityMode = DefaultVisibility;
+/** @deprecated Use {@link DefaultVisibility} */
+type DefaultInUrlBehavior = DefaultVisibility;
+/** @deprecated Use {@link DefaultVisibility} */
+type DefaultParamsBehavior = DefaultVisibility;
+type UrlStateAdapter = {
+    kind: string;
+    getSearch(): string;
+    setSearch(search: string, options?: {
+        history?: HistoryMode;
+        shallow?: boolean;
+        scroll?: boolean;
+    }): void;
+    subscribe(listener: () => void): () => void;
+};
+type QueryStateSetOptions = {
+    adapter?: UrlStateAdapter;
+    history?: HistoryMode;
+    shallow?: boolean;
+    scroll?: boolean;
+    defaultVisibility?: DefaultVisibility;
+    /** @deprecated Use {@link defaultVisibility} */
+    defaultParamsBehavior?: DefaultVisibility;
+    /** @deprecated Use {@link defaultVisibility} */
+    clearOnDefault?: boolean;
+    limitUrlUpdates?: ReturnType<typeof throttle> | ReturnType<typeof debounce> | false;
+    equals?: false | ((a: unknown, b: unknown) => boolean);
+};
+type QueryStateOptions = QueryStateSetOptions;
+type CreateQueryParamsOptions<Schema extends Record<string, QueryParamParser<any>>> = QueryStateOptions & {
+    urlKeys?: Partial<Record<keyof Schema, string>>;
+};
+type ParserMode = "single" | "multi";
+type Parser<Value> = {
+    parserMode?: ParserMode;
+    parse(value: SearchParamValue): Value | null;
+    serialize(value: Value): SearchParamValue;
+    /** Custom equality for `defaultVisibility: "hide"` (objects, arrays, …). */
+    eq?: (a: Value, b: Value) => boolean;
+    defaultValue?: Value | undefined;
+    options?: Partial<QueryStateOptions> | undefined;
+    withDefault(defaultValue: Value): ParserWithDefault<Value>;
+    withOptions(options: Partial<QueryStateOptions>): Parser<Value>;
+};
+/** Parser for repeated query keys (`?tag=a&tag=b`). */
+type MultiParser<Value> = Parser<Value> & {
+    parserMode: "multi";
+};
+type QueryParamParser<Value> = Parser<Value> | MultiParser<Value>;
+type ParserWithDefault<Value> = Parser<Value> & {
+    defaultValue: Value;
+};
+type ParsedValue<P> = P extends ParserWithDefault<infer Value> ? Value : P extends Parser<infer Value> ? Value | null : never;
+type ParsedSchema<Schema extends Record<string, QueryParamParser<any>>> = {
+    [K in keyof Schema]: ParsedValue<Schema[K]>;
+};
+type QueryParamState<Value> = {
+    kind: "query-param";
+    key: string;
+    value(): ReadValue<Value>;
+    set(value: Value | null, options?: QueryStateSetOptions): void;
+    update(updater: (value: ReadValue<Value>) => Value | null, options?: QueryStateSetOptions): void;
+    reset(options?: QueryStateSetOptions): void;
+    clear(options?: QueryStateSetOptions): void;
+    $value: Signal<Value>;
+    $rawValue: Signal<SearchParamValue>;
+    subscribe(listener: (value: ReadValue<Value>, prevValue: ReadValue<Value>) => void): () => void;
+};
+type QueryParamsState<Schema extends Record<string, QueryParamParser<any>>> = {
+    kind: "query-params";
+    value(): ReadValue<ParsedSchema<Schema>>;
+    set(value: Partial<ParsedSchema<Schema>> | null, options?: QueryStateSetOptions): void;
+    update(updater: (value: ReadValue<ParsedSchema<Schema>>) => Partial<ParsedSchema<Schema>> | null, options?: QueryStateSetOptions): void;
+    reset(options?: QueryStateSetOptions): void;
+    clear(options?: QueryStateSetOptions): void;
+    $value: Signal<ParsedSchema<Schema>>;
+    subscribe(listener: (value: ReadValue<ParsedSchema<Schema>>, prevValue: ReadValue<ParsedSchema<Schema>>) => void): () => void;
+};
+
+declare const createQueryParam: <Value>(key: string, parser: Parser<Value>, options?: QueryStateOptions) => QueryParamState<Value>;
+
+declare const createQueryParams: <Schema extends Record<string, Parser<any>>>(schema: Schema, options?: CreateQueryParamsOptions<Schema>) => QueryParamsState<Schema>;
+
+declare const createBrowserUrlStateAdapter: () => UrlStateAdapter;
+
+declare const createMemoryUrlStateAdapter: (initialSearch?: string) => UrlStateAdapter;
+
+type RouterLike = {
+    readonly $fullPath: {
+        value(): string;
+        subscribe(fn: () => void): () => void;
+    };
+    go(path: string, options?: {
+        replace?: boolean;
+    }): void;
+    replace?(path: string): void;
+};
+declare const createRouterUrlStateAdapter: (router: RouterLike) => UrlStateAdapter | undefined;
+
+type RouterBoundQueryParams = <Schema extends Record<string, Parser<any>>>(schema: Schema, options?: Omit<CreateQueryParamsOptions<Schema>, "adapter">) => QueryParamsState<Schema>;
+type RouterWithQueryParams<TRouter extends RouterLike> = TRouter & {
+    createQueryParams: RouterBoundQueryParams;
+};
+declare const attachRouterQueryParams: <TRouter extends RouterLike>(router: TRouter) => RouterWithQueryParams<TRouter>;
+
+declare const getUrlStateRouter: () => RouterLike | null;
+
+declare const parseAsString: Parser<string>;
+
+declare const parseAsInteger: Parser<number>;
+
+declare const parseAsFloat: Parser<number>;
+
+declare const parseAsBoolean: Parser<boolean>;
+
+declare const parseAsLiteral: <const Values extends readonly (string | number)[]>(values: Values) => Parser<Values[number]>;
+declare const parseAsStringLiteral: <const Values extends readonly string[]>(values: Values) => Parser<Values[number]>;
+declare const parseAsNumberLiteral: <const Values extends readonly number[]>(values: Values) => Parser<Values[number]>;
+
+/**
+ * Array serialized as repeated keys or a custom separator in one key (see second argument).
+ *
+ * For native `?tag=a&tag=b` only, prefer {@link parseAsNativeArrayOf}.
+ */
+declare const parseAsArrayOf: <Item>(item: Parser<Item>, separator?: string) => MultiParser<Item[]>;
+
+/**
+ * Native URL arrays via repeated keys: `?tag=a&tag=b`.
+ *
+ * @see https://nuqs.dev/docs/parsers/built-in#native-arrays
+ */
+declare const parseAsNativeArrayOf: <Item>(item: Parser<Item>) => ParserWithDefault<Item[]>;
+
+/** Minimal Standard Schema v1 shape (Zod 4, Valibot, ArkType, …). */
+type StandardSchemaLike<T = unknown> = {
+    "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<T>;
+    };
+};
+type StandardSchemaResult<T> = {
+    readonly value: T;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+    }>;
+};
+type JsonSchema<T> = StandardSchemaLike<T> | ((value: unknown) => T | null);
+
+/**
+ * JSON in a single query param. Optional Standard Schema (Zod, Valibot, …) or sync validator.
+ *
+ * @see https://nuqs.dev/docs/parsers/built-in#json
+ */
+declare const parseAsJson: <T = unknown>(schema?: JsonSchema<T>) => Parser<T>;
+
+type CustomParserConfig<Value> = {
+    parse: (value: SearchParamValue) => Value | null;
+    serialize: (value: Value) => SearchParamValue;
+    /** Used for `defaultVisibility: "hide"` equality checks (like nuqs `eq`). */
+    eq?: (a: Value, b: Value) => boolean;
+};
+declare const createCustomParser: <Value>(config: CustomParserConfig<Value>) => Parser<Value>;
+
+type CustomMultiParserConfig<Value> = {
+    parse: (values: readonly string[]) => Value | null;
+    serialize: (value: Value) => readonly string[];
+    eq?: (a: Value, b: Value) => boolean;
+};
+declare const createCustomMultiParser: <Value>(config: CustomMultiParserConfig<Value>) => MultiParser<Value>;
+declare const isMultiParser: <Value>(parser: {
+    parserMode?: string;
+}) => parser is MultiParser<Value>;
+
+declare const parseAsIsoDate: Parser<Date>;
+
+declare const parseAsTimestamp: Parser<number>;
+
+export { type CustomMultiParserConfig, type CustomParserConfig, type DefaultInUrlBehavior, type DefaultParamsBehavior, type DefaultVisibility, type DefaultVisibilityMode, type JsonSchema, type MultiParser, type Parser, type ParserMode, type ParserWithDefault, type QueryParamParser, type QueryParamState, type QueryParamsState, type QueryStateOptions, type QueryStateSetOptions, type RouterBoundQueryParams, type RouterLike, type RouterWithQueryParams, type StandardSchemaLike, type UrlStateAdapter, attachRouterQueryParams, createBrowserUrlStateAdapter, createCustomMultiParser, createCustomParser, createMemoryUrlStateAdapter, createQueryParam, createQueryParams, createRouterUrlStateAdapter, debounce, getUrlStateRouter, isMultiParser, parseAsArrayOf, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsIsoDate, parseAsJson, parseAsLiteral, parseAsNativeArrayOf, parseAsNumberLiteral, parseAsString, parseAsStringLiteral, parseAsTimestamp, throttle };