yuustate 0.0.1 → 3.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Muhammad Afifudin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,8 +7,97 @@ Inspired by [Zustand](https://zustand.docs.pmnd.rs) & [TanStack-Query](https://t
 
 _Fine-grained reactivity, minimal boilerplate, zero dependencies._
 
+Demo: https://afiiif.github.io/yuustate/
+
+**Installation:**
+
+```
+npm install yuustate
+```
+
+**Read the docs → https://yuustate.vercel.app**
+
+<br>
+
+---
+
+**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)
+
+A store is a global state container that can be used both **inside and outside** React.\
+With YuuState, creating a store is simple:
+
+```tsx
+import { createStore } from "yuustate/react";
+
+const useLawn = createStore({
+  plants: 3,
+  zombies: 1,
+});
+```
+
+Use it inside a component:
+
+```tsx
+function MyPlants() {
+  const { plants } = useLawn(); // No selectors needed.
+
+  return <div>Plants: {plants}</div>; // Only re-render when plants state changes
+}
+```
+
+Update the state **anywhere**:
+
+```tsx
+const addPlant = () => {
+  useLawn.setState(prev => ({ plants: prev.plants + 1 }));
+};
+```
+
+## Query Store for Async State
+
+Create a query store for async data with `createQuery`:
+
+```tsx
+import { createQuery } from "yuustate/react";
+
+const plantDetailQuery = createQuery(
+  async ({ id }) => {
+    const res = await fetch(`/api/plants/${id}`);
+    return res.json();
+  },
+);
+```
+
+Use it in your component:
+
+```tsx
+function PlantDetail({ id }) {
+  const usePlantDetailQuery = plantDetailQuery({ id });
+  const { data, error } = usePlantDetailQuery();
+
+  if (!data && !error) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>Name: {data.name}, damage: {data.damage}</div>;
+}
+```
+
+<br>
+
 ---
 
-This package is the rebranded version of [floppy-disk](https://www.npmjs.com/package/floppy-disk).\
-While the name has changed, the API and functionality remain the same.
-Simply update your dependencies and imports to start using the new package.
+Read the docs → https://yuustate.vercel.app

package/esm/index.d.mts

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

package/esm/index.mjs

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

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

@@ -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.d.mts").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;
+};