@warkypublic/zustandsyncstore 0.0.1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": true,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @warkypublic/zustandsyncstore
+
+## 0.0.1
+
+### Patch Changes
+
+- 0ed2a54: First Release

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2021 Vitaly Rtishchev
+
+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 

package/README.md

@@ -0,0 +1,205 @@
+# ZustandSyncStore
+
+A React library that provides synchronized Zustand stores with prop-based state management and persistence support.
+
+## Features
+
+- **Prop Synchronization**: Automatically sync React props with Zustand store state
+- **Context-based**: Provides a Provider/Consumer pattern for scoped store access
+- **Persistence**: Built-in support for state persistence via Zustand middleware
+- **TypeScript**: Full TypeScript support with type inference
+- **Selective Sync**: Control which props are synced and when
+
+## Installation
+
+```bash
+npm install @warkypublic/zustandsyncstore
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm install react zustand use-sync-external-store
+```
+
+## Basic Usage
+
+```tsx
+import { createSyncStore } from '@warkypublic/zustandsyncstore';
+
+// Define your state type
+interface MyState {
+  count: number;
+  increment: () => void;
+}
+
+// Define your props type
+interface MyProps {
+  initialCount: number;
+}
+
+// Create the synchronized store
+const { Provider, useStore } = createSyncStore<MyState, MyProps>(
+  (set) => ({
+    count: 0,
+    increment: () => set((state) => ({ count: state.count + 1 })),
+  })
+);
+
+// Component that uses the store
+function Counter() {
+  const { count, increment } = useStore();
+  
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={increment}>Increment</button>
+    </div>
+  );
+}
+
+// App component with Provider
+function App() {
+  return (
+    <Provider initialCount={10}>
+      <Counter />
+    </Provider>
+  );
+}
+```
+
+## Advanced Usage
+
+### With Custom Hook Logic
+
+```tsx
+const { Provider, useStore } = createSyncStore<MyState, MyProps>(
+  (set) => ({
+    count: 0,
+    increment: () => set((state) => ({ count: state.count + 1 })),
+  }),
+  ({ useStore, useStoreApi, initialCount }) => {
+    // Custom hook logic here
+    const currentCount = useStore(state => state.count);
+    
+    // Return additional props to sync
+    return {
+      computedValue: initialCount * 2
+    };
+  }
+);
+```
+
+### With Persistence
+
+```tsx
+function App() {
+  return (
+    <Provider 
+      initialCount={10}
+      persist={{
+        name: 'my-store',
+        storage: localStorage,
+      }}
+    >
+      <Counter />
+    </Provider>
+  );
+}
+```
+
+### Selective Prop Syncing
+
+```tsx
+function App() {
+  return (
+    <Provider 
+      initialCount={10}
+      otherProp="value"
+      firstSyncProps={['initialCount']} // Only sync these props initially
+    >
+      <Counter />
+    </Provider>
+  );
+}
+```
+
+## API Reference
+
+### `createSyncStore<TState, TProps>(createState?, useValue?)`
+
+Creates a synchronized Zustand store.
+
+**Parameters:**
+- `createState` (optional): Zustand state creator function
+- `useValue` (optional): Custom hook function that receives props and store access
+
+**Returns:**
+- `Provider`: React component that provides the store context
+- `useStore`: Hook to access the store state
+
+### Provider Props
+
+- `children`: React children
+- `firstSyncProps` (optional): Array of prop names to sync only on first render
+- `persist` (optional): Zustand persist options
+- `...TProps`: Your custom props that will be synced with the store
+
+### useStore Hook
+
+Can be used with or without a selector:
+
+```tsx
+// Get entire state
+const state = useStore();
+
+// With selector
+const count = useStore(state => state.count);
+
+// With equality function
+const count = useStore(state => state.count, (a, b) => a === b);
+```
+
+## TypeScript Support
+
+The library is fully typed and provides type inference for your state and props:
+
+```tsx
+interface State {
+  value: string;
+}
+
+interface Props {
+  defaultValue: string;
+}
+
+const { Provider, useStore } = createSyncStore<State, Props>(...);
+
+// TypeScript will infer the correct types
+const { value } = useStore(); // value is string
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run development server
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Run linting
+pnpm lint
+
+# Run type checking
+pnpm typecheck
+```
+
+## License
+
+MIT

package/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { globalIgnores } from 'eslint/config'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs['recommended-latest'],
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@warkypublic/zustandsyncstore",
+  "author": "Warky Devs",
+  "version": "0.0.1",
+  "type": "module",
+  "module": "./dist/lib.es.js",
+  "types": "./dist/lib.d.ts",
+  "publishConfig": {
+    "require": "./dist/lib.cjs.js"
+  },
+  "dependencies": {
+    "@warkypublic/artemis-kit": "^1.0.10"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@types/node": "^24.4.0",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "@typescript-eslint/parser": "^8.43.0",
+    "@vitejs/plugin-react-swc": "^4.0.1",
+    "@changesets/cli": "^2.29.7",
+    "eslint": "^9.35.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "global": "^4.4.0",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2",
+    "prettier-eslint": "^16.4.2",
+    "react-dom": "^19.1.1",
+    "typescript": "~5.9.2",
+    "typescript-eslint": "^8.43.0",
+    "vite": "^7.1.5",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "peerDependencies": {
+    "react": ">= 19.0.0",
+    "use-sync-external-store": ">= 1.4.0",
+    "zustand": ">= 5.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint ./src",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf node_modules && rm -rf dist ",
+    "preview": "vite preview"
+  },
+  "main": "./dist/lib.cjs.js",
+  "typings": "./dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/lib.es.js",
+      "types": "./dist/lib.d.ts",
+      "default": "./dist/lib.cjs.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/src/SyncStore.tsx

@@ -0,0 +1,170 @@
+
+import {decycle} from '@warkypublic/artemis-kit/object'
+import React, { createContext, type ReactNode, useContext, useLayoutEffect, useRef } from 'react';
+import { createStore as createZustandStore, type StateCreator, type StoreApi } from 'zustand';
+import { persist, type PersistOptions } from 'zustand/middleware';
+import { useShallow } from 'zustand/react/shallow';
+import { useStoreWithEqualityFn } from 'zustand/traditional';
+
+export type SyncStoreReturn<TState, TProps> = {
+  Provider: (
+    props: {
+      children: ReactNode;
+    } & {
+      firstSyncProps?: string[];
+      persist?: PersistOptions<Partial<TProps & TState>>;
+    } & TProps
+  ) => React.ReactNode;
+  useStore: {
+    (): LocalUseStore<TState, TProps>;
+    <U>(
+      selector: (state: LocalUseStore<TState, TProps>) => U,
+      equalityFn?: (a: U, b: U) => boolean
+    ): U;
+  };
+};
+
+type CreateContextUseStore<TState> = {
+  (): TState;
+  <U>(selector: (state: TState) => U, equalityFn?: (a: U, b: U) => boolean): U;
+};
+
+type LocalUseStore<TState, TProps> = {
+  $sync?: (props: TProps) => void;
+} & TState;
+
+export function createSyncStore<TState, TProps>(
+  createState?: StateCreator<TState>,
+  useValue?: (
+    props: {
+      useStore: CreateContextUseStore<LocalUseStore<TState, TProps>>;
+      useStoreApi: StoreApi<LocalUseStore<TState, TProps>>;
+    } & TProps
+  ) => any
+): SyncStoreReturn<TState, TProps> {
+  const StoreContext = createContext<null | StoreApi<LocalUseStore<TState, TProps>>>(null);
+
+  function useStore(): LocalUseStore<TState, TProps>;
+  function useStore<U>(
+    selector: (state: LocalUseStore<TState, TProps>) => U,
+    equalityFn?: (a: U, b: U) => boolean
+  ): U;
+  function useStore<U>(
+    selector?: (state: LocalUseStore<TState, TProps>) => U,
+    equalityFn?: (a: U, b: U) => boolean
+  ) {
+    const store = useContext(StoreContext);
+    if (!store) {
+      throw new Error('Missing StoreProvider');
+    }
+    return useStoreWithEqualityFn(
+      store,
+      selector ? useShallow(selector) : (state) => state as unknown as U,
+      equalityFn
+    );
+  }
+
+  const Hook = ({
+    firstSyncProps,
+    ...others
+  }: {
+    firstSyncProps: string[];
+  } & TProps) => {
+    const syncedProps = useRef(false);
+
+    const { $sync } = useStore((state) => ({ $sync: state.$sync }));
+    const storeApi = useContext<null | StoreApi<LocalUseStore<TState, TProps>>>(StoreContext);
+
+    if (firstSyncProps) {
+      for (const key of firstSyncProps) {
+        if (syncedProps.current) {
+          //@ts-ignore
+          delete others[key];
+        }
+      }
+    }
+
+    useLayoutEffect(
+      () => {
+        //@ts-ignore
+        $sync?.(others);
+        //method was actually called
+        if ($sync) {
+          syncedProps.current = true;
+        }
+      },
+      [JSON.stringify(decycle(others ?? {}))]
+    );
+
+    if (useValue) {
+      // @ts-ignore
+      const returned = useValue({
+        ...others,
+        useStore,
+        useStoreApi: storeApi
+      });
+
+      useLayoutEffect(() => {
+        if (returned && typeof returned === 'object') {$sync?.(returned);}
+      }, [returned]);
+    }
+
+    return null;
+  };
+
+  // eslint-disable-next-line no-param-reassign
+  createState = createState || (() => ({}) as TState);
+
+  const StoreProvider = (
+    props: {
+      children: ReactNode;
+    } & {
+      firstSyncProps?: string[];
+      persist?: PersistOptions<Partial<TProps & TState>>;
+    } & TProps
+  ) => {
+    const storeRef = useRef<StoreApi<LocalUseStore<TState, TProps>>>(null);
+
+    const { children, ...propsWithoutChildren } = props;
+
+    if (!storeRef.current) {
+      if (props?.persist) {
+        storeRef.current = createZustandStore<LocalUseStore<TState, TProps>>(
+          //@ts-ignore
+          persist(
+            //@ts-ignore
+            (set, get, api) => ({
+              //@ts-ignore
+              ...createState?.(set, get, api),
+              $sync: (props: TProps) => set((state) => ({ ...state, ...props }))
+            }),
+            { ...props?.persist }
+          )
+        );
+      } else {
+        storeRef.current = createZustandStore<LocalUseStore<TState, TProps>>(
+          // @ts-ignore
+          (set, get, api) => ({
+            ...createState?.(set, get, api),
+            $sync: (props: TProps) => set((state) => ({ ...state, ...props }))
+          })
+        );
+      }
+    }
+
+    return (
+      <StoreContext.Provider value={storeRef.current}>
+        {/* @ts-ignore*/}
+        <Hook {...propsWithoutChildren} firstSyncProps={props.firstSyncProps} />
+        {children}
+      </StoreContext.Provider>
+    );
+  };
+
+  return {
+    Provider: StoreProvider,
+    useStore
+  };
+}
+
+export default createSyncStore;

package/src/lib.ts

@@ -0,0 +1 @@
+export {createSyncStore, type SyncStoreReturn} from './SyncStore'

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/tsconfig.app.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/tsconfig.node.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "vite";
+import { dirname } from "node:path";
+import * as path from "path";
+import { fileURLToPath } from "node:url";
+import react from "@vitejs/plugin-react-swc";
+import { peerDependencies } from "./package.json";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, "src/lib.ts"),
+      name: "lib",
+      formats: ["es", "cjs"],
+      fileName: (format) => `lib.${format}.js`,
+    },
+    emptyOutDir: true,
+    rollupOptions: {
+      external: Object.keys(peerDependencies),
+    },
+  },
+});