cogsbox-state 0.5.3

package/README.md

@@ -0,0 +1,386 @@
+# Cobgsbox State
+
+> ⚠️ **Warning**: This package is currently a work in progress and not ready for production use. The API is unstable and subject to breaking changes. Please do not use in production environments.
+
+---
+
+Cobgsbox State is a state management library that provides a fluent interface for managing complex state in React applications.
+
+## Installation
+
+```bash
+npm install cogsbox-state
+```
+
+## Features
+
+- 🎯 **Simplified Deep Updates**
+
+    ```typescript
+    // Instead of setState(prev => ({ ...prev, deep: { ...prev.deep, value: newValue }}))
+    updater.deep.value.update(newValue);
+    ```
+
+- 🔄 **Fluent Array Operations**
+
+    ```typescript
+    // Find, filter, and update in one chain
+    updater.items.findWith("id", "123").status.update("complete");
+    ```
+
+- 📝 **Smart Form Handling**
+
+    - Automatic debouncing
+    - Validation integration
+    - Form state synchronization
+
+- 🔍 **Powerful Array Methods**
+
+    - Filter with state access
+    - Flatten nested arrays
+    - Unique insertions
+    - Map with updaters
+
+- 🔄 **State Sync Features**
+
+    - Server synchronization
+    - Local storage persistence
+    - Optimistic updates
+
+- 🛠 **Developer Experience**
+
+    - Full TypeScript support
+    - Path autocompletion
+    - Runtime type checking
+
+- ⚡ **Performance**
+    - Granular updates
+    - Automatic optimization
+    - Path-based subscriptions
+
+## Initialization
+
+```typescript
+// Define your state shape
+interface Product {
+    id: string;
+    name: string;
+    price: number;
+    categories: string[];
+    variants: {
+        id: string;
+        color: string;
+        size: string;
+        stock: number;
+    }[];
+}
+
+interface CartItem {
+    productId: string;
+    variantId: string;
+    quantity: number;
+}
+
+const InitialState = {
+    catalog: {
+        products: [] as Product[],
+        categories: [] as string[],
+        filters: {
+            priceRange: { min: 0, max: 100 },
+            selectedCategories: [] as string[],
+            search: "",
+        },
+        sortBy: "price_asc" as "price_asc" | "price_desc" | "name",
+    },
+    cart: {
+        items: [] as CartItem[],
+        couponCode: "",
+        shipping: {
+            address: "",
+            method: "standard" as "standard" | "express",
+            cost: 0,
+        },
+    },
+    ui: {
+        sidebarOpen: false,
+        activeProductId: null as string | null,
+        notifications: [] as {
+            id: string;
+            message: string;
+            type: "success" | "error";
+        }[],
+    },
+};
+
+// Create state hook
+export const { useCogsState } = createCogsState(InitialState);
+
+// Use in component
+const [state, updater] = useCogsState("catalog");
+```
+
+## Updater API
+
+### Basic Updates
+
+#### `.update()`
+
+Updates state value directly.
+
+```typescript
+// Direct update
+updater.catalog.filters.search.update("blue shoes");
+
+// Functional update
+updater.cart.items[0].quantity.update((prev) => prev + 1);
+
+// Deep update
+updater.catalog.products
+    .findWith("id", "123")
+    .variants[0].stock.update((prev) => prev - 1);
+```
+
+#### `.get()`
+
+Gets current state value.
+
+```typescript
+const searchTerm = updater.catalog.filters.search.get();
+const cartTotal = updater.cart.items
+    .get()
+    .reduce((sum, item) => sum + item.quantity, 0);
+```
+
+### Array Operations
+
+#### `.insert()`
+
+Inserts an item into an array.
+
+```typescript
+// Add product
+updater.catalog.products.insert({
+    id: "123",
+    name: "Running Shoes",
+    price: 99.99,
+    categories: ["shoes", "sports"],
+    variants: [],
+});
+
+// Add to cart
+updater.cart.items.insert((prev) => ({
+    productId: "123",
+    variantId: "v1",
+    quantity: 1,
+}));
+```
+
+#### `.uniqueInsert()`
+
+Inserts only if item doesn't exist (checks deep equality).
+
+```typescript
+// Add category if not exists
+updater.catalog.categories.uniqueInsert("sports");
+
+// Add notification with unique ID
+updater.ui.notifications.uniqueInsert(
+    {
+        id: generateId(),
+        message: "Item added to cart",
+        type: "success",
+    },
+    ["id"],
+);
+```
+
+#### `.cut()`
+
+Removes an item from an array.
+
+```typescript
+// Remove from cart
+updater.cart.items.cut(index);
+
+// Remove notification
+updater.ui.notifications.findWith("id", "notif-123").cut();
+```
+
+#### `.findWith()`
+
+Finds an item in array by property comparison.
+
+```typescript
+// Find and update product
+updater.catalog.products.findWith("id", 123).price.update(99.99);
+
+// Find and update cart item
+updater.cart.items
+    .findWith("productId", 123)
+    .quantity.update((prev) => prev + 1);
+```
+
+#### `.index()`
+
+Gets item at specific index with updater methods.
+
+```typescript
+// Update first cart item
+updater.cart.items.index(0).quantity.update(2);
+```
+
+#### `.stateEach()`
+
+Maps over array with access to item updater.
+
+```typescript
+// Apply discount to all products
+updater.catalog.products.stateEach((product, productUpdater) => {
+    productUpdater.price.update((price) => price * 0.9);
+});
+```
+
+#### `.stateFilter()`
+
+Creates filtered view of array with updater methods.
+
+```typescript
+// Get low stock variants
+const lowStock = updater.catalog.products.stateFilter((product) =>
+    product.variants.some((v) => v.stock < 5),
+);
+
+// Update prices for filtered products
+lowStock.stateEach((product, productUpdater) => {
+    productUpdater.price.update((price) => price * 0.8);
+});
+```
+
+#### `.stateFlattenOn()`
+
+Flattens nested arrays by property.
+
+```typescript
+// Get all variants across products
+const allVariants = updater.catalog.products.stateFlattenOn("variants");
+```
+
+### Form Integration
+
+#### `.formElement()`
+
+Creates form control with validation.
+
+```typescript
+updater.cart.shipping.address.formElement("shipping", ({ inputProps }) => (
+  <input {...inputProps} placeholder="Shipping address" />
+), {
+  validation: {
+    message: "Address is required",
+    onChange: { clear: ["shipping.address"] }
+  },
+  debounceTime: 300
+})
+```
+
+### Menu & Selection API
+
+#### `.setSelected()`
+
+Marks an item as selected in a list.
+
+```typescript
+// Select product
+updater.catalog.products[0].setSelected(true);
+
+// Select category
+updater.catalog.categories.findWith("name", "sports").setSelected(true);
+```
+
+#### `.getSelected()`
+
+Gets currently selected item from a list.
+
+```typescript
+const selectedProduct = updater.catalog.products.getSelected();
+```
+
+[Rest of documentation remains the same...]
+
+## Examples
+
+### Product Catalog Management
+
+```typescript
+function ProductList() {
+  const [state, updater] = useCogsState("catalog", {
+    serverSync: {
+      syncKey: "products",
+      syncFunction: async ({ state }) => {
+        await api.updateProducts(state.products)
+      }
+    }
+  });
+
+  const filteredProducts = updater.products
+    .stateFilter(product =>
+      product.price >= state.filters.priceRange.min &&
+      product.price <= state.filters.priceRange.max &&
+      (state.filters.selectedCategories.length === 0 ||
+        product.categories.some(c => state.filters.selectedCategories.includes(c)))
+    );
+
+  return (
+    <div>
+      {filteredProducts.stateEach((product, productUpdater) => (
+        <ProductCard
+          key={product.id}
+          product={product}
+          onUpdateStock={(variantId, newStock) =>
+            productUpdater
+              .variants
+              .findWith("id", variantId)
+              .stock
+              .update(newStock)
+          }
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+### Shopping Cart Management
+
+```typescript
+function CartManager() {
+  const [state, updater] = useCogsState("cart", {
+    localStorage: {
+      key: "shopping-cart"
+    }
+  });
+
+  const addToCart = (product: Product, variantId: string) => {
+    updater.items.uniqueInsert({
+      productId: product.id,
+      variantId,
+      quantity: 1
+    }, ['productId', 'variantId']);
+  };
+
+  return (
+    <div>
+      {updater.items.stateEach((item, itemUpdater) => (
+        <CartItem
+          key={item.productId}
+          item={item}
+          onUpdateQuantity={qty => itemUpdater.quantity.update(qty)}
+          onRemove={() => itemUpdater.cut()}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+[Rest of TypeScript section remains the same...]

package/dist/CogsState.d.ts

@@ -0,0 +1,279 @@
+import { GenericObject } from './utility.js';
+import { UseMutationResult } from '@tanstack/react-query';
+import { ZodObject, ZodRawShape } from 'zod';
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type ServerSyncStatus = {
+    isFresh: boolean;
+    isFreshTime: number;
+    isStale: boolean;
+    isStaleTime: number;
+    isSyncing: boolean;
+    isSyncingTime: number;
+};
+export type SyncInfo = {
+    timeStamp: number;
+    userId: number;
+};
+export type FormElementParmas<T> = {
+    get: () => T;
+    set: UpdateType<T>;
+    syncStatus: (SyncInfo & {
+        date: Date;
+    }) | null;
+    path: string[];
+    validationErrors: () => string[];
+    inputProps: {
+        value?: T;
+        onChange?: (event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    };
+};
+export type StateKeys = string;
+type findWithFuncType<U> = (thisKey: keyof U, thisValue: U[keyof U]) => EndType<U> & {
+    upsert: UpdateType<U>;
+} & StateObject<U>;
+export type PushArgs<U> = (update: Prettify<U> | ((prevState: NonNullable<Prettify<U>>[]) => NonNullable<Prettify<U>>), opts?: UpdateOpts) => void;
+export interface GlobalState<T, K extends keyof T = keyof T> {
+    getKeyState: () => T;
+    setState: (newState: T | ((previousState: T) => T)) => void;
+    key: K;
+}
+type CutFunctionType = (index?: number, options?: {
+    waitForSync?: boolean;
+}) => void;
+export type InferArrayElement<T> = T extends (infer U)[] ? U : never;
+export type ArrayEndType<TShape extends unknown> = {
+    findWith: findWithFuncType<InferArrayElement<TShape>>;
+    index: (index: number) => StateObject<InferArrayElement<TShape>> & {
+        insert: PushArgs<InferArrayElement<TShape>>;
+        cut: CutFunctionType;
+        _index: number;
+    } & EndType<InferArrayElement<TShape>>;
+    insert: PushArgs<InferArrayElement<TShape>>;
+    cut: CutFunctionType;
+    stateEach: (callbackfn: (value: InferArrayElement<TShape>, setter: StateObject<InferArrayElement<TShape>>, index: number, array: TShape, arraySetter: StateObject<TShape>) => void) => any;
+    stateFlattenOn: <K extends keyof InferArrayElement<TShape>>(field: K) => StateObject<InferArrayElement<InferArrayElement<TShape>[K]>[]>;
+    uniqueInsert: (payload: UpdateArg<InferArrayElement<TShape>>, fields?: (keyof InferArrayElement<TShape>)[]) => void;
+    stateFilter: (callbackfn: (value: InferArrayElement<TShape>, index: number) => void) => ArrayEndType<TShape>;
+    getSelected: () => StateObject<InferArrayElement<TShape>> | undefined;
+} & EndType<TShape>;
+export type UpdateType<T> = (payload: UpdateArg<Prettify<T>>, opts?: UpdateOpts) => void;
+export type FormOptsType = {
+    key?: string;
+    validation?: {
+        message?: string;
+        stretch?: boolean;
+        props?: GenericObject;
+        disable?: boolean;
+    };
+    formElements?: boolean;
+    debounceTime?: number;
+    stateServerDifferences?: string[][];
+};
+export type FormControl<T> = (obj: FormElementParmas<T>) => JSX.Element;
+export type UpdateArg<S> = S | ((prevState: S) => S);
+export type UpdateOpts = {
+    timelineLabel?: string;
+    timeLineMessage?: string;
+    validate?: boolean;
+};
+export type ObjectEndType<T> = EndType<T> & {
+    [K in keyof T]-?: ObjectEndType<T[K]>;
+} & {
+    stateObject: (callbackfn: (value: T, setter: StateObject<T>) => void) => any;
+    delete: () => void;
+};
+export type EndType<T> = {
+    update: UpdateType<T>;
+    _path: string[];
+    _stateKey: string;
+    formElement: (validationKey: string, control: FormControl<T>, opts?: FormOptsType) => JSX.Element;
+    get: () => T;
+    $get: () => T;
+    _status: "fresh" | "stale" | "synced";
+    showValidationErrors: (ctx: string) => string[];
+    setValidation: (ctx: string) => void;
+    removeValidation: (ctx: string) => void;
+    ignoreFields: (fields: string[]) => StateObject<T>;
+    _selected: boolean;
+    setSelected: (value: boolean) => void;
+    validationWrapper: ({ children, hideMessage, }: {
+        children: React.ReactNode;
+        hideMessage?: boolean;
+    }) => JSX.Element;
+    lastSynced?: SyncInfo;
+};
+export type StateObject<T> = (T extends any[] ? ArrayEndType<T> : T extends Record<string, unknown> | object ? {
+    [K in keyof T]-?: StateObject<T[K]>;
+} & ObjectEndType<T> : T extends string | number | boolean | null ? T : never) & EndType<T> & {
+    _componentId: string | null;
+    _initialState: T;
+    updateInitialState: (newState: T | null) => {
+        fetchId: (field: keyof T) => string | number;
+    };
+    _isLoading: boolean;
+    _serverState: T;
+    revertToInitialState: (obj?: {
+        validationKey?: string;
+    }) => void;
+    middleware: (middles: ({ updateLog, update, }: {
+        updateLog: UpdateTypeDetail[] | undefined;
+        update: UpdateTypeDetail;
+    }) => void) => void;
+    _isServerSynced: () => boolean;
+    getLocalStorage: (key: string) => LocalStorageData<T> | null;
+};
+export type CogsUpdate<T extends unknown> = UpdateType<T>;
+export type EffectiveSetState<TStateObject> = (newStateOrFunction: TStateObject | ((prevState: TStateObject) => TStateObject), path: string[], updateObj: {
+    updateType: "update" | "insert" | "cut";
+}, validationKey?: string, opts?: UpdateOpts) => void;
+export type UpdateTypeDetail = {
+    timeStamp: number;
+    stateKey: string;
+    updateType: "update" | "insert" | "cut";
+    path: string[];
+    status: "new" | "sent" | "synced";
+    oldValue: any;
+    newValue: any;
+    userId?: number;
+};
+export type ActionsType<T> = {
+    type: "onChange";
+    action: ({ state, actionType }: {
+        state: T;
+        actionType: string;
+    }) => void;
+    debounce?: number;
+}[];
+type ArrayToObject<T extends string[]> = Record<T[number], string>;
+type CookieType<T> = {
+    timeStamp: number;
+    value: T;
+    cookieName: string;
+    OnUnMountCookie?: Boolean;
+};
+export type CogsCookiesType<T extends string[] = string[]> = CookieType<ArrayToObject<T>>;
+export type OptionsType<T extends unknown = unknown> = {
+    serverSync?: ServerSyncType<T>;
+    validationKey?: string;
+    enableServerState?: boolean;
+    middleware?: ({ updateLog, update, }: {
+        updateLog: UpdateTypeDetail[] | undefined;
+        update: UpdateTypeDetail;
+    }) => void;
+    zodSchema?: ZodObject<ZodRawShape>;
+    modifyState?: (state: T) => T;
+    localStorage?: {
+        key: string | ((state: T) => string);
+    };
+    formElements?: FormsElementsType;
+    enabledSync?: (state: T) => boolean;
+    reactiveDeps?: (state: T) => any[] | true;
+    syncUpdate?: Partial<UpdateTypeDetail>;
+    initState?: {
+        localStorageKey?: string;
+        ctx?: Record<string, any>;
+        initialState: T;
+        dependencies?: any[];
+    };
+};
+export type ServerSyncType<T> = {
+    testKey?: string;
+    syncKey: (({ state }: {
+        state: T;
+    }) => string) | string;
+    syncFunction: ({ state }: {
+        state: T;
+    }) => void;
+    debounce?: number;
+    mutation: UseMutationResult<any, unknown, any, unknown>;
+    snapshot?: {
+        name: (({ state }: {
+            state: T;
+        }) => string) | string;
+        stateKeys: StateKeys[];
+        currentUrl: string;
+        currentParams?: URLSearchParams;
+    };
+};
+export type SyncActionsType<T> = {
+    syncKey: string;
+    rollBackState?: T;
+    actionTimeStamp: number;
+    retryCount?: number;
+    status: "success" | "waiting" | "rolledBack" | "error" | "cancelled" | "failed";
+    snapshot?: {
+        name: string;
+        stateKeys: StateKeys[];
+        currentUrl: string;
+        currentParams?: URLSearchParams;
+    };
+};
+export type ValidationWrapperOptions<T extends unknown = unknown> = {
+    children: React.ReactNode;
+    active: boolean;
+    stretch?: boolean;
+    path: string[];
+    message?: string;
+    data?: T;
+    key?: string;
+};
+export type SyncRenderOptions<T extends unknown = unknown> = {
+    children: React.ReactNode;
+    time: number;
+    data?: T;
+    key?: string;
+};
+type FormsElementsType<T extends unknown = unknown> = {
+    validation?: (options: ValidationWrapperOptions<T>) => React.ReactNode;
+    syncRender?: (options: SyncRenderOptions<T>) => React.ReactNode;
+};
+export type InitialStateInnerType<T extends unknown = unknown> = {
+    initialState: T;
+} & OptionsType<T>;
+export type InitialStateType<T> = {
+    [key: string]: InitialStateInnerType<T>;
+};
+export type FunctionsToPassDownType = {
+    getValidationErrors: (pathArray: string) => string[];
+    removeValidationError: (path: string) => void;
+};
+export type AllStateTypes<T extends unknown> = Record<string, T>;
+export type CogsInitialState<T> = {
+    initialState: T;
+    formElements?: FormsElementsType<T>;
+};
+export type TransformedStateType<T> = {
+    [P in keyof T]: T[P] extends CogsInitialState<infer U> ? U : T[P];
+};
+export declare function addStateOptions<T extends unknown>(initialState: T, { formElements, zodSchema }: OptionsType<T>): T;
+export declare const createCogsState: <State extends Record<string, unknown>>(initialState: State) => {
+    useCogsState: <StateKey extends keyof State>(stateKey: StateKey, options?: OptionsType<TransformedStateType<State>[StateKey]>) => readonly [TransformedStateType<State>[StateKey], StateObject<TransformedStateType<State>[StateKey]>];
+    setCogsOptions: <StateKey extends keyof State>(stateKey: StateKey, options: OptionsType<TransformedStateType<State>[StateKey]>) => void;
+};
+type LocalStorageData<T> = {
+    state: T;
+    lastUpdated: number;
+    lastSyncedWithServer?: number;
+    baseServerState?: T;
+};
+export declare function useCogsStateFn<TStateObject extends unknown>(stateObject: TStateObject, { stateKey, serverSync, zodSchema, localStorage, formElements, middleware, reactiveDeps, componentId, initState, syncUpdate, }?: {
+    stateKey?: string;
+    componentId?: string;
+} & OptionsType<TStateObject>): [TStateObject, StateObject<TStateObject>];
+export declare function $cogsSignal(proxy: {
+    _path: string[];
+    _stateKey: string;
+}): import('react').FunctionComponentElement<{
+    proxy: {
+        _path: string[];
+        _stateKey: string;
+    };
+}>;
+export declare function $cogsSignalStore(proxy: {
+    _path: string[];
+    _stateKey: string;
+}): import('react').ReactSVGElement;
+export {};