websql-orm

library2.6.1jsnpmunverified

websql-orm is an ORM framework for TypeScript, Angular, Cordova, and browser environments that wraps WebSQL and SQLite databases. Version 2.6.1 is the latest stable release, with regular updates. It uses decorators to define tables, columns, and foreign key references, generating SQL schemas automatically. Key differentiators: supports both browser WebSQL and Cordova sqlite-storage via a config flag, provides a Table base class for entity models, and includes methods like insert, update, delete, and raw SQL queries. It is designed for Angular developers needing offline-first mobile or web apps with minimal SQL boilerplate.

database

npm install websql-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSQL-ORM

websql-orm

databasejavascriptv2.6.1

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.

sqlite

✓ import { sqlite } from 'websql-orm'

✗ import sqlite from 'websql-orm'

sqlite is a named export, not default. ESM only; no CJS support.

database

✓ import { database } from 'websql-orm'

Used as a class decorator; TypeScript requires experimentalDecorators: true in tsconfig.json.

Table

✓ import { Table } from 'websql-orm'

Entity classes must extend Table.

EnvConfig

✓ import { EnvConfig } from 'websql-orm'

Used to enable Cordova mode or debug logging.

ColumnType

✓ import { ColumnType } from 'websql-orm'

Enum for column types; combine with | for primary key (e.g., ColumnType.STRING | ColumnType.PRIMARY).

Shows defining a table with decorators, inserting a record, and querying with parameters.

import { database, column, ColumnType, Table, sqlite } from 'websql-orm'; @database('mydb', 'users') export class User extends Table { @column(ColumnType.STRING | ColumnType.PRIMARY) id: string; @column(ColumnType.STRING) name: string; @column(ColumnType.NUMBER) age: number; } async function main() { const user = new User(); user.id = '1'; user.name = 'Alice'; user.age = 30; await sqlite.insert(user); const users = await sqlite.fromSql(new User(), 'SELECT * FROM users WHERE age > ?', [20]); console.log(users); } main();

Debug

Known issues

breakingVersions prior to 2.1.0 are debug versions and cannot be used in production.

fix

Install version 2.1.0 or later: npm install websql-orm@latest

affects: <2.1.0

gotchaWhen using Cordova, you must set EnvConfig.useCordovaSqliteStorage = true before any database operations, otherwise it defaults to browser WebSQL which is not supported in iOS/Android.

fix

import { EnvConfig } from 'websql-orm'; EnvConfig.useCordovaSqliteStorage = true;

affects: >=2.0.0

gotchaTypeScript's experimentalDecorators must be enabled in tsconfig.json. Without it, decorators will not work and may cause compile errors.

fix

Add "experimentalDecorators": true to tsconfig.json compilerOptions.

affects: >=2.0.0

gotchaThe table entity class must inherit from Table. If omitted, methods like insert/update may fail silently or throw errors.

fix

Ensure each entity class extends Table.

affects: >=2.0.0

deprecatedThe @reference decorator for foreign keys is deprecated in later versions and may be removed. Consider manually managing relationships.

fix

Use raw SQL for foreign key constraints instead.

affects: >=2.5.0

Errors

Common errors & fixes

TypeError: Class extends value undefined is not a constructor or null

Table class is not exported correctly or not imported as a named export.

fix

Use: import { Table } from 'websql-orm';

Cannot find module 'websql-orm' or its corresponding type declarations.

Missing TypeScript definitions or package not installed.

fix

Run: npm install websql-orm@latest

Experimental support for decorators is a feature that is subject to change in a future release. Set 'experimentalDecorators' to true in your tsconfig.json to remove this warning.

Decorators used without experimentalDecorators flag.

fix

Add "experimentalDecorators": true to tsconfig.json compilerOptions.

sqlite.fromSql is not a function

sqlite is imported incorrectly (default import instead of named).

fix

Use: import { sqlite } from 'websql-orm';

Upgrade

Version history

2.6.1latest on npm

Audit

Dependencies

cordova-sqlite-storageoptionalRequired for Cordova projects to use native SQLite; must be installed as a Cordova plugin and enabled via EnvConfig.useCordovaSqliteStorage.

Agent activity

31 hits · last 30 days

node