floppy-disk 3.0.0-experimental.1 → 3.0.1

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,89 @@
+/**
+ * Represents a partial state update.
+ *
+ * Can be either:
+ * - A partial object to merge into the current state
+ * - A function that receives the current state and returns a partial update
+ */
+export type SetState<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>> = {
+    setState: (value: SetState<TState>) => void;
+    getState: () => TState;
+    subscribe: (subscriber: Subscriber<TState>) => () => void;
+    getSubscribers: () => Set<Subscriber<TState>>;
+};
+/**
+ * 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>> = {
+    onFirstSubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    onSubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    onUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    onLastUnsubscribe?: (state: TState, store: StoreApi<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,82 @@
+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,
+    allowSetStateServerSide = false
+  } = options;
+  const subscribers = /* @__PURE__ */ new Set();
+  const getSubscribers = () => subscribers;
+  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 in newValue) {
+      if (!Object.is(prevState[key], newValue[key])) {
+        changedKeys.push(key);
+      }
+    }
+    if (changedKeys.length === 0) return;
+    state = { ...prevState, ...newValue };
+    [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
+  };
+  const storeApi = {
+    getState,
+    setState,
+    subscribe,
+    getSubscribers
+  };
+  return storeApi;
+};
+
+export { getHash, getValue, initStore, isClient, isPlainObject, noop };

package/index.d.ts

@@ -0,0 +1 @@
+export * from 'floppy-disk/vanilla';

package/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+var vanilla = require('floppy-disk/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

@@ -1,15 +1,14 @@
 {
   "name": "floppy-disk",
-  "version": "3.0.0-experimental.1",
-  "description": "FloppyDisk - lightweight, simple, and powerful state management library",
+  "description": "Lightweight, simple, and powerful state management library",
+  "private": false,
+  "version": "3.0.1",
   "keywords": [
+    "utilities",
+    "store",
     "state",
-    "manager",
-    "management",
     "react",
     "hooks",
-    "store",
-    "utilities",
     "query"
   ],
   "author": "Muhammad Afifudin",
@@ -24,59 +23,62 @@
   "homepage": "https://github.com/afiiif/floppy-disk#readme",
   "sideEffects": false,
   "files": [
-    "lib/",
-    "esm/",
-    "utils/"
+    "**"
   ],
-  "main": "./lib/index.js",
-  "module": "./esm/index.js",
-  "types": "./lib/index.d.ts",
+  "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.ts",
-        "default": "./esm/index.js"
-      },
-      "module": {
-        "types": "./esm/index.d.ts",
-        "default": "./esm/index.js"
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
       },
       "default": {
-        "types": "./lib/index.d.ts",
-        "default": "./lib/index.js"
+        "types": "./index.d.ts",
+        "default": "./index.js"
       }
     },
-    "./utils": {
+    "./*": {
       "import": {
-        "types": "./esm/utils.d.ts",
-        "default": "./esm/utils.js"
-      },
-      "module": {
-        "types": "./esm/utils.d.ts",
-        "default": "./esm/utils.js"
+        "types": "./esm/*.d.mts",
+        "default": "./esm/*.mjs"
       },
       "default": {
-        "types": "./lib/utils.d.ts",
-        "default": "./lib/utils.js"
+        "types": "./*.d.ts",
+        "default": "./*.js"
       }
     }
   },
-  "release": {
-    "branches": [
-      "main",
-      {
-        "name": "beta",
-        "prerelease": true
-      },
-      {
-        "name": "alpha",
-        "prerelease": true
-      },
-      {
-        "name": "experimental",
-        "prerelease": true
-      }
-    ]
+  "packageManager": "pnpm@10.32.1",
+  "peerDependencies": {
+    "@types/react": ">=17.0",
+    "react": ">=17.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   }
 }

package/react/create-mutation.d.ts

@@ -0,0 +1,151 @@
+import { type InitStoreOptions, type SetState } from 'floppy-disk/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: {
+    state: string;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    variable: undefined;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: undefined;
+    errorUpdatedAt: undefined;
+};
+/**
+ * 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' });
+ */
+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;
+    getSubscribers: () => Set<import("../vanilla.ts").Subscriber<MutationState<TData, TVariable, TError>>>;
+    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: SetState<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;
+};