yuustate 0.0.1 → 3.10.0

package/esm/vanilla/basic.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Check if this runs on browser.
+ */
+export declare const isClient: boolean;
+/**
+ * Empty function.
+ */
+export declare const noop: () => void;
+/**
+ * If the value is a function, it will invoke the function.\
+ * If the value is not a function, it will just return it.
+ */
+export declare const getValue: <T, P extends any[]>(valueOrComputeValueFn: T | ((...params: P) => T), ...params: P) => T;

package/esm/vanilla/hash.d.mts

@@ -0,0 +1,7 @@
+export declare const isPlainObject: (value: any) => boolean;
+/**
+ * Get stable hash string from any value.
+ *
+ * Reference: https://github.com/TanStack/query/blob/v5.90.3/packages/query-core/src/utils.ts#L216
+ */
+export declare const getHash: (value?: any) => string;

package/esm/vanilla/store.d.mts

@@ -0,0 +1,121 @@
+export type SetStateInput<TState> = Partial<TState> | ((state: TState) => Partial<TState>);
+/**
+ * A subscriber function that is called whenever the state updates.
+ *
+ * @param state - The latest state
+ * @param prevState - The previous state before the update
+ * @param changedKeys - The top-level keys that changed (shallow diff)
+ *
+ * @remarks
+ * - Subscribers are only called when at least one field changes.
+ * - Change detection is performed per key using `Object.is`.
+ * - `changedKeys` only includes top-level keys; nested changes must be inferred by the consumer.
+ */
+export type Subscriber<TState> = (state: TState, prevState: TState, changedKeys: Array<keyof TState>) => void;
+/**
+ * Core store API for managing state.
+ *
+ * @remarks
+ * - The store performs **shallow change detection per key** before notifying subscribers.
+ * - Subscribers are only notified when at least one field changes.
+ * - State is treated as **immutable**. Mutating nested values directly will not trigger updates.
+ * - Designed to be framework-agnostic (React bindings are built separately).
+ * - By default, `setState` is **disabled on the server** to prevent accidental shared state between requests.
+ */
+export type StoreApi<TState extends Record<string, any>> = {
+    /**
+     * Updates the state.
+     *
+     * @param value - Partial state or updater function
+     *
+     * @remarks
+     * - Accepts either a partial object or a function `(state) => partial`
+     * - Updates are shallowly merged into the current state
+     */
+    setState: (value: SetStateInput<TState>) => void;
+    /**
+     * Get the current state.
+     *
+     * @returns The latest state snapshot
+     */
+    getState: () => TState;
+    /**
+     * Subscribes to state changes.
+     *
+     * @param subscriber - Function called when state updates
+     *
+     * @returns Unsubscribe function
+     *
+     * @remarks
+     * - Subscribers are only called when at least one root key changes
+     * - Receives `(state, prevState, changedKeys)`
+     */
+    subscribe: (subscriber: Subscriber<TState>) => () => void;
+    /**
+     * Returns the number of active subscribers.
+     *
+     * @returns Total subscriber count
+     *
+     * @remarks
+     * - Can be used to determine if the store is currently in use
+     */
+    getSubscriberCount: () => number;
+};
+/**
+ * Lifecycle hooks for the store.
+ *
+ * These hooks allow you to attach side effects based on subscription lifecycle.
+ *
+ * @remarks
+ * Useful for:
+ * - Lazy initialization (e.g. start fetching on first subscribe)
+ * - Cleanup (e.g. cancel timers, disconnect sockets)
+ * - Resource management (e.g. garbage collection)
+ */
+export type InitStoreOptions<TState extends Record<string, any>, TStoreProps extends Record<string, any> = object> = {
+    onFirstSubscribe?: (state: TState, store: StoreApi<TState> & TStoreProps) => void;
+    onSubscribe?: (state: TState, store: StoreApi<TState> & TStoreProps) => void;
+    onUnsubscribe?: (state: TState, store: StoreApi<TState> & TStoreProps) => void;
+    onLastUnsubscribe?: (state: TState, store: StoreApi<TState> & TStoreProps) => void;
+    /**
+     * Called whenever the state changes, without counting as a subscriber.
+     * Acts like a "spy" on state updates.
+     * Useful for devtools, logging, or debugging state changes.
+     */
+    onStateChange?: (state: TState, prevState: TState, changedKeys: Array<keyof TState>) => void;
+    /**
+     * By default, calling `setState` on the server is disallowed to prevent shared state across requests.
+     * Set this to `true` only if you explicitly intend to mutate state during server execution.
+     */
+    allowSetStateServerSide?: boolean;
+};
+/**
+ * Creates a vanilla store with pub-sub capabilities.
+ *
+ * The store state must be an **object**.\
+ * Updates are applied as shallow merges, so non-object states are not supported.
+ *
+ * @param initialState - The initial state of the store
+ * @param options - Optional lifecycle hooks
+ *
+ * @returns A store API for managing state and subscriptions
+ *
+ * @remarks
+ * - State updates are **shallowly compared per key** before notifying subscribers.
+ * - Subscribers are only notified when at least one updated field changes (using `Object.is` comparison).
+ * - Subscribers receive the new state, previous state, and changed top-level keys.
+ * - State is expected to be treated as **immutable**.
+ *   - Mutating nested values directly will not trigger updates.
+ * - Lifecycle hooks allow side-effect management tied to subscription count.
+ * - By default, `setState` is **not allowed on the server** to prevent accidental shared state between requests.
+ *   - This helps avoid leaking data between users in server environments.
+ *   - If you intentionally want to allow this behavior, set `allowSetStateServerSide: true`.
+ *
+ * @example
+ * const store = initStore({ count: 0 });
+ *
+ * store.subscribe((state) => console.log(state.count));
+ * store.setState({ count: 1 }); // triggers subscriber
+ * store.setState({ count: 1 }); // no-op (no change)
+ */
+export declare const initStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => StoreApi<TState>;

