localstorage-orm

Interact with localStorage as we would with an ORM.

Setup

import { Model, Schema } from "localstorage-orm";

// Define the schema
interface Person extends Schema {
    name: string;
    age: number;
}

// Use the schema to define the model
const personModel = new Model<Person>("person");

Creating records

// Create a new instance of the model with build
const person = personModel.build();

person.name = "John Doe";
person.age = 24;

// Persist the instance
person.save();

// Or use the create method to instantly persist a data
const janeDoe = personModel.create({
    name: "Jane Doe",
    age: 24,
});

Fetching records

// Get all records of the model
const allRecords = personModel.list();

// Get a filtered list
const personAged24 = personModel.find({
    age: 24,
});

// Get a single record
const johnDoe = personModel.findOne({
    name: "John Doe",
});

// Get a single record by ID
const johnDoeAgain = personModel.findById(johnDoe.id);
const johnDoeAgainAndAgain = personModel.get(johnDoe.id);

Updating Records

// Updating a single instance
johnDoe.name = "Johnny Doe";
johnDoe.save();

for (let person of personAged24) {
    // What's funnier than 24?
    person.age = 25;
}

// Updating multiple records
personAged24.save();

Deleting records

// Delete a single instance
johnDoe.delete();

// Deletes a list of instance
personAged24.delete();

Reference and populatiom

// Schema declarations
interface Contact extends Schema {
    phone: number;
    email: string;
}
// Allow string for ID and schema for population
interface Employee extends Schema {
    name: string;
    contact: string | Contact;
}
// Array of references
interface Company extends Schema {
    name: string;
    employees: string[] | Employee[];
    contact: string | Contact;
}

const contactModel = new Model<Contact>("contact");

// Declare reference in modelSettings
// modelName - to reference which model to get the data from
// property - field in interface that references that model
const employeeModel = new Model<Employee>("employee", {
    references: [
        {
            modelName: "contact",
            property: "contact",
        },
    ],
});
// If one to many, add isArray property
const companyModel = new Model<Company>("company", {
    references: [
        {
            modelName: "employee",
            property: "employees",
            isArray: true,
        },
        {
            modelName: "contact",
            property: "contact",
        },
    ],
});

const company = ...
// Will convert {string} id into an instance of Contact
company.populate("contact");
// Will convert {string[]} ids into an array of Employees
company.populate("employees");
// Only populate the reference in the first index
company.populate("employees", 0);

Model Settings

const personModelWithSettings = new Model<Person>("person", {
    timestamps: true;
    softDelete: true;
    references: Reference[]
});

• timestamps: boolean - if true, adds an autogenerated createdAt and updatedAt property to the schema
• softDelete: boolean - if true, adds an isDeleted flag to the schema, which is set to true instead of deleting the data
• references: Reference[] - list of references for the model
  • property: string - property of schema that references the target model
  • modelName: string - name of the target model
  • isArray: boolean - indicates that the property is an array

TODO

• findAndUpdate
• findOneAndUpdate
• findAndDelete
• findOneAndDelete
• joins
• population
• indexing
• unique

Brief history (of why I made this)

1. Created a to do app to study Vue and added localStorage as persistence option
2. Thought "Hey! I can reuse this" and uploaded as seperate repo (localStorage-crud) to github
3. Published my first package and thought about this project