https://github.com/idleberg/node-local-storage
A NodeJS ponyfill for the Storage API, utilizing SQLite
https://github.com/idleberg/node-local-storage
local-storage local-storage-api nodejs ponyfill storage-api
Last synced: about 1 month ago
JSON representation
A NodeJS ponyfill for the Storage API, utilizing SQLite
- Host: GitHub
- URL: https://github.com/idleberg/node-local-storage
- Owner: idleberg
- License: mit
- Created: 2025-04-13T10:35:52.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-17T19:26:17.000Z (4 months ago)
- Last Synced: 2026-03-13T13:52:52.508Z (3 months ago)
- Topics: local-storage, local-storage-api, nodejs, ponyfill, storage-api
- Language: TypeScript
- Homepage: https://www.npmjs.org/package/@idleberg/local-storage
- Size: 229 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @idleberg/local-storage
> A NodeJS ponyfill for the Storage API, utilizing SQLite.
[](https://github.com/idleberg/node-local-storage/blob/main/LICENSE)
[](https://www.npmjs.org/package/@idleberg/local-storage)
## Features
- zero dependencies
- fully API compatible to both, `localStorage` and `sessionStorage`
- persists data across sessions
- supports `storage` events
- supports optional quota
> [!NOTE]
>
> This package depends on the experimental `node:sqlite` module included in NodeJS v22.5 and later.
## Installation
`npm install @idleberg/local-storage`
## Usage
### API
#### `createStorage`
Usage: `createStorage(dbFile?: string, options?: StorageFactoryOptions)`
Returns: `{ sessionStorage, localStorage, emitter }`
Creates instances of both, [`sessionStorage`][] and [`localStorage`][], as well as a corresponding EventEmitter.
**Example:**
```typescript
import { createStorage } from "@idleberg/local-storage";
const { sessionStorage, localStorage, emitter } = createStorage("./db.sqlite");
// Listen for storage changes
emitter.on("storage", console.log);
```
##### Options
###### `options.quota`
#### `Storage` (Advanced Usage)
Usage: `new Storage(filePath: string | ':memory:', options: StorageClassOptions)`
This class is used internally by `createStorage. It allows you more control over the EventEmitter, e.g. you could re-use an existing one from your application code.
**Example:**
```typescript
import { Storage } from "@idleberg/local-storage";
import EventEmitter from "node:events";
const myEmitter = new EventEmitter();
const localStorage = new Storage("./db.sqlite", {
emitter: myEmitter,
});
// Listen for storage changes
myEmitter.on("storage", console.log);
```
##### Options
###### `options.emitter`
An instance of `EventEmitter` to use for dispatching storage events.
###### `options.eventName`
The name of the event to dispatch when a storage event occurs. Defaults to `storage`.
###### `options.quota`
Optional storage quota in bytes, useful for emulating browser behaviour.
## Related
- [bun-storage](https://www.npmjs.com/package/bun-storage): a Bun implementation of this package
## License
This work is licensed under [The MIT License](https://opensource.org/licenses/MIT).
[`localStorage`]: https://developer.mozilla.org/docs/Web/API/Window/localStorage
[`sessionStorage`]: https://developer.mozilla.org/docs/Web/API/Window/sessionStorage