package/esm/vanilla.d.mts

@@ -0,0 +1,3 @@
+export * from "./vanilla/basic.mjs";
+export * from "./vanilla/hash.mjs";
+export * from "./vanilla/store.mjs";

package/esm/vanilla.mjs

@@ -0,0 +1,90 @@
+const isClient = typeof window !== "undefined" && !("Deno" in window);
+const noop = () => {
+};
+const getValue = (valueOrComputeValueFn, ...params) => {
+  if (typeof valueOrComputeValueFn === "function") {
+    return valueOrComputeValueFn(...params);
+  }
+  return valueOrComputeValueFn;
+};
+
+const hasObjectPrototype = (value) => {
+  return Object.prototype.toString.call(value) === "[object Object]";
+};
+const isPlainObject = (value) => {
+  if (!hasObjectPrototype(value)) return false;
+  const ctor = value.constructor;
+  if (typeof ctor === "undefined") return true;
+  const prot = ctor.prototype;
+  if (!hasObjectPrototype(prot)) return false;
+  if (!prot.hasOwnProperty("isPrototypeOf")) return false;
+  if (Object.getPrototypeOf(value) !== Object.prototype) return false;
+  return true;
+};
+const getHash = (value) => JSON.stringify(
+  value,
+  (_, val) => isPlainObject(val) ? Object.keys(val).sort().reduce((result, key) => {
+    result[key] = val[key];
+    return result;
+  }, {}) : val
+);
+
+const initStore = (initialState, options = {}) => {
+  const {
+    onFirstSubscribe = noop,
+    onSubscribe = noop,
+    onUnsubscribe = noop,
+    onLastUnsubscribe = noop,
+    onStateChange = noop,
+    allowSetStateServerSide = false
+  } = options;
+  const subscribers = /* @__PURE__ */ new Set();
+  const getSubscriberCount = () => subscribers.size;
+  const subscribe = (subscriber) => {
+    subscribers.add(subscriber);
+    if (subscribers.size === 1) onFirstSubscribe(state, storeApi);
+    onSubscribe(state, storeApi);
+    return () => {
+      subscribers.delete(subscriber);
+      onUnsubscribe(state, storeApi);
+      if (subscribers.size === 0) onLastUnsubscribe(state, storeApi);
+    };
+  };
+  let state = initialState;
+  const getState = () => state;
+  const setState = (value) => {
+    if (!isClient && !allowSetStateServerSide) {
+      console.error(
+        "setState on the server is not allowed by default. Set `allowSetStateServerSide: true` to allow it."
+      );
+      return;
+    }
+    const prevState = state;
+    const newValue = getValue(value, state);
+    const changedKeys = [];
+    for (const key of Object.keys(newValue)) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype") {
+        console.warn(
+          `Ignored unsafe key "${String(key)}" in setState(). This key is reserved and may indicate a prototype pollution attempt or malformed payload.`
+        );
+        continue;
+      }
+      if (!Object.is(prevState[key], newValue[key])) {
+        changedKeys.push(key);
+      }
+    }
+    if (changedKeys.length === 0) return;
+    state = { ...prevState, ...newValue };
+    onStateChange(state, prevState, changedKeys);
+    [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
+  };
+  const storeApi = {
+    getState,
+    setState,
+    subscribe,
+    getSubscriberCount
+  };
+  return storeApi;
+};
+
+export { getHash, getValue, initStore, isClient, isPlainObject, noop };

