LORM (localStorage ORM)

A lightweight mini-ORM for localStorage with TypeScript support and SQL-inspired API.

⚠️ This project is in active development and not yet ready for production use.

Introduction

LORM is a minimalist Object-Relational Mapping (ORM) library for JavaScript/TypeScript that persists data to localStorage. It provides a simple, type-safe API for working with structured data in the browser, inspired by SQL syntax and modern ORM libraries.

Features

• localStorage persistence: Data persists across browser sessions using localStorage
• In-memory operations: Fast operations with cached data in JavaScript Maps
• Type-safe schemas: Built-in schema validation with Zod
• SQL-inspired API: Familiar query methods like select(), insert(), and delete()
• Filtering capabilities: Powerful where clauses with object syntax or functional predicates
• Browser-first: Designed specifically for client-side JavaScript applications
• Performance focused: Optimized for speed with benchmarking included

Performance

LORM is optimized for localStorage-backed operations, with different query strategies for various data sizes:

benchmark

Installation

# Using bun
bun add 0xtotem/lorm

# Using npm
npm install 0xtotem/lorm

# Using yarn
yarn add 0xtotem/lorm

Example Usage

Basic Setup

import { lorm, table, schema, string, number } from "@0xtotem/lorm";

// Define your schema using re-exported Zod types
const userSchema = schema({
  id: string(),
  name: string(),
  age: number(),
});

// Or use Zod directly
import { z } from "zod";
const userSchemaZod = z.object({
  id: z.string(),
  name: z.string(),
  age: z.number(),
});

// Initialize the ORM
const db = lorm("my-app");

// Create a table
const users = table("users", userSchema);

Insert Data

// Insert a new user
db.insert(users).values({
  id: "1",
  name: "John Doe",
  age: 30
});

Query Data

// Get all users
const allUsers = await db.select().from(users);

// Filter users with object syntax
const filteredUsers = await db.select().from(users).where({ name: "John Doe" });

// Filter users with functional predicate
import { eq } from "lorm";
const johnDoe = await db.select().from(users).where(eq("name", "John Doe"));

// Limit results
const limitedUsers = await db.select().from(users).limit(5);

Delete Data

// Delete by condition
await db.delete(users).where(eq("id", "1"));

// Delete with returning deleted items
const deletedUsers = await db.delete(users).where(eq("id", "1")).returning();

Multiple Tables

import { schema, string, boolean } from "lorm";

const todoSchema = schema({
  id: string(),
  title: string(),
  completed: boolean(),
});

const todos = table("todos", todoSchema);

// Insert into todo table
db.insert(todos).values({
  id: "1",
  title: "Buy groceries",
  completed: false
});

// Query both tables
const allUsers = await db.select().from(users);
const allTodos = await db.select().from(todos);

API Reference

Core Functions

• lorm(namespace: string): Creates a new ORM instance
• table(name: string, schema: ZodType<T>): Creates a new table with the specified schema
• schema(obj): Re-exported Zod object schema creator
• string(), number(), boolean(): Re-exported Zod primitive types

ORM Methods

• db.select().from(table): Start a query to select data from a table
• db.insert(table).values(data): Insert data into a table
• db.delete(table).where(condition): Delete data from a table

Query Builder Methods

• .where(condition): Filter results by condition
• .limit(n): Limit results to n items
• .limitFilterSlice(n): Alternative limit implementation for specific use cases

Filter Functions

• eq(field, value): Create a predicate to check field equality

Option Pattern

• some(value): Create a Some instance with a value
• none(): Create a None instance for null values
• Option<T>: Type representing either Some or None

Dependencies

• Zod: Schema definition and validation (re-exported for convenience)
• Neverthrow: Error handling utilities

Development

This project was created using bun init in Bun v1.2.4.

Running Tests

bun test

Running Benchmarks

bun run benchmark.ts

License

MIT