stateshape 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+type EventCallback<T> = (payload: T) => boolean | undefined | void;
+
+type EventCallbackMap<Map extends Record<string, unknown>> = Partial<{ [K in keyof Map]: Set<EventCallback<Map[K]>> }>;
+
+declare class EventEmitter<P extends Record<string, unknown> = Record<string, void>> {
+  _callbacks: EventCallbackMap<P>;
+  _active: boolean;
+  /**
+   * Adds an event handler.
+   *
+   * Returns an unsubscription function. Once it's invoked, the given
+   * `callback` is removed and no longer called in response to the event.
+   */
+  on<E extends string>(event: E, callback: EventCallback<P[E]>): () => void;
+  /**
+   * Adds a one-time event handler: once the event is emitted, the callback
+   * is called and immediately removed.
+   */
+  once<E extends string>(event: E, callback: EventCallback<P[E]>): () => void;
+  /**
+   * Removes the specified `callback` from the handlers of the given event,
+   * and removes all handlers of the given event if `callback` is not
+   * specified.
+   */
+  off<E extends string>(event: E, callback?: EventCallback<P[E]>): void;
+  /**
+   * Emits the specified event. Returns `false` if at least one event callback
+   * returns `false`, effectively interrupting the callback call chain.
+   * Otherwise returns `true`.
+   */
+  emit<E extends string>(event: E, payload?: P[E]): boolean;
+  get active(): boolean;
+  start(): void;
+  stop(): void;
+}
+
+type StateUpdate<T> = (value: T) => T;
+type StateUpdatePayload<T> = {
+  previous: T;
+  current: T;
+};
+type StatePayloadMap<T> = Record<string, void> & {
+  update: StateUpdatePayload<T>;
+  set: StateUpdatePayload<T>;
+  start: void;
+  stop: void;
+};
+type StateOptions = {
+  /**
+   * Whether to call `start()` at initialization.
+   * @default true
+   */
+  autoStart?: boolean;
+};
+/**
+ * Data container allowing for subscription to its updates.
+ */
+declare class State<T, P extends StatePayloadMap<T> = StatePayloadMap<T>> extends EventEmitter<P> {
+  _value: T;
+  _revision: number;
+  _active: boolean;
+  _queue: (() => void)[];
+  constructor(value: T, options?: StateOptions);
+  _init(): void;
+  _call(callback: () => void): void;
+  on<E extends string>(event: E, callback: EventCallback<P[E]>): () => void;
+  getValue(): T;
+  /**
+   * Updates the state value.
+   *
+   * @param update - A new value or an update function `(value) => nextValue`
+   * that returns a new state value based on the current state value.
+   */
+  setValue(update: T | StateUpdate<T>): void;
+  _resolveValue(update: T | StateUpdate<T>): T;
+  _assignValue(value: T): void;
+  get revision(): number;
+  start(): void;
+}
+
+/**
+ * Serves as an alternative to `instanceof State` which can lead to a false
+ * negative when `State` comes from a transitive dependency.
+ */
+declare function isState<T, P extends StatePayloadMap<T> = StatePayloadMap<T>>(x: unknown): x is State<T, P>;
+
+type PersistentStorage<T> = {
+  read: () => T | null | Promise<T | null>;
+  write?: (value: T) => void | Promise<void>;
+};
+
+type StorageEntryOptions<T> = {
+  key: string;
+  session?: boolean;
+  serialize?: (value: T) => string;
+  deserialize?: (serializedValue: string) => T;
+};
+declare function getStorageEntry<T>({
+  key,
+  session,
+  serialize,
+  deserialize
+}: StorageEntryOptions<T>): PersistentStorage<T>;
+type PersistentStatePayloadMap<T> = StatePayloadMap<T> & {
+  sync: void;
+  synconce: void;
+  effect: void;
+};
+/**
+ * A container for data persistent across page reloads.
+ */
+declare class PersistentState<T, P extends PersistentStatePayloadMap<T> = PersistentStatePayloadMap<T>> extends State<T, P> {
+  /**
+   * @param value - Initial state value.
+   * @param options - Either of the following:
+   * - A set of browser storage settings: `key` points to the target browser
+   * storage key where the state value should be saved; `session` set to `true`
+   * signals to use `sessionStorage` instead of `localStorage`, with the latter
+   * being the default; the optional `serialize` and `deserialize` define the
+   * way the state value is saved to and restored from the browser storage
+   * entry (default: `JSON.stringify` and `JSON.parse` respectively).
+   * - A storage singleton with a `read` and an optional `write` method
+   * (synchronous or asynchronous).
+   */
+  constructor(value: T, options: (StorageEntryOptions<T> | PersistentStorage<T>) & StateOptions);
+}
+
+type URLComponents = {
+  params?: Record<string, unknown> | undefined;
+  query?: Record<string, unknown> | undefined;
+};
+
+type URLSchema = StandardSchemaV1<URLComponents>;
+
+type LocationObject = {
+  _schema: URLSchema | undefined;
+  exec: (x: string) => URLComponents | null;
+  compile: (x: any) => string;
+  toString: () => string;
+};
+
+type URLConfigShape = {
+  strict?: boolean;
+};
+interface URLConfig extends URLConfigShape {}
+
+type LocationValue = URLConfig["strict"] extends true ? LocationObject | undefined : string | LocationObject | undefined;
+
+type LocationPattern = URLConfig["strict"] extends true ? LocationValue | LocationValue[] : LocationValue | RegExp | (LocationValue | RegExp)[];
+
+type MatchState<P extends LocationPattern> = {
+  ok: boolean;
+  href: string;
+  params: P extends {
+    _schema: URLSchema;
+  } ? StandardSchemaV1.InferOutput<P["_schema"]> extends {
+    params?: Record<string, unknown>;
+  } ? StandardSchemaV1.InferOutput<P["_schema"]>["params"] : Record<string, never> : Record<string, string | undefined>;
+  query: P extends {
+    _schema: URLSchema;
+  } ? StandardSchemaV1.InferOutput<P["_schema"]> extends {
+    query?: Record<string, unknown>;
+  } ? StandardSchemaV1.InferOutput<P["_schema"]>["query"] : Record<string, never> : Record<string, string | undefined>;
+};
+
+type MatchHandler<P extends LocationPattern, T> = (payload: MatchState<P>) => T;
+
+type NavigationOptions<Href = string> = {
+  target?: string;
+  href?: Href;
+  referrer?: Href;
+  spa?: "auto" | "off" | undefined;
+  history?: "push" | "replace" | undefined;
+  scroll?: "auto" | "off" | undefined;
+  id?: string;
+  source?: "popstate" | undefined;
+};
+
+type URLData<T extends LocationValue = LocationValue> = T extends {
+  _schema: URLSchema;
+} ? StandardSchemaV1.InferOutput<T["_schema"]> : URLComponents;
+
+type URLStatePayloadMap = StatePayloadMap<string> & {
+  navigationstart: NavigationOptions;
+  navigation: NavigationOptions;
+  navigationcomplete: NavigationOptions;
+};
+declare class URLState extends State<string, URLStatePayloadMap> {
+  constructor(href?: string | null, options?: StateOptions);
+  _init(): void;
+  on<E extends string>(event: E, callback: EventCallback<URLStatePayloadMap[E]>, invokeImmediately?: boolean): () => void;
+  getValue(): string;
+  setValue(update: string | StateUpdate<string>, options?: NavigationOptions): void;
+  _transition(options?: NavigationOptions): boolean | void | undefined;
+  _complete(options?: NavigationOptions): boolean | void | undefined;
+  toValue(x: string): string;
+}
+
+type ContainerElement = Document | Element | null | undefined;
+type ElementCollection = (string | Node)[] | HTMLCollection | NodeList;
+type ObservedElement = string | Node | (string | Node)[] | HTMLCollection | NodeList;
+declare class Route extends URLState {
+  _clicks: Set<(event: MouseEvent) => void>;
+  constructor(href?: LocationValue | null, options?: StateOptions);
+  _init(): void;
+  observe(container: ContainerElement | (() => ContainerElement), elements?: ObservedElement): () => void;
+  navigate(options?: NavigationOptions<LocationValue>): void;
+  assign(url: LocationValue): void;
+  replace(url: LocationValue): void;
+  reload(): void;
+  go(delta: number): void;
+  back(): void;
+  forward(): void;
+  get href(): string;
+  set href(value: LocationValue);
+  get pathname(): string;
+  set pathname(value: LocationValue);
+  get search(): string;
+  set search(value: string | URLSearchParams);
+  get hash(): string;
+  set hash(value: string);
+  toString(): string;
+  /**
+   * Matches the current location against `urlPattern`.
+   */
+  match<P extends LocationPattern>(urlPattern: P): MatchState<P>;
+  /**
+   * Compiles `urlPattern` to a URL string by filling out the parameters
+   * based on `data`.
+   */
+  compile<T extends LocationValue>(urlPattern: T, data?: URLData<T>): string;
+  /**
+   * Checks whether `urlPattern` matches the current URL and returns either
+   * based on `x` if there is a match, or based on `y` otherwise. (It
+   * loosely resembles the ternary conditional operator
+   * `matchesPattern ? x : y`.)
+   *
+   * If the current location matches `urlPattern`, `at(urlPattern, x, y)`
+   * returns:
+   * - `x`, if `x` is not a function;
+   * - `x({ params })`, if `x` is a function, with `params` extracted from
+   * the current URL.
+   *
+   * If the current location doesn't match `urlPattern`, `at(urlPattern, x, y)`
+   * returns:
+   * - `y`, if `y` is not a function;
+   * - `y({ params })`, if `y` is a function, with `params` extracted from
+   * the current URL.
+   */
+  at<P extends LocationPattern, X>(urlPattern: P, matchOutput: X | MatchHandler<P, X>): X | undefined;
+  at<P extends LocationPattern, X, Y>(urlPattern: P, matchOutput: X | MatchHandler<P, X>, mismatchOutput: Y | MatchHandler<P, Y>): X | Y;
+}
+
+type LinkElement = HTMLAnchorElement | HTMLAreaElement;
+
+declare function compileURL<T extends LocationValue>(urlPattern: T, data?: URLData<T>): string;
+
+declare function getNavigationOptions(element: LinkElement): NavigationOptions;
+
+declare function isLocationObject(x: unknown): x is LocationObject;
+
+declare function isRouteEvent(event: unknown): boolean;
+
+declare function matchURL<P extends LocationPattern>(pattern: P, href: string): MatchState<P>;
+
+export { ContainerElement, ElementCollection, EventCallback, EventCallbackMap, EventEmitter, LinkElement, LocationObject, LocationPattern, LocationValue, MatchHandler, MatchState, NavigationOptions, ObservedElement, PersistentState, PersistentStatePayloadMap, PersistentStorage, Route, State, StateOptions, StatePayloadMap, StateUpdate, StateUpdatePayload, StorageEntryOptions, URLComponents, URLConfig, URLData, URLSchema, URLState, URLStatePayloadMap, compileURL, getNavigationOptions, getStorageEntry, isLocationObject, isRouteEvent, isState, matchURL };