{"_id":"@arashgh/storagets","name":"@arashgh/storagets","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@arashgh/storagets","author":{"name":"Arash Ghorban","url":"https://github.com/0x0arash"},"description":"A typesafe localstorage manager for React and Next.js applications.","version":"0.0.1","license":"MIT","homepage":"https://github.com/0x0arash/storagets","repository":{"type":"git","url":"git+https://github.com/0x0arash/storagets.git","directory":"packages/storagets"},"keywords":["nextjs","react","reactjs","reactjs library","reactjs storage","typescript","localstorage","storage","storage library","storage manager","typesafe","validation","typed storage","typed localstorage"],"type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"devDependencies":{"@types/react":"^19.0.0","@types/react-dom":"^19.0.0","react":"^19.0.0","react-dom":"^19.0.0","typescript":"latest","@storagets/eslint-config":"0.0.0","@storagets/typescript-config":"0.0.0"},"peerDependencies":{"react":"^19.0.0","react-dom":"^19.0.0"},"scripts":{"dev":"tsc --watch","build":"tsc"},"_id":"@arashgh/storagets@0.0.1","bugs":{"url":"https://github.com/0x0arash/storagets/issues"},"_integrity":"sha512-4fVSunK4DAJ+U7QTCZUFgy3buajcLlmMhNS0+KxreS7ohheeJz9ik1b+aFbfnYHGuGgpoFvtNLNDmmGz8aoVzQ==","_resolved":"C:\\Users\\ghorb\\AppData\\Local\\Temp\\7cddd5bd18b8104413cc02fea81dc9e1\\arashgh-storagets-0.0.1.tgz","_from":"file:arashgh-storagets-0.0.1.tgz","_nodeVersion":"22.15.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-4fVSunK4DAJ+U7QTCZUFgy3buajcLlmMhNS0+KxreS7ohheeJz9ik1b+aFbfnYHGuGgpoFvtNLNDmmGz8aoVzQ==","shasum":"3add8cdf3e6fe143b20e9212ea1b90ca8d019b3d","tarball":"https://registry.npmjs.org/@arashgh/storagets/-/storagets-0.0.1.tgz","fileCount":13,"unpackedSize":8969,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGdcvOk5yBOvEX+YToVhswTr9yl9I4xzVEtVMARO6Gm3AiBRWLvMrJdB9MknyaqKmFiqRF8Xtt0+/YqadsGIAd1X9w=="}]},"_npmUser":{"name":"arashgh","email":"ghorbanarash@gmail.com"},"directories":{},"maintainers":[{"name":"arashgh","email":"ghorbanarash@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/storagets_0.0.1_1746979518435_0.13532307587464"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-11T16:05:18.324Z","0.0.1":"2025-05-11T16:05:18.717Z","modified":"2025-05-11T16:05:19.023Z"},"maintainers":[{"name":"arashgh","email":"ghorbanarash@gmail.com"}],"description":"A typesafe localstorage manager for React and Next.js applications.","homepage":"https://github.com/0x0arash/storagets","keywords":["nextjs","react","reactjs","reactjs library","reactjs storage","typescript","localstorage","storage","storage library","storage manager","typesafe","validation","typed storage","typed localstorage"],"repository":{"type":"git","url":"git+https://github.com/0x0arash/storagets.git","directory":"packages/storagets"},"author":{"name":"Arash Ghorban","url":"https://github.com/0x0arash"},"bugs":{"url":"https://github.com/0x0arash/storagets/issues"},"license":"MIT","readme":"# StorageTS\r\n\r\nA type-safe localStorage wrapper for React applications with built-in validation support.\r\n\r\n## Features\r\n\r\n- 🦾 Type-safe storage operations\r\n- ✨ Built-in validation support\r\n- 🔄 Automatic state synchronization\r\n- 📦 Zero dependencies (except React)\r\n- 🎯 Next.js compatible with \"use client\" support\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @arashgh/storagets\r\n# or\r\nyarn add @arashgh/storagets\r\n# or\r\npnpm add @arashgh/storagets\r\n```\r\n\r\n## Basic Usage\r\n\r\n```tsx\r\nimport { useStorageTS } from \"@arashgh/storagets\";\r\n\r\nfunction Counter() {\r\n  const [storage, setStorage] = useStorageTS(\"my-counter\", {\r\n    count: 0,\r\n  });\r\n\r\n  return (\r\n    <div>\r\n      <p>Count: {storage.count}</p>\r\n      <button\r\n        onClick={() =>\r\n          setStorage((prev) => ({\r\n            ...prev,\r\n            count: prev.count + 1,\r\n          }))\r\n        }\r\n      >\r\n        Increment\r\n      </button>\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n## Type-Safe Validation\r\n\r\n```tsx\r\ninterface UserPreferences {\r\n  theme: \"light\" | \"dark\";\r\n  fontSize: number;\r\n}\r\n\r\nfunction Settings() {\r\n  const [preferences, setPreferences] = useStorageTS<UserPreferences>(\r\n    \"user-preferences\",\r\n    {\r\n      theme: \"light\",\r\n      fontSize: 16,\r\n    },\r\n    (value) => {\r\n      const v = value as UserPreferences;\r\n      if (v.theme !== \"light\" && v.theme !== \"dark\") {\r\n        throw new Error(\"Invalid theme\");\r\n      }\r\n      if (\r\n        typeof v.fontSize !== \"number\" ||\r\n        v.fontSize < 12 ||\r\n        v.fontSize > 24\r\n      ) {\r\n        throw new Error(\"Invalid font size\");\r\n      }\r\n      return v;\r\n    }\r\n  );\r\n\r\n  return (\r\n    <div>\r\n      <select\r\n        value={preferences.theme}\r\n        onChange={(e) =>\r\n          setPreferences((prev) => ({\r\n            ...prev,\r\n            theme: e.target.value as \"light\" | \"dark\",\r\n          }))\r\n        }\r\n      >\r\n        <option value=\"light\">Light</option>\r\n        <option value=\"dark\">Dark</option>\r\n      </select>\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n## Using with Zod\r\n\r\n```tsx\r\nimport { z } from \"zod\";\r\nimport { useStorageTS } from \"@arashgh/storagets\";\r\n\r\nconst UserSchema = z.object({\r\n  name: z.string().min(2),\r\n  age: z.number().min(0).max(120),\r\n  preferences: z.object({\r\n    theme: z.enum([\"light\", \"dark\"]),\r\n    notifications: z.boolean(),\r\n  }),\r\n});\r\n\r\ntype User = z.infer<typeof UserSchema>;\r\n\r\nfunction UserProfile() {\r\n  const [user, setUser] = useStorageTS<User>(\r\n    \"user-profile\",\r\n    {\r\n      name: \"\",\r\n      age: 0,\r\n      preferences: {\r\n        theme: \"light\",\r\n        notifications: true,\r\n      },\r\n    },\r\n    (value) => UserSchema.parse(value)\r\n  );\r\n\r\n  return (\r\n    <div>\r\n      <input\r\n        type=\"text\"\r\n        value={user.name}\r\n        onChange={(e) =>\r\n          setUser((prev) => ({\r\n            ...prev,\r\n            name: e.target.value,\r\n          }))\r\n        }\r\n      />\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n## API Reference\r\n\r\n### `useStorageTS<T>`\r\n\r\n```tsx\r\nfunction useStorageTS<T extends Record<string, unknown>>(\r\n  key: string,\r\n  defaultValue: T,\r\n  validatorFn?: (data: unknown) => T\r\n): [\r\n  T,\r\n  (updateOrValue: T | ((prev: T) => T), options?: { merge?: boolean }) => void,\r\n];\r\n```\r\n\r\n#### Parameters\r\n\r\n- `key`: Storage key for localStorage\r\n- `defaultValue`: Default value if nothing is stored\r\n- `validatorFn`: (Optional) Validation function that throws on invalid data\r\n\r\n#### Returns\r\n\r\nA tuple containing:\r\n\r\n- Current state (`T`)\r\n- Setter function that accepts either:\r\n  - New value of type `T`\r\n  - Update function `(prev: T) => T`\r\n  - Optional `merge` option for partial updates\r\n\r\n## Partial Updates\r\n\r\n```tsx\r\nconst [userData, setUserData] = useStorageTS(\"user-data\", {\r\n  name: \"\",\r\n  settings: { theme: \"light\" },\r\n});\r\n\r\n// Merge update\r\nsetUserData({ settings: { theme: \"dark\" } }, { merge: true });\r\n```\r\n\r\n## TypeScript Support\r\n\r\nStorageTS is written in TypeScript and provides full type safety out of the box. It will show type errors for:\r\n\r\n- Invalid data structures\r\n- Incorrect property access\r\n- Type mismatches in update functions\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Author\r\n\r\n[Arash Ghorban](https://github.com/0x0arash)\r\n\r\n## Contributing\r\n\r\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\r\n","readmeFilename":"README.md","_rev":"1-15ecc95c7beb9a56f639eb03fbbf0a71"}