coaction 0.1.4 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Michael Lin
+
+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

@@ -19,12 +19,24 @@ npm install coaction
 ```jsx
 import { create } from 'coaction';
 
-const useStore = create((set, get) => ({
+const useStore = create((set) => ({
   count: 0,
   increment: () => set((state) => state.count++)
 }));
 ```
 
+### Store Shape Mode (`sliceMode`)
+
+`create()` uses `sliceMode: 'auto'` by default. You can force behavior explicitly:
+
+- `sliceMode: 'single'`: treat object input as a single store.
+- `sliceMode: 'slices'`: require object-of-slice-functions input.
+
+```ts
+create({ ping: () => 'pong' }, { sliceMode: 'single' });
+create({ counter: (set) => ({ count: 0 }) }, { sliceMode: 'slices' });
+```
+
 ## Documentation
 
 You can find the documentation [here](https://github.com/unadlib/coaction).

package/dist/{declarations/src/interface.d.ts → index.d.mts}

@@ -1,11 +1,12 @@
-import type { Transport } from 'data-transport';
-import type { Draft, Patches } from 'mutative';
-export type ISlices<T = any> = Record<string, T>;
-export type DeepPartial<T> = {
+import { Transport } from 'data-transport';
+import { Draft, Patches } from 'mutative';
+
+type ISlices<T = any> = Record<string, T>;
+type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
-export type Listener = () => void;
-export interface Store<T extends ISlices = ISlices> {
+type Listener = () => void;
+interface Store<T extends ISlices = ISlices> {
     /**
      * The name of the store.
      */
@@ -27,7 +28,7 @@ export interface Store<T extends ISlices = ISlices> {
      */
     getState: () => T;
     /**
-     * Subscribe to the state changes.
+     * Subscribe to the state changes, and return the unsubscribe function.
      */
     subscribe: (listener: Listener) => () => void;
     /**
@@ -58,10 +59,6 @@ export interface Store<T extends ISlices = ISlices> {
      * Get the initial state.
      */
     getInitialState: () => T;
-    /**
-     * Get the raw instance via the initial state.
-     */
-    toRaw?: (key: any) => any;
     /**
      * The patch is used to update the state.
      */
@@ -72,10 +69,6 @@ export interface Store<T extends ISlices = ISlices> {
         patches: Patches;
         inversePatches: Patches;
     };
-    /**
-     * The act is used to run the function in the action.
-     */
-    act?: <T extends () => any>(fn: T) => ReturnType<T>;
     /**
      * The trace is used to trace the action
      */
@@ -102,39 +95,11 @@ export interface Store<T extends ISlices = ISlices> {
         result?: any;
     }) => void;
 }
-export type InternalEvents = {
-    /**
-     * Update the state in the worker or shared worker.
-     */
-    update(options: {
-        /**
-         * The patches is used to update the state.
-         */
-        patches: Patches;
-        /**
-         * The sequence is used to ensure the sequence of the state.
-         */
-        sequence: number;
-    }): Promise<void>;
-};
-export type ExternalEvents = {
-    /**
-     * Execute the function in the worker or shared worker.
-     */
-    execute(keys: string[], args: any[]): Promise<any>;
-    /**
-     * Full sync the state with the worker or shared worker.
-     */
-    fullSync(): Promise<{
-        state: string;
-        sequence: number;
-    }>;
-};
 interface Getter<T extends ISlices> {
     <P extends any[], R>(getDeps: (store: T) => readonly [...P] | [...P], selector: (...args: P) => R): R;
     (): T;
 }
-export type Slice<T extends ISlices> = (
+type Slice<T extends ISlices> = (
 /**
  * The setState is used to update the state.
  */
@@ -147,7 +112,7 @@ get: Getter<T>,
  * The store is used to store the state.
  */
 store: Store<T>) => T;
-export type Slices<T extends ISlices, K extends keyof T> = (
+type Slices<T extends ISlices, K extends keyof T> = (
 /**
  * The setState is used to update the state.
  */
@@ -160,11 +125,11 @@ get: Getter<T>,
  * The store is used to store the state.
  */
 store: Store<T>) => T[K];
-export type Middleware<T extends CreateState> = (store: Store<T>) => Store<T>;
-export type SliceState<T extends Record<string, Slice<any>>> = {
+type Middleware<T extends CreateState> = (store: Store<T>) => Store<T>;
+type SliceState<T extends Record<string, Slice<any>>> = {
     [K in keyof T]: ReturnType<T[K]>;
 };
-export type StoreOptions<T extends CreateState> = {
+type StoreOptions<T extends CreateState> = {
     /**
      * The name of the store.
      */
@@ -176,49 +141,150 @@ export type StoreOptions<T extends CreateState> = {
      * enable patches
      */
     enablePatches?: boolean;
+    /**
+     * control how createState should be interpreted.
+     * - auto: infer from createState shape.
+     * - slices: force slices mode.
+     * - single: force single-store mode.
+     */
+    sliceMode?: 'auto' | 'slices' | 'single';
 };
-export type ClientStoreOptions<T extends CreateState> = {
+type ClientStoreOptions<T extends CreateState> = {
     /**
      * The name of the store.
      */
     name?: string;
     middlewares?: Middleware<T>[];
+    /**
+     * control how createState should be interpreted.
+     * - auto: infer from createState shape.
+     * - slices: force slices mode.
+     * - single: force single-store mode.
+     */
+    sliceMode?: 'auto' | 'slices' | 'single';
 } & ClientTransportOptions;
-export interface ClientTransportOptions {
+interface ClientTransportOptions {
     workerType?: 'WebWorkerClient' | 'SharedWorkerClient';
     clientTransport?: Transport<any>;
     worker?: SharedWorker | Worker;
 }
-export type Asyncify<T extends object, D extends true | false> = {
+type Asyncify<T extends object, D extends true | false> = {
     [K in keyof T]: T[K] extends (...args: any[]) => any ? (...args: Parameters<T[K]>) => Promise<ReturnType<T[K]>> : D extends false ? T[K] : {
         [P in keyof T[K]]: T[K][P] extends (...args: any[]) => any ? (...args: Parameters<T[K][P]>) => Promise<ReturnType<T[K][P]>> : T[K][P];
     };
 };
-export type StoreWithAsyncFunction<T extends object, D extends true | false = false> = Store<Asyncify<T, D>> & (() => Asyncify<T, D>);
-export type StoreReturn<T extends object> = Store<T> & ((...args: any[]) => T);
-export type CreateState = ISlices | Record<string, Slice<any>>;
-export type Creator = {
+type StoreWithAsyncFunction<T extends object, D extends true | false = false> = Store<Asyncify<T, D>> & (() => Asyncify<T, D>);
+type StoreReturn<T extends object> = Store<T> & ((...args: any[]) => T);
+type CreateState = ISlices | Record<string, Slice<any>>;
+type Creator = {
     <T extends Record<string, Slice<any>>>(createState: T, options?: StoreOptions<T>): StoreReturn<SliceState<T>>;
     <T extends ISlices>(createState: Slice<T>, options?: StoreOptions<T>): StoreReturn<T>;
     <T extends Record<string, Slice<any>>>(createState: T, options?: ClientStoreOptions<T>): StoreWithAsyncFunction<SliceState<T>, true>;
     <T extends ISlices>(createState: Slice<T>, options?: ClientStoreOptions<T>): StoreWithAsyncFunction<T>;
 };
-export type ClientTransport = (Transport<{
-    listen: InternalEvents;
-    emit: ExternalEvents;
-}> & {
+
+/**
+ * Create a simple store or a shared store. The shared store can be used in a worker or another thread.
+ */
+declare const create: Creator;
+
+interface Internal<T extends CreateState = CreateState> {
+    /**
+     * The store module.
+     */
+    module: T;
     /**
-     * onConnect is called when the transport is connected.
+     * The root state.
      */
-    onConnect?: (fn: () => void) => void;
-}) | undefined;
-export type StoreTransport = (Transport<{
-    listen: ExternalEvents;
-    emit: InternalEvents;
-}> & {
+    rootState: T | Draft<T>;
     /**
-     * onConnect is called when the transport is connected.
+     * The backup state.
      */
-    onConnect?: (fn: () => void) => void;
-}) | undefined;
-export {};
+    backupState: T | Draft<T>;
+    /**
+     * Finalize the draft.
+     */
+    finalizeDraft: () => [T, Patches, Patches];
+    /**
+     * The mutable instance.
+     */
+    mutableInstance: any;
+    /**
+     * The sequence number.
+     */
+    sequence: number;
+    /**
+     * Whether the batch is running.
+     */
+    isBatching: boolean;
+    /**
+     * The listeners.
+     */
+    listeners: Set<Listener>;
+    /**
+     * The act is used to run the function in the action for mutable state.
+     */
+    actMutable?: <T extends () => any>(fn: T) => ReturnType<T>;
+    /**
+     * Get the mutable raw instance via the initial state.
+     */
+    toMutableRaw?: (key: any) => any;
+    /**
+     * The update immutable function.
+     */
+    updateImmutable?: (state: T) => void;
+}
+
+/**
+ * createBinder is a function to create a binder for the 3rd party store.
+ */
+declare function createBinder<F = (...args: any[]) => any>({ handleState, handleStore }: {
+    /**
+     * handleState is a function to handle the state object.
+     */
+    handleState: <T extends object = object>(state: T) => {
+        /**
+         * copyState is a copy of the state object.
+         */
+        copyState: T;
+        /**
+         * key is the key of the state object.
+         */
+        key?: keyof T;
+        /**
+         * bind is a function to bind the state object.
+         */
+        bind: (state: T) => T;
+    };
+    /**
+     * handleStore is a function to handle the store object.
+     */
+    handleStore: (
+    /**
+     * Coaction store
+     */
+    store: Store<object>, 
+    /**
+     * The raw state object from 3rd party library.
+     */
+    rawState: object, 
+    /**
+     * 3rd party library state object to Coaction state object.
+     */
+    state: object, 
+    /**
+     * internal Coaction API.
+     */
+    internal: Internal<object>, 
+    /**
+     * the key of the slice state object.
+     */
+    key?: string) => void;
+}): F;
+
+/**
+ * wrapStore is a function to wrap the store and return function to get the state with store.
+ */
+declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
+
+export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ISlices, type Middleware, type Slice, type SliceState, type Slices, type Store, type StoreOptions, create, createBinder, wrapStore };

package/dist/index.d.ts

@@ -0,0 +1,290 @@
+import { Transport } from 'data-transport';
+import { Draft, Patches } from 'mutative';
+
+type ISlices<T = any> = Record<string, T>;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+type Listener = () => void;
+interface Store<T extends ISlices = ISlices> {
+    /**
+     * The name of the store.
+     */
+    name: string;
+    /**
+     * Set the next state.
+     */
+    setState: (
+    /**
+     * The next state.
+     */
+    next: DeepPartial<T> | ((draft: Draft<T>) => any) | null, 
+    /**
+     * The updater is used to update the state.
+     */
+    updater?: (next: DeepPartial<T> | ((draft: Draft<T>) => any) | null) => [] | [T, Patches, Patches]) => void;
+    /**
+     * Get the current state.
+     */
+    getState: () => T;
+    /**
+     * Subscribe to the state changes, and return the unsubscribe function.
+     */
+    subscribe: (listener: Listener) => () => void;
+    /**
+     * Unsubscribe all listeners and dispose the transport.
+     */
+    destroy: () => void;
+    /**
+     * The store is shared in the web worker, shared worker, or other process.
+     */
+    share?: 'main' | 'client' | false;
+    /**
+     * The transport is used to communicate between the main thread and the worker or shared worker.
+     */
+    transport?: Transport;
+    /**
+     * The store is a slices.
+     */
+    isSliceStore: boolean;
+    /**
+     * apply the patches to the state.
+     */
+    apply: (state?: T, patches?: Patches) => void;
+    /**
+     * the pure state is used to get the state without the methods and getters.
+     */
+    getPureState: () => T;
+    /**
+     * Get the initial state.
+     */
+    getInitialState: () => T;
+    /**
+     * The patch is used to update the state.
+     */
+    patch?: (option: {
+        patches: Patches;
+        inversePatches: Patches;
+    }) => {
+        patches: Patches;
+        inversePatches: Patches;
+    };
+    /**
+     * The trace is used to trace the action
+     */
+    trace?: (options: {
+        /**
+         * The id of the method.
+         */
+        id: string;
+        /**
+         * The method name.
+         */
+        method: string;
+        /**
+         * The slice key.
+         */
+        sliceKey?: string;
+        /**
+         * The parameters of the method.
+         */
+        parameters?: any[];
+        /**
+         * The result of the method.
+         */
+        result?: any;
+    }) => void;
+}
+interface Getter<T extends ISlices> {
+    <P extends any[], R>(getDeps: (store: T) => readonly [...P] | [...P], selector: (...args: P) => R): R;
+    (): T;
+}
+type Slice<T extends ISlices> = (
+/**
+ * The setState is used to update the state.
+ */
+set: Store<T>['setState'], 
+/**
+ * The getState is used to get the state.
+ */
+get: Getter<T>, 
+/**
+ * The store is used to store the state.
+ */
+store: Store<T>) => T;
+type Slices<T extends ISlices, K extends keyof T> = (
+/**
+ * The setState is used to update the state.
+ */
+set: Store<T>['setState'], 
+/**
+ * The getState is used to get the state.
+ */
+get: Getter<T>, 
+/**
+ * The store is used to store the state.
+ */
+store: Store<T>) => T[K];
+type Middleware<T extends CreateState> = (store: Store<T>) => Store<T>;
+type SliceState<T extends Record<string, Slice<any>>> = {
+    [K in keyof T]: ReturnType<T[K]>;
+};
+type StoreOptions<T extends CreateState> = {
+    /**
+     * The name of the store.
+     */
+    name?: string;
+    transport?: Transport;
+    workerType?: 'SharedWorkerInternal' | 'WebWorkerInternal';
+    middlewares?: Middleware<T>[];
+    /**
+     * enable patches
+     */
+    enablePatches?: boolean;
+    /**
+     * control how createState should be interpreted.
+     * - auto: infer from createState shape.
+     * - slices: force slices mode.
+     * - single: force single-store mode.
+     */
+    sliceMode?: 'auto' | 'slices' | 'single';
+};
+type ClientStoreOptions<T extends CreateState> = {
+    /**
+     * The name of the store.
+     */
+    name?: string;
+    middlewares?: Middleware<T>[];
+    /**
+     * control how createState should be interpreted.
+     * - auto: infer from createState shape.
+     * - slices: force slices mode.
+     * - single: force single-store mode.
+     */
+    sliceMode?: 'auto' | 'slices' | 'single';
+} & ClientTransportOptions;
+interface ClientTransportOptions {
+    workerType?: 'WebWorkerClient' | 'SharedWorkerClient';
+    clientTransport?: Transport<any>;
+    worker?: SharedWorker | Worker;
+}
+type Asyncify<T extends object, D extends true | false> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? (...args: Parameters<T[K]>) => Promise<ReturnType<T[K]>> : D extends false ? T[K] : {
+        [P in keyof T[K]]: T[K][P] extends (...args: any[]) => any ? (...args: Parameters<T[K][P]>) => Promise<ReturnType<T[K][P]>> : T[K][P];
+    };
+};
+type StoreWithAsyncFunction<T extends object, D extends true | false = false> = Store<Asyncify<T, D>> & (() => Asyncify<T, D>);
+type StoreReturn<T extends object> = Store<T> & ((...args: any[]) => T);
+type CreateState = ISlices | Record<string, Slice<any>>;
+type Creator = {
+    <T extends Record<string, Slice<any>>>(createState: T, options?: StoreOptions<T>): StoreReturn<SliceState<T>>;
+    <T extends ISlices>(createState: Slice<T>, options?: StoreOptions<T>): StoreReturn<T>;
+    <T extends Record<string, Slice<any>>>(createState: T, options?: ClientStoreOptions<T>): StoreWithAsyncFunction<SliceState<T>, true>;
+    <T extends ISlices>(createState: Slice<T>, options?: ClientStoreOptions<T>): StoreWithAsyncFunction<T>;
+};
+
+/**
+ * Create a simple store or a shared store. The shared store can be used in a worker or another thread.
+ */
+declare const create: Creator;
+
+interface Internal<T extends CreateState = CreateState> {
+    /**
+     * The store module.
+     */
+    module: T;
+    /**
+     * The root state.
+     */
+    rootState: T | Draft<T>;
+    /**
+     * The backup state.
+     */
+    backupState: T | Draft<T>;
+    /**
+     * Finalize the draft.
+     */
+    finalizeDraft: () => [T, Patches, Patches];
+    /**
+     * The mutable instance.
+     */
+    mutableInstance: any;
+    /**
+     * The sequence number.
+     */
+    sequence: number;
+    /**
+     * Whether the batch is running.
+     */
+    isBatching: boolean;
+    /**
+     * The listeners.
+     */
+    listeners: Set<Listener>;
+    /**
+     * The act is used to run the function in the action for mutable state.
+     */
+    actMutable?: <T extends () => any>(fn: T) => ReturnType<T>;
+    /**
+     * Get the mutable raw instance via the initial state.
+     */
+    toMutableRaw?: (key: any) => any;
+    /**
+     * The update immutable function.
+     */
+    updateImmutable?: (state: T) => void;
+}
+
+/**
+ * createBinder is a function to create a binder for the 3rd party store.
+ */
+declare function createBinder<F = (...args: any[]) => any>({ handleState, handleStore }: {
+    /**
+     * handleState is a function to handle the state object.
+     */
+    handleState: <T extends object = object>(state: T) => {
+        /**
+         * copyState is a copy of the state object.
+         */
+        copyState: T;
+        /**
+         * key is the key of the state object.
+         */
+        key?: keyof T;
+        /**
+         * bind is a function to bind the state object.
+         */
+        bind: (state: T) => T;
+    };
+    /**
+     * handleStore is a function to handle the store object.
+     */
+    handleStore: (
+    /**
+     * Coaction store
+     */
+    store: Store<object>, 
+    /**
+     * The raw state object from 3rd party library.
+     */
+    rawState: object, 
+    /**
+     * 3rd party library state object to Coaction state object.
+     */
+    state: object, 
+    /**
+     * internal Coaction API.
+     */
+    internal: Internal<object>, 
+    /**
+     * the key of the slice state object.
+     */
+    key?: string) => void;
+}): F;
+
+/**
+ * wrapStore is a function to wrap the store and return function to get the state with store.
+ */
+declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
+
+export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ISlices, type Middleware, type Slice, type SliceState, type Slices, type Store, type StoreOptions, create, createBinder, wrapStore };