package/index.d.ts

@@ -0,0 +1 @@
+export * from "yuustate/vanilla";

package/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+var vanilla = require('yuustate/vanilla');
+
+
+
+Object.keys(vanilla).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return vanilla[k]; }
+	});
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "yuustate",
   "description": "Lightweight unified state management for sync and async data.",
   "private": false,
-  "version": "0.0.1",
+  "version": "3.10.0",
   "keywords": [
     "utilities",
     "store",
@@ -22,9 +22,56 @@
   },
   "homepage": "https://github.com/afiiif/yuustate#readme",
   "sideEffects": false,
+  "files": [
+    "**"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "typesVersions": {
+    ">=4.5": {
+      "esm/*": [
+        "esm/*"
+      ],
+      "*": [
+        "*"
+      ]
+    },
+    "*": {
+      "esm/*": [
+        "ts_version_4.5_and_above_is_required.d.ts"
+      ],
+      "*": [
+        "ts_version_4.5_and_above_is_required.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "default": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    },
+    "./*": {
+      "import": {
+        "types": "./esm/*.d.mts",
+        "default": "./esm/*.mjs"
+      },
+      "default": {
+        "types": "./*.d.ts",
+        "default": "./*.js"
+      }
+    }
+  },
+  "packageManager": "pnpm@10.32.1",
   "peerDependencies": {
-    "@types/react": ">=17.0",
-    "react": ">=17.0"
+    "@types/react": ">=18.0",
+    "react": ">=18.0"
   },
   "peerDependenciesMeta": {
     "@types/react": {

package/react/create-mutation.d.ts

@@ -0,0 +1,143 @@
+import { type InitStoreOptions, type SetStateInput } from "yuustate/vanilla";
+/**
+ * Represents the state of a mutation.
+ *
+ * @remarks
+ * A mutation does not cache results and only tracks the latest execution.
+ *
+ * The state transitions are:
+ * - `INITIAL` → before any execution
+ * - `SUCCESS` → when mutation resolves successfully
+ * - `ERROR` → when mutation fails
+ *
+ * Unlike queries:
+ * - No retry mechanism
+ * - No caching across executions
+ */
+export type MutationState<TData, TVariable, TError> = {
+    isPending: boolean;
+} & ({
+    state: "INITIAL";
+    isSuccess: false;
+    isError: false;
+    variable: undefined;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: undefined;
+    errorUpdatedAt: undefined;
+} | {
+    state: "SUCCESS";
+    isSuccess: true;
+    isError: false;
+    variable: TVariable;
+    data: TData;
+    dataUpdatedAt: number;
+    error: undefined;
+    errorUpdatedAt: undefined;
+} | {
+    state: "ERROR";
+    isSuccess: false;
+    isError: true;
+    variable: TVariable;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: TError;
+    errorUpdatedAt: number;
+});
+export declare const INITIAL_STATE: MutationState<any, any, any>;
+/**
+ * Configuration options for a mutation.
+ *
+ * @remarks
+ * Lifecycle callbacks are triggered for each execution.
+ */
+export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions<MutationState<TData, TVariable, TError>> & {
+    /**
+     * Called when the mutation succeeds.\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
+     */
+    onSuccess?: (data: TData, variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
+    /**
+     * Called when the mutation fails.\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
+     */
+    onError?: (error: TError, variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
+    /**
+     * Called after the mutation settles (either success or error).\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
+     */
+    onSettled?: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
+};
+/**
+ * Creates a mutation store for handling async operations that modify data.
+ *
+ * @param mutationFn - Async function that performs the mutation
+ * @param options - Optional configuration and lifecycle callbacks
+ *
+ * @returns A function that acts as both:
+ * - A React hook for subscribing to mutation state
+ * - A mutation controller (execute, reset, etc.)
+ *
+ * @remarks
+ * - Mutations are **not cached** and only track the latest execution.
+ * - Designed for operations that change data (e.g. create, update, delete).
+ * - No retry mechanism is provided by default.
+ * - The mutation always resolves (never throws): the result contains either `data` or `error`.
+ * - If multiple executions triggered at the same time:
+ *   - Only the latest execution is allowed to update the state.
+ *   - Results from previous executions are ignored if a newer one exists.
+ *
+ * @example
+ * const useCreateUser = createMutation(async (input) => {
+ *   return api.createUser(input);
+ * });
+ *
+ * const { isPending } = useCreateUser();
+ * const result = await useCreateUser.execute({ name: 'John' });
+ *
+ * @see https://yuustate.vercel.app/docs/mutation
+ */
+export declare const createMutation: <TData, TVariable = undefined, TError = Error>(mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => Promise<TData>, options?: MutationOptions<TData, TVariable, TError>) => (() => MutationState<TData, TVariable, TError>) & {
+    subscribe: (subscriber: import("../vanilla.ts").Subscriber<MutationState<TData, TVariable, TError>>) => () => void;
+    getSubscriberCount: () => number;
+    getState: () => MutationState<TData, TVariable, TError>;
+    /**
+     * Manually updates the mutation state.
+     *
+     * @remarks
+     * - Intended for advanced use cases.
+     * - Prefer using provided mutation actions (`execute`, `reset`) instead.
+     */
+    setState: (value: SetStateInput<MutationState<TData, TVariable, TError>>) => void;
+    /**
+     * Executes the mutation.
+     *
+     * @param variable - Input passed to the mutation function
+     *
+     * @returns A promise that always resolves with:
+     * - `{ data, variable }` on success
+     * - `{ error, variable }` on failure
+     *
+     * @remarks
+     * - The promise never rejects to simplify async handling.
+     * - If a mutation is already in progress, a warning is logged.
+     * - When a new execution starts, all previous pending executions will resolve with the result of the latest execution.
+     */
+    execute: TVariable extends undefined ? () => Promise<{
+        variable: undefined;
+        data?: TData;
+        error?: TError;
+    }> : (variable: TVariable) => Promise<{
+        variable: TVariable;
+        data?: TData;
+        error?: TError;
+    }>;
+    /**
+     * Resets the mutation state back to its initial state.
+     *
+     * @remarks
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
+     */
+    reset: () => void;
+};