Home

Awesome

jstorm

version downloads Node.js CI Chrome E2E Test codecov Maintainability

ORM-like API provider for window.localStorage and chrome.storage, or any other data store.

// For window.localStorage:
import { Model } from "jstorm/browser/local";

// For chrome.storage.sync:
import { Model } from "jstorm/chrome/sync";

// For your custom storage:
import { Model } from "jstorm";
Model._area_ = yourCoolStorageAccessor;
// NOTE: It should implement `chrome.storage.StorageArea` interface.

Getting started

npm install jstorm
# or yarn add, pnpm add, whatever

Example Usage

// In your JS/TS
import { Model } from "jstorm/chrome/local";

// Define your model,
class Player extends Model {
    public name: string;
    public age: number;
    greet(): string {
        return `Hello, my name is ${this.name}!`;
    }
}

// and use it.
(async () => {
    // Save records to chrome.storage.
    const x = await Player.create({ name: "otiai10", age: 17 });
    const y = await Player.create({ name: "hiromu", age: 32 });

    // Retrieve records from chrome.storage.
    console.log(await Player.list()); // [Player, Player] length 2
    console.log(await Player.find(x._id)); // Player {name:"otiai10", age: 17}
})();

Basic APIs

Defining your model class

import { Model } from "jstorm";

class Player extends Model {
    // You can define your own members of your model.
    public name: string;
    public age: number;

    // Optional: If you'd like to minify/mangle your JS,
    // you'd better set the namespace of this mode explicitly.
    static override _namespace_ = "Player";
}

That's all to get started. Let's enjoy.

new

To construct new model object:

const john = Player.new({name: "John", age: 17});
console.log(john._id); // null

NOTE: new does NOT save constructed object yet. Please use save to make it persistent.

save

To save unsaved obejct to the storage:

await john.save();
console.log(john._id); // 1672363730924

Now _id is generated because it's saved on the storage.

create

Just a short-hand of new and save:

const paul = await Player.create({name: "Paul", age: 16});
console.log(paul._id); // 1672968746499

list

To list up all entities saved on this namespace:

const all = await Player.list();
console.log(all.length);  // 2
console.log(all[0].name); // John

dict

To get all entities saved on this namespace as a dict:

const dict = await Player.dict();
console.log(Object.entries(dict));
// [[1672363730924, Player], [1672968746499, Player]]

find

To find specific object saved on this namespace:

const found = await Player.find("1672968746499");
console.log(found?.name); // Paul

filter

To find objects which should match a specific criteria:

const criteria = (p: Player): bool => (Player.age > 16);
const filtered = await Player.filter(criteria);
console.log(filtered.length); // 1

update

await john.update({ age: 21 });
const found = await Player.find(john._id);
console.log(found.age); // 21

delete

To delete a specific object:

await john.delete();
const found = await Player.find(john._id);
console.log(found); // null

drop

To delete all objects saved on this namespace:

await Player.drop();
const list = await Player.list();
console.log(list.length); // 0

Advanced properties

schema

Use static schema to define relation between your Models.

import { Model, Types } from "jstorm/chrome/local";

class Team extends Model {
    public name: string;
    public captain: Player;
    public admins: Player[];

    static override schema = {
        name: Types.string.isRequired,
        captain: Types.model(Player, { eager: true }).isRequired,
        admins: Types.arrayOf(Types.model(Player)),
    }
}

NOTE: When {eager: true} is provided in schema definition of Types.model, this model always look up your storage to populate specified fields, eagerly. Otherwise, this model just instantiate this field from what's saved under this model.

Issues