floppy-disk 3.3.0 → 3.5.0

package/README.md

@@ -2,11 +2,10 @@
 
 A unified state model for **sync & async** data.
 
-If you know [Zustand](https://zustand.docs.pmnd.rs) & [TanStack-Query](https://tanstack.com/query), you already know FloppyDisk(.ts).\
-It keeps what works, removes unnecessary complexity, and unifies everything into a simpler API.\
-No relearning—just a better experience.
+Built on the patterns you know. Refined into something simpler.\
+Inspired by [Zustand](https://zustand.docs.pmnd.rs) & [TanStack-Query](https://tanstack.com/query).
 
-_Smaller bundle. Zero dependencies._
+_Fine-grained reactivity, minimal boilerplate, zero dependencies._
 
 Demo: https://afiiif.github.io/floppy-disk/
 
@@ -16,18 +15,25 @@ Demo: https://afiiif.github.io/floppy-disk/
 npm install floppy-disk
 ```
 
-## In short, it is:
+**Read the docs → https://floppy-disk.vercel.app**
 
-- **Like Zustand, but has additional capabilities:**
-  - No selectors: automatically optimizes re-renders
-  - Store events: `onFirstSubscribe`, `onSubscribe`, `onUnsubscribe`, `onLastUnsubscribe`
-  - Easier to set initial state on SSR/SSG
-  - Smaller bundle
-- **Like TanStack Query, but:**
-  - DX is very similar to Zustand → One mental model for sync & async
-  - Much smaller bundle than TanStack Query → With nearly the same capabilities
+<br>
 
-**Docs: https://floppy-disk.vercel.app**
+---
+
+**Like Zustand, but has additional capabilities:**
+- No selectors: automatically optimizes re-renders
+- Store events: `onFirstSubscribe`, `onSubscribe`, `onUnsubscribe`, `onLastUnsubscribe`
+- Easier to set initial state on SSR/SSG
+- Smaller bundle
+
+**Like TanStack Query, but:**
+- DX is very similar to Zustand → One mental model for sync & async
+- Much smaller bundle than TanStack Query → With nearly the same capabilities
+
+---
+
+<br>
 
 ## Store (Global State)
 

package/esm/react/create-mutation.d.mts

@@ -105,7 +105,7 @@ export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions
  * const { isPending } = useCreateUser();
  * const result = await useCreateUser.execute({ name: 'John' });
  *
- * @see https://floppy-disk.vercel.app/docs/async/mutation
+ * @see https://floppy-disk.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.d.mts").Subscriber<MutationState<TData, TVariable, TError>>) => () => void;

package/esm/react/create-query.d.mts

@@ -1,4 +1,5 @@
 import { type InitStoreOptions, type SetState } from "../vanilla.mjs";
+import type { StoreKey } from "./create-stores.mjs";
 /**
  * Represents the state of a query.
  *
@@ -68,7 +69,9 @@ export type QueryState<TData, TError> = {
  * @remarks
  * Controls caching, retry behavior, lifecycle, and side effects of an async operation.
  */
-export type QueryOptions<TData, TVariable extends Record<string, any>, TError = Error> = InitStoreOptions<QueryState<TData, TError>> & {
+export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, {
+    variableHash: string;
+}> & {
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
@@ -162,9 +165,9 @@ export type QueryOptions<TData, TVariable extends Record<string, any>, TError =
  *   // ...
  * }
  *
- * @see https://floppy-disk.vercel.app/docs/async/query
+ * @see https://floppy-disk.vercel.app/docs/query
  */
-export declare const createQuery: <TData, TVariable extends Record<string, any> = never, TError = Error>(queryFn: (variable: TVariable, currentState: QueryState<TData, TError>, variableHash: string) => Promise<TData>, options?: QueryOptions<TData, TVariable, TError>) => ((variable?: TVariable) => ((options?: {
+export declare const createQuery: <TData, TVariable extends StoreKey = never, TError = Error>(queryFn: (variable: TVariable, currentState: QueryState<TData, TError>, variableHash: string) => Promise<TData>, options?: QueryOptions<TData, TVariable, TError>) => ((variable?: TVariable) => ((options?: {
     /**
      * Whether the query should be ravalidated automatically on mount.
      *
@@ -216,11 +219,11 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
     initialData?: never;
     initialDataIsStale?: never;
 })) => QueryState<TData, TError>) & {
+    variableHash: string;
     /**
      * Internal data, do not mutate!
      */
     metadata: {
-        variableHash: string;
         isInvalidated?: boolean;
         promise?: Promise<QueryState<TData, TError>> | undefined;
         promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;

package/esm/react/create-store.d.mts

@@ -25,7 +25,7 @@ import { type InitStoreOptions } from "../vanilla.mjs";
  *
  * useMyStore.setState({ foo: 2 }); // only components using foo will re-render
  *
- * @see https://floppy-disk.vercel.app/docs/sync/store
+ * @see https://floppy-disk.vercel.app/docs/store
  */
 export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => ((options?: {
     /**

package/esm/react/create-stores.d.mts

@@ -1,4 +1,8 @@
 import { type InitStoreOptions } from "../vanilla.mjs";
+type GoodInputForHash = string | number | boolean | null | Date;
+export type StoreKey = GoodInputForHash | {
+    [key: string | number]: StoreKey | StoreKey[];
+};
 /**
  * Creates a factory for multiple stores identified by a key.
  *
@@ -30,9 +34,12 @@ import { type InitStoreOptions } from "../vanilla.mjs";
  *   return <div>{state.name}</div>;
  * }
  *
- * @see https://floppy-disk.vercel.app/docs/sync/stores
+ * @see https://floppy-disk.vercel.app/docs/stores
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => ((options?: {
+export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, {
+    key: TKey;
+    keyHash: string;
+}>) => (key?: TKey) => ((options?: {
     /**
      * Initial state used on first render (and will also update the store state right after that)
      *
@@ -48,3 +55,4 @@ export declare const createStores: <TState extends Record<string, any>, TKey ext
     key: TKey;
     keyHash: string;
 };
+export {};

package/esm/react/use-mutation.d.mts

@@ -21,7 +21,7 @@ import { type MutationOptions, type MutationState } from "./create-mutation.mjs"
  *   - Only the latest execution is allowed to update the state.
  *   - Results from previous executions are ignored if a newer one exists.
  *
- * @see https://floppy-disk.vercel.app/docs/async/mutation
+ * @see https://floppy-disk.vercel.app/docs/mutation
  */
 export declare const useMutation: <TData, TVariable = undefined, TError = Error>(
 /**

package/esm/react.mjs

@@ -94,7 +94,11 @@ const createStores = (initialState, options) => {
     if (stores.has(keyHash)) {
       store = stores.get(keyHash);
     } else {
-      store = initStore(initialState, options);
+      store = initStore(
+        initialState,
+        options
+        // Intentionally using as any: don't want to add generic on `initStore`
+      );
       store.key = key;
       store.keyHash = keyHash;
       stores.set(keyHash, store);
@@ -207,8 +211,8 @@ const createQuery = (queryFn, options = {}) => {
     }
   });
   const internals = /* @__PURE__ */ new WeakMap();
-  const configureInternals = (store, variable, variableHash) => ({
-    metadata: { variableHash },
+  const configureInternals = (store, variable) => ({
+    metadata: {},
     setInitialData: (data, revalidate2 = false) => {
       const state = store.getState();
       if (state.state === "INITIAL" && state.data === void 0) {
@@ -263,7 +267,7 @@ const createQuery = (queryFn, options = {}) => {
         return false;
       }
       internals.get(store).reset();
-      return stores.delete(variableHash);
+      return stores.delete(store.variableHash);
     },
     optimisticUpdate: (optimisticData) => {
       const { metadata, revalidate: revalidate2, rollbackOptimisticUpdate } = internals.get(store);
@@ -292,7 +296,7 @@ const createQuery = (queryFn, options = {}) => {
           isRetrying: !!metadata.retryResolver,
           retryCount: metadata.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
         });
-        queryFn(variable, stateBeforeExecute, metadata.variableHash).then((data) => {
+        queryFn(variable, stateBeforeExecute, store.variableHash).then((data) => {
           var _a;
           if (data === void 0) {
             console.error(
@@ -396,9 +400,14 @@ const createQuery = (queryFn, options = {}) => {
     if (stores.has(variableHash)) {
       store = stores.get(variableHash);
     } else {
-      store = initStore(initialState, configureStoreEvents(variableHash));
+      store = initStore(
+        initialState,
+        configureStoreEvents(variableHash)
+        // Intentionally using as any: don't want to add generic on `initStore`
+      );
+      store.variableHash = variableHash;
       stores.set(variableHash, store);
-      internals.set(store, configureInternals(store, variable, variableHash));
+      internals.set(store, configureInternals(store, variable));
     }
     const useStore = (options2 = {}) => {
       const {
@@ -473,7 +482,8 @@ const createQuery = (queryFn, options = {}) => {
         console.debug("Manual setState (not via provided actions) on query store");
         store.setState(value);
       },
-      ...internals.get(store)
+      ...internals.get(store),
+      variableHash
     });
   };
   return Object.assign(getStore, {

package/esm/vanilla/store.d.mts

@@ -46,11 +46,11 @@ export type StoreApi<TState extends Record<string, any>> = {
  * - 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;
+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.

package/package.json

@@ -2,7 +2,7 @@
   "name": "floppy-disk",
   "description": "Lightweight unified state management for sync and async data.",
   "private": false,
-  "version": "3.3.0",
+  "version": "3.5.0",
   "keywords": [
     "utilities",
     "store",

package/react/create-mutation.d.ts

@@ -105,7 +105,7 @@ export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions
  * const { isPending } = useCreateUser();
  * const result = await useCreateUser.execute({ name: 'John' });
  *
- * @see https://floppy-disk.vercel.app/docs/async/mutation
+ * @see https://floppy-disk.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;

package/react/create-query.d.ts

@@ -1,4 +1,5 @@
 import { type InitStoreOptions, type SetState } from "../vanilla.ts";
+import type { StoreKey } from "./create-stores.ts";
 /**
  * Represents the state of a query.
  *
@@ -68,7 +69,9 @@ export type QueryState<TData, TError> = {
  * @remarks
  * Controls caching, retry behavior, lifecycle, and side effects of an async operation.
  */
-export type QueryOptions<TData, TVariable extends Record<string, any>, TError = Error> = InitStoreOptions<QueryState<TData, TError>> & {
+export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, {
+    variableHash: string;
+}> & {
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
@@ -162,9 +165,9 @@ export type QueryOptions<TData, TVariable extends Record<string, any>, TError =
  *   // ...
  * }
  *
- * @see https://floppy-disk.vercel.app/docs/async/query
+ * @see https://floppy-disk.vercel.app/docs/query
  */
-export declare const createQuery: <TData, TVariable extends Record<string, any> = never, TError = Error>(queryFn: (variable: TVariable, currentState: QueryState<TData, TError>, variableHash: string) => Promise<TData>, options?: QueryOptions<TData, TVariable, TError>) => ((variable?: TVariable) => ((options?: {
+export declare const createQuery: <TData, TVariable extends StoreKey = never, TError = Error>(queryFn: (variable: TVariable, currentState: QueryState<TData, TError>, variableHash: string) => Promise<TData>, options?: QueryOptions<TData, TVariable, TError>) => ((variable?: TVariable) => ((options?: {
     /**
      * Whether the query should be ravalidated automatically on mount.
      *
@@ -216,11 +219,11 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
     initialData?: never;
     initialDataIsStale?: never;
 })) => QueryState<TData, TError>) & {
+    variableHash: string;
     /**
      * Internal data, do not mutate!
      */
     metadata: {
-        variableHash: string;
         isInvalidated?: boolean;
         promise?: Promise<QueryState<TData, TError>> | undefined;
         promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;

package/react/create-store.d.ts

@@ -25,7 +25,7 @@ import { type InitStoreOptions } from "../vanilla.ts";
  *
  * useMyStore.setState({ foo: 2 }); // only components using foo will re-render
  *
- * @see https://floppy-disk.vercel.app/docs/sync/store
+ * @see https://floppy-disk.vercel.app/docs/store
  */
 export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => ((options?: {
     /**

package/react/create-stores.d.ts

@@ -1,4 +1,8 @@
 import { type InitStoreOptions } from "../vanilla.ts";
+type GoodInputForHash = string | number | boolean | null | Date;
+export type StoreKey = GoodInputForHash | {
+    [key: string | number]: StoreKey | StoreKey[];
+};
 /**
  * Creates a factory for multiple stores identified by a key.
  *
@@ -30,9 +34,12 @@ import { type InitStoreOptions } from "../vanilla.ts";
  *   return <div>{state.name}</div>;
  * }
  *
- * @see https://floppy-disk.vercel.app/docs/sync/stores
+ * @see https://floppy-disk.vercel.app/docs/stores
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => ((options?: {
+export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, {
+    key: TKey;
+    keyHash: string;
+}>) => (key?: TKey) => ((options?: {
     /**
      * Initial state used on first render (and will also update the store state right after that)
      *
@@ -48,3 +55,4 @@ export declare const createStores: <TState extends Record<string, any>, TKey ext
     key: TKey;
     keyHash: string;
 };
+export {};

package/react/use-mutation.d.ts

@@ -21,7 +21,7 @@ import { type MutationOptions, type MutationState } from "./create-mutation.ts";
  *   - Only the latest execution is allowed to update the state.
  *   - Results from previous executions are ignored if a newer one exists.
  *
- * @see https://floppy-disk.vercel.app/docs/async/mutation
+ * @see https://floppy-disk.vercel.app/docs/mutation
  */
 export declare const useMutation: <TData, TVariable = undefined, TError = Error>(
 /**

package/react.js

@@ -96,7 +96,11 @@ const createStores = (initialState, options) => {
     if (stores.has(keyHash)) {
       store = stores.get(keyHash);
     } else {
-      store = vanilla.initStore(initialState, options);
+      store = vanilla.initStore(
+        initialState,
+        options
+        // Intentionally using as any: don't want to add generic on `initStore`
+      );
       store.key = key;
       store.keyHash = keyHash;
       stores.set(keyHash, store);
@@ -209,8 +213,8 @@ const createQuery = (queryFn, options = {}) => {
     }
   });
   const internals = /* @__PURE__ */ new WeakMap();
-  const configureInternals = (store, variable, variableHash) => ({
-    metadata: { variableHash },
+  const configureInternals = (store, variable) => ({
+    metadata: {},
     setInitialData: (data, revalidate2 = false) => {
       const state = store.getState();
       if (state.state === "INITIAL" && state.data === void 0) {
@@ -265,7 +269,7 @@ const createQuery = (queryFn, options = {}) => {
         return false;
       }
       internals.get(store).reset();
-      return stores.delete(variableHash);
+      return stores.delete(store.variableHash);
     },
     optimisticUpdate: (optimisticData) => {
       const { metadata, revalidate: revalidate2, rollbackOptimisticUpdate } = internals.get(store);
@@ -294,7 +298,7 @@ const createQuery = (queryFn, options = {}) => {
           isRetrying: !!metadata.retryResolver,
           retryCount: metadata.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
         });
-        queryFn(variable, stateBeforeExecute, metadata.variableHash).then((data) => {
+        queryFn(variable, stateBeforeExecute, store.variableHash).then((data) => {
           var _a;
           if (data === void 0) {
             console.error(
@@ -398,9 +402,14 @@ const createQuery = (queryFn, options = {}) => {
     if (stores.has(variableHash)) {
       store = stores.get(variableHash);
     } else {
-      store = vanilla.initStore(initialState, configureStoreEvents(variableHash));
+      store = vanilla.initStore(
+        initialState,
+        configureStoreEvents(variableHash)
+        // Intentionally using as any: don't want to add generic on `initStore`
+      );
+      store.variableHash = variableHash;
       stores.set(variableHash, store);
-      internals.set(store, configureInternals(store, variable, variableHash));
+      internals.set(store, configureInternals(store, variable));
     }
     const useStore = (options2 = {}) => {
       const {
@@ -475,7 +484,8 @@ const createQuery = (queryFn, options = {}) => {
         console.debug("Manual setState (not via provided actions) on query store");
         store.setState(value);
       },
-      ...internals.get(store)
+      ...internals.get(store),
+      variableHash
     });
   };
   return Object.assign(getStore, {

package/vanilla/store.d.ts

@@ -46,11 +46,11 @@ export type StoreApi<TState extends Record<string, any>> = {
  * - 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;
+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.