localstorage-orm

library1.1.0jsnpmunverified

localstorage-orm is a lightweight TypeScript ORM for browser localStorage that provides a model-based CRUD interface with schema validation, timestamps, soft deletes, and reference/population support. Current stable version is 1.1.0. It uses a simple builder pattern for records and supports find/findById methods. Key differentiators: direct localStorage persistence with no backend required, TypeScript-first with type safety, and built-in reference population for relational data management within the browser. Release cadence is irregular; latest update was September 2024.

database

npm install localstorage-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOCALSTORAGE-ORM

localstorage-orm

databasejavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Model

✓ import { Model } from 'localstorage-orm'

✗ const { Model } = require('localstorage-orm')

Package is ESM-only; CommonJS require may cause runtime errors. Ensure 'type':'module' in package.json or use .mjs extension.

Schema

✓ import { Schema } from 'localstorage-orm'

✗ import Schema from 'localstorage-orm'

Schema is a named export, not default. Also required as base interface for model schemas.

Model<Person>

✓ import { Model } from 'localstorage-orm'; new Model<Person>('person')

✗ new Model<Person>('person', { timestamps: true }) // correct

Constructor requires a string model name and optional settings object. The generic type parameter should extend Schema.

Create a model, build a record, persist, fetch, update, and delete using Model and Schema.

import { Model, Schema } from 'localstorage-orm'; interface Person extends Schema { name: string; age: number; } const personModel = new Model<Person>('person'); const person = personModel.build(); person.name = 'John Doe'; person.age = 30; person.save(); const all = personModel.list(); console.log(all.length); // 1 const found = personModel.findOne({ name: 'John Doe' }); if (found) { found.age = 31; found.save(); found.delete(); }

Debug

Known issues

gotchaModel constructor expects a generic type that extends Schema. Failing to extend Schema will cause TypeScript compilation errors.

fix

Ensure your interface extends Schema: interface Person extends Schema { ... }

affects: >=1.0.0

breakingLocalStorage is synchronous and blocking. Large datasets may cause UI jank. No async operations supported.

fix

Keep localStorage data small (KB range). Consider IndexedDB for larger datasets.

affects: >=1.0.0

gotchaThe build() method returns a new instance but does NOT automatically save. You must call .save() on it or use create() for immediate persistence.

fix

Use personModel.create(data) instead of build() if you want immediate persistence.

affects: >=1.0.0

deprecatedThe get() method is an alias for findById(). No deprecation notice yet, but prefer findById() for clarity.

fix

Use findById(id) instead of get(id).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: person.save is not a function

You called .save() on a plain object instead of a model instance returned by build() or find() methods. Plain objects do not have the save method.

fix

Use model.build() to create an instance, set properties, then call .save(). For find results, they already have .save().

TS2345: Argument of type '{ name: string; age: number; }' is not assignable to parameter of type 'Schema & Person'

The interface used as generic for Model does not extend Schema.

fix

Define interface Person extends Schema { ... } and use Model<Person>.

Uncaught DOMException: Failed to read the 'localStorage' property from 'Window': Access is denied for this document.

localStorage is not accessible in some browsers (e.g., in private/incognito mode) or when the page is opened via file:// protocol.

fix

Test in a regular browser window with http:// or https://. For file://, use a local server.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

typescriptoptionalTypeScript types are shipped; strongly typed usage requires TypeScript at development time.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/johnreybacal/localstorage-orm ↗

packagelocalstorage-orm ↗

homepagehttps://github.com/johnreybacal/localstorage-orm#readme ↗