{"_id":"@abdu-selam/smart-storage","_rev":"3-71acc8c3fbc2b2a6614a5e770845e1d3","name":"@abdu-selam/smart-storage","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@abdu-selam/smart-storage","version":"1.0.0","keywords":["storage","localstorage","sessionstorage","typescript","javascript","browser-storage"],"author":{"name":"Abduselam Awel"},"_id":"@abdu-selam/smart-storage@1.0.0","maintainers":[{"name":"abdu-selam","email":"abdselam676@gmail.com"}],"homepage":"https://github.com/abdu-selam/smart-storage#readme","bugs":{"url":"https://github.com/abdu-selam/smart-storage/issues"},"dist":{"shasum":"076ba449e457f90c57244810799811cd82e1d1f2","tarball":"https://registry.npmjs.org/@abdu-selam/smart-storage/-/smart-storage-1.0.0.tgz","fileCount":33,"integrity":"sha512-6tlkXZHh6Kf3XZoHXXxTzm1Hg08HM/tlxgmaIdP+ufIMax19QGr/ekKd/b6TlGoGCh2RvbWoJwFxqssc9bT8WQ==","signatures":[{"sig":"MEYCIQCIyxs9xCbq6ZS/Iai6Y+ZEU33vxGbG14WrWA0Ihy8SyAIhAJbQ+PGcHBVNbKgVrlFstaDZIy6GhyR3TzNcXmuvGt4v","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43855},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":{"import":"./dist/index.d.mts","require":"./dist/index.d.cts"},"import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"a79e9979c8a814caf35f51b0b536c4d727d6ff6d","scripts":{"dev":"tsx watch ./src/index.ts","build":"tsdown","prepublishOnly":"npm run build"},"_npmUser":{"name":"abdu-selam","email":"abdselam676@gmail.com"},"repository":{"url":"git+https://github.com/abdu-selam/smart-storage.git","type":"git"},"_npmVersion":"12.0.2","description":"A simple and powerfull storage api that allow you to handle localStorage and sessionStorage easily.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.12","tsdown":"^0.23.0","typescript":"^7.0.2","@types/node":"^26.2.0"},"_npmOperationalInternal":{"tmp":"tmp/smart-storage_1.0.0_1788759670297_0.7650392960931212","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abdu-selam/smart-storage","version":"1.0.1","keywords":["storage","localstorage","sessionstorage","typescript","javascript","browser-storage"],"author":{"name":"Abduselam Awel"},"license":"MIT","_id":"@abdu-selam/smart-storage@1.0.1","maintainers":[{"name":"abdu-selam","email":"abdselam676@gmail.com"}],"homepage":"https://github.com/abdu-selam/smart-storage#readme","bugs":{"url":"https://github.com/abdu-selam/smart-storage/issues"},"dist":{"shasum":"5c86826e9c954e8a38d95ac3b28617e4fc170b51","tarball":"https://registry.npmjs.org/@abdu-selam/smart-storage/-/smart-storage-1.0.1.tgz","fileCount":35,"integrity":"sha512-nW7yeWr4jvd4nk0djILt6INr7k7cciUVQmDQDBsYP6bN7VIYnHxry1FDycXlALcYRjdm3oS95a2IKqcIlkmocw==","signatures":[{"sig":"MEQCIF5uxjmdBX3miUves8/85UzfQMAYSKFLfe8+hYHSmjkPAiBHTNQGhMU9ceYTzqlGyfzlYqDuc5lGgLFCElFk68np/Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51103},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":{"import":"./dist/index.d.mts","require":"./dist/index.d.cts"},"import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"79cce9f013bf6074aeb921a824f40d54353d4976","scripts":{"dev":"tsx watch ./src/index.ts","build":"tsdown","prepublishOnly":"npm run build"},"_npmUser":{"name":"abdu-selam","email":"abdselam676@gmail.com"},"repository":{"url":"git+https://github.com/abdu-selam/smart-storage.git","type":"git"},"_npmVersion":"12.0.2","description":"A simple and powerfull storage api that allow you to handle localStorage and sessionStorage easily.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.12","tsdown":"^0.23.0","typescript":"^7.0.2","@types/node":"^26.2.0"},"_npmOperationalInternal":{"tmp":"tmp/smart-storage_1.0.1_1788763158488_0.8800741178553069","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"_id":"@abdu-selam/smart-storage@1.1.1","bugs":{"url":"https://github.com/abdu-selam/smart-storage/issues"},"dist":{"shasum":"63aa47139cdfbfec519be78d7d495a46237000e9","tarball":"https://registry.npmjs.org/@abdu-selam/smart-storage/-/smart-storage-1.1.1.tgz","fileCount":56,"integrity":"sha512-XTk3FCUnt2P61bJQUYD2AqqebR8ffaf0DSi6JbynbHD4VFqybxPgImyb0DX3ko612iq4Pl7NO0HeWvGHKwCCyw==","signatures":[{"sig":"MEUCIQDGb2b1jCIMOXbIMV+bQqJZkyTbi0q8uXMI72PXCW5/wgIgZ5Ksxp/6QjsO8FpSONQegTLzl37Vo8hPj5kH1lqbQfs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD/g9toSifKDs+8S43pEvVaMFWj05no2DgLz7h2IgbB8gIhAKrCdjf5n/eIHcWs/0kttnu6miCBiuRQvE5lXnRyMDvW"}],"unpackedSize":109881},"main":"./dist/index.cjs","name":"@abdu-selam/smart-storage","type":"module","types":"./dist/index.d.mts","author":{"name":"Abduselam Awel"},"module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":{"import":"./dist/index.d.mts","require":"./dist/index.d.cts"},"import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"18e01580a1ba7f00ec0065e2970ac69547d6c5b8","license":"MIT","scripts":{"dev":"tsx watch ./src/index.ts","build":"tsdown","prepublishOnly":"npm run build"},"version":"1.1.1","_npmUser":{"name":"abdu-selam","email":"abdselam676@gmail.com"},"homepage":"https://github.com/abdu-selam/smart-storage#readme","keywords":["storage","localstorage","sessionstorage","typescript","javascript","browser-storage"],"repository":{"url":"git+https://github.com/abdu-selam/smart-storage.git","type":"git"},"_npmVersion":"12.0.2","description":"A TypeScript storage utility for managing browser localStorage, sessionStorage, and JSON files with a simple, consistent API.","directories":{},"maintainers":[{"name":"abdu-selam","email":"abdselam676@gmail.com"}],"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.12","tsdown":"^0.23.0","typescript":"^7.0.2","@types/node":"^26.2.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smart-storage_1.1.1_1789583484743_0.1354202391043915"}}},"time":{"created":"2026-09-07T05:41:09.980Z","modified":"2026-09-16T18:31:24.969Z","1.0.0":"2026-09-07T05:41:10.434Z","1.0.1":"2026-09-07T06:39:18.632Z","1.1.1":"2026-09-16T18:31:24.835Z"},"bugs":{"url":"https://github.com/abdu-selam/smart-storage/issues"},"author":{"name":"Abduselam Awel"},"license":"MIT","homepage":"https://github.com/abdu-selam/smart-storage#readme","keywords":["storage","localstorage","sessionstorage","typescript","javascript","browser-storage"],"repository":{"url":"git+https://github.com/abdu-selam/smart-storage.git","type":"git"},"description":"A TypeScript storage utility for managing browser localStorage, sessionStorage, and JSON files with a simple, consistent API.","maintainers":[{"name":"abdu-selam","email":"abdselam676@gmail.com"}],"readme":"# Smart Storage\n\nA lightweight TypeScript storage utility with a simple, consistent API for working with:\n\n- Browser `localStorage`\n- Browser `sessionStorage`\n- JSON files in Node.js\n\nIt supports regular and deeply nested data access, updates through callbacks, key management, and JSON file persistence.\n\n## Features\n\n- TypeScript-first API with type declarations\n- ESM and CommonJS support\n- `localStorage` and `sessionStorage` support\n- JSON file storage for Node.js\n- Get and set individual values\n- Get and set deeply nested objects and arrays with dot notation\n- Update values with callback functions\n- Set or retrieve multiple values\n- Check whether keys or nested paths exist\n- Remove individual values\n- Clear stored data\n- JSON file validation with `isJson()`\n- Automatic creation of a JSON file when using `JsonStorage`\n\n## Installation\n\n```bash\nnpm install @abdu-selam/smart-storage\n```\n\n## Browser Storage\n\n`BrowserStorage` provides a wrapper around the browser's native `localStorage` and `sessionStorage` APIs.\n\n### Import\n\n```ts\nimport { BrowserStorage } from \"@abdu-selam/smart-storage\";\n```\n\n### Create a storage instance\n\nFor `localStorage`:\n\n```ts\nconst storage = new BrowserStorage(\"local\");\n```\n\nFor `sessionStorage`:\n\n```ts\nconst storage = new BrowserStorage(\"session\");\n```\n\nThe constructor accepts:\n\n```ts\n\"local\" | \"session\"\n```\n\n### Set and get values\n\n```ts\nstorage.set(\"username\", \"Abdu\");\n\nconst username = storage.get(\"username\");\n\nconsole.log(username);\n// \"Abdu\"\n```\n\nIf a key does not exist, `get()` returns `null`.\n\nNumeric keys are also supported:\n\n```ts\nstorage.set(1, \"Hello\");\n\nconsole.log(storage.get(1));\n// \"Hello\"\n```\n\n### Get all values\n\n```ts\nconst data = storage.getAll();\n\nconsole.log(data);\n```\n\n`getAll()` returns a cloned copy of the current storage data.\n\n### Deep get\n\nUse `deepGet()` to access values inside nested objects or arrays.\n\n```ts\nstorage.set(\"user\", {\n  name: \"Abdu\",\n  profile: {\n    age: 22\n  }\n});\n\nconst age = storage.deepGet(\"user.profile.age\");\n\nconsole.log(age);\n// 22\n```\n\nArray indexes are supported:\n\n```ts\nstorage.set(\"users\", [\n  { name: \"Abdu\" },\n  { name: \"John\" }\n]);\n\nconsole.log(storage.deepGet(\"users.0.name\"));\n// \"Abdu\"\n```\n\n### Deep set\n\nUse `deepSet()` to create or modify nested values.\n\n```ts\nstorage.deepSet(\"user.profile.name\", \"Abdu\");\n```\n\nArray indexes are supported as well:\n\n```ts\nstorage.deepSet(\"users.0.name\", \"Abdu\");\n```\n\nIf the required nested structure does not exist, `deepSet()` creates the required objects or arrays.\n\n### Update values\n\n`update()` receives the current value and stores the value returned by the callback.\n\n```ts\nstorage.set(\"counter\", 10);\n\nstorage.update(\"counter\", (current) => current + 1);\n\nconsole.log(storage.get(\"counter\"));\n// 11\n```\n\nNested values can also be updated:\n\n```ts\nstorage.set(\"user\", {\n  name: \"Abdu\",\n  age: 21\n});\n\nstorage.update(\"user.age\", (age) => age + 1);\n\nconsole.log(storage.deepGet(\"user.age\"));\n// 22\n```\n\n### Set multiple values\n\n```ts\nstorage.setAll({\n  username: \"Abdu\",\n  age: 22,\n  role: \"developer\"\n});\n```\n\n### Check for a key\n\n```ts\nconsole.log(storage.has(\"username\"));\n// true\n```\n\nNested paths are supported:\n\n```ts\nconsole.log(storage.has(\"user.profile.age\"));\n// true\n```\n\nArray indexes are supported:\n\n```ts\nconsole.log(storage.has(\"users.0.name\"));\n// true\n```\n\n### Get all keys\n\n```ts\nconst keys = storage.keys();\n\nconsole.log(keys);\n```\n\nExample:\n\n```ts\n[\"username\", \"age\", \"role\"]\n```\n\n### Remove a value\n\n```ts\nstorage.remove(\"username\");\n```\n\nNumeric keys are supported:\n\n```ts\nstorage.remove(1);\n```\n\n### Clear storage\n\n`clear()` removes all data from the selected browser storage.\n\n```ts\nstorage.clear();\n```\n\nThis clears either `localStorage` or `sessionStorage`, depending on how the instance was created.\n\n---\n\n## JSON File Storage\n\n`JsonStorage` provides an asynchronous API for storing data in JSON files and is intended for Node.js environments.\n\n### Import\n\n```ts\nimport { JsonStorage } from \"@abdu-selam/smart-storage\";\n```\n\n### Create a JSON storage instance\n\n```ts\nconst storage = new JsonStorage(\"./data.json\");\n```\n\nIf the file does not exist or is not a valid JSON file, the storage initializes it with an empty object.\n\n### Set and get values\n\n```ts\nawait storage.set(\"username\", \"Abdu\");\n\nconst username = await storage.get(\"username\");\n\nconsole.log(username);\n// \"Abdu\"\n```\n\n### Get all data\n\n```ts\nconst data = await storage.getAll();\n\nconsole.log(data);\n```\n\n### Deep get\n\n```ts\nawait storage.set(\"user\", {\n  name: \"Abdu\",\n  profile: {\n    age: 22\n  }\n});\n\nconst age = await storage.deepGet(\"user.profile.age\");\n\nconsole.log(age);\n// 22\n```\n\nArrays are supported:\n\n```ts\nawait storage.set(\"users\", [\n  { name: \"Abdu\" },\n  { name: \"John\" }\n]);\n\nconsole.log(await storage.deepGet(\"users.0.name\"));\n// \"Abdu\"\n```\n\n### Deep set\n\n```ts\nawait storage.deepSet(\"user.profile.name\", \"Abdu\");\n```\n\nNested arrays are also supported:\n\n```ts\nawait storage.deepSet(\"users.0.name\", \"Abdu\");\n```\n\n### Update values\n\n```ts\nawait storage.set(\"counter\", 10);\n\nawait storage.update(\"counter\", (current) => current + 1);\n\nconsole.log(await storage.get(\"counter\"));\n// 11\n```\n\n### Set multiple values\n\n```ts\nawait storage.setAll({\n  username: \"Abdu\",\n  age: 22,\n  role: \"developer\"\n});\n```\n\n`setAll()` accepts either an object or an array.\n\n### Check for a key\n\n```ts\nconst exists = await storage.has(\"username\");\n\nconsole.log(exists);\n// true\n```\n\nNested paths are supported:\n\n```ts\nconst exists = await storage.has(\"user.profile.age\");\n```\n\n### Get keys\n\n```ts\nconst keys = await storage.keys();\n\nconsole.log(keys);\n```\n\nFor object data:\n\n```ts\n[\"username\", \"age\", \"role\"]\n```\n\nFor array data:\n\n```ts\n[0, 1, 2]\n```\n\n### Get array length\n\n`length()` returns the length when the root JSON value is an array.\n\n```ts\nconst length = await storage.length();\n\nconsole.log(length);\n// 3\n```\n\nFor a root object, it returns `null`.\n\n### Remove data\n\n```ts\nawait storage.remove(\"username\");\n```\n\nFor a root array, provide an array index:\n\n```ts\nawait storage.remove(0);\n```\n\n### Clear the JSON file\n\n```ts\nawait storage.clear();\n```\n\nThe root value becomes an empty object or empty array, depending on the current root data type.\n\n### Check whether a file is valid JSON\n\nYou can check an instance:\n\n```ts\nconst valid = await storage.isJson();\n\nconsole.log(valid);\n```\n\nYou can also use the static method without creating an instance:\n\n```ts\nconst valid = await JsonStorage.isJson(\"./data.json\");\n\nconsole.log(valid);\n```\n\n---\n\n## API Reference\n\n### `BrowserStorage`\n\n| Method | Return type | Description |\n|---|---|---|\n| `getAll()` | `Record<string, unknown>` | Returns all stored data |\n| `get(key)` | `unknown \\| null` | Gets a value by key |\n| `deepGet(key)` | `unknown \\| null` | Gets a nested value using dot notation |\n| `set(key, value)` | `void` | Stores a value |\n| `deepSet(key, value)` | `void` | Sets a nested value |\n| `update(key, callback)` | `void` | Updates a value using a callback |\n| `setAll(data)` | `void` | Stores multiple values |\n| `remove(key)` | `void` | Removes a value |\n| `clear()` | `void` | Clears the selected browser storage |\n| `keys()` | `string[]` | Returns top-level keys |\n| `has(key)` | `boolean` | Checks whether a key or nested path exists |\n\n### `JsonStorage`\n\n| Method | Return type | Description |\n|---|---|---|\n| `getAll()` | `Promise<JsonDataType>` | Returns all JSON data |\n| `get(key)` | `Promise<unknown>` | Gets a value by key |\n| `deepGet(key)` | `Promise<unknown>` | Gets a nested value |\n| `set(key, value)` | `Promise<void>` | Stores a value |\n| `deepSet(key, value)` | `Promise<void>` | Sets a nested value |\n| `update(key, callback)` | `Promise<void>` | Updates a value using a callback |\n| `setAll(data)` | `Promise<void>` | Replaces the stored data |\n| `remove(key)` | `Promise<void>` | Removes a value or array item |\n| `clear()` | `Promise<void>` | Clears the JSON data |\n| `keys()` | `Promise<(string \\| number)[]>` | Returns object keys or array indexes |\n| `length()` | `Promise<number \\| null>` | Returns root array length |\n| `has(key)` | `Promise<boolean>` | Checks whether a key or nested path exists |\n| `isJson()` | `Promise<boolean>` | Checks whether the storage file is valid JSON |\n\n## Error Handling\n\nThe package includes custom errors for invalid input:\n\n### `ConstructionError`\n\nThrown when `BrowserStorage` receives an invalid storage type.\n\n```ts\nnew BrowserStorage(\"invalid\");\n```\n\nValid values are:\n\n```ts\n\"local\"\n\"session\"\n```\n\n### `InvalidKeyError`\n\nThrown when a key is not a string or number, or when an invalid key is used with array storage.\n\n### `InvalidValueError`\n\nThrown when `undefined` is passed to operations that require a value.\n\n### `InvalidDataError`\n\nThrown when invalid data is passed to `setAll()`.\n\n### `InvalidFunctionError`\n\nThrown when the callback passed to `update()` is not a function.\n\n## Browser and Node.js Support\n\n### Browser\n\nUse `BrowserStorage` in environments that provide the Web Storage API:\n\n- `localStorage`\n- `sessionStorage`\n\n```ts\nconst storage = new BrowserStorage(\"local\");\n```\n\n### Node.js\n\nUse `JsonStorage` for JSON file persistence:\n\n```ts\nconst storage = new JsonStorage(\"./data.json\");\n```\n\n`JsonStorage` uses Node.js file-system APIs and should not be used directly in a browser environment.\n\n## TypeScript\n\nThe package is written in TypeScript and includes generated type declarations.\n\nYou can import the provided types when needed:\n\n```ts\nimport type {\n  StorageType,\n  UpdateCallback,\n  JsonStorageType,\n  JsonDataType\n} from \"@abdu-selam/smart-storage\";\n```\n\n## ESM and CommonJS\n\nThe package provides both ESM and CommonJS builds.\n\nESM:\n\n```ts\nimport { BrowserStorage, JsonStorage } from \"@abdu-selam/smart-storage\";\n```\n\nCommonJS:\n\n```js\nconst {\n  BrowserStorage,\n  JsonStorage\n} = require(\"@abdu-selam/smart-storage\");\n```\n\n## Important Notes\n\n- `BrowserStorage` depends on the browser's native Storage API.\n- `JsonStorage` performs asynchronous file operations, so its methods must be awaited.\n- `BrowserStorage` and `JsonStorage` are separate storage implementations; choose the one that matches your runtime.\n- Nested paths use dot notation, for example `user.profile.name` and `users.0.name`.\n- JSON file writes are formatted with two-space indentation.\n\n## Contributing\n\nIssues, feature requests, bug reports, and pull requests are welcome.\n\nRepository:\n\nhttps://github.com/abdu-selam/smart-storage\n\nIssues:\n\nhttps://github.com/abdu-selam/smart-storage/issues\n\n## License\n\nMIT © Abduselam Awel\n","readmeFilename":"README.md"}