flyweightjs

library5.0.34jsnpmunverified

Flyweight is an ORM for SQLite and Turso targeting Node.js ≥22.13.1. Version 5.0.34 provides a comprehensive API including insert, update, upsert, get, many, first, query, remove, and batch operations. It automatically generates TypeScript types from your SQL schema (via npm run types/watch) and supports advanced features like JSON field typing and typed raw SQL queries. Unlike traditional ORMs, Flyweight uses a file-based migration system and integrates deeply with Turso for edge databases. The library is ESM-only and ships with TypeScript definitions.

database

npm install flyweightjs

package ↗

INSTALL

IMPORT

SIG · FLYWEIGHTJS

flyweightjs

databasejavascriptv5.0.34

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.

✓ import { db } from './database/db.js'

✗ import { db } from 'flyweightjs'

The db instance is generated by the `create-flyweight` CLI tool and placed in a local `database` folder. It is not exported from the package itself.

createFlyweight

✓ import { createFlyweight } from 'flyweightjs'

✗ const createFlyweight = require('flyweightjs')

The package is ESM-only since v5. CommonJS require will fail.

Demonstrates basic CRUD operations: insert, many (with filter), update, and upsert using the auto-generated db instance.

// 1. Initialize a project // npx create-flyweight database // 2. Use the generated db instance import { db } from './database/db.js'; // Insert a record const id = await db.users.insert({ name: 'Alice', email: 'alice@example.com' }); console.log('Inserted user with id:', id); // Query records const users = await db.users.many({ name: 'Alice' }); console.log('Users:', users); // Update a record const affected = await db.users.update({ where: { id }, set: { email: 'alice_new@example.com' } }); console.log('Updated rows:', affected); // Upsert (insert or update) const upsertedId = await db.users.upsert({ values: { id, name: 'Alice', email: 'alice@example.com' }, target: 'id', set: { email: 'alice_upsert@example.com' } }); console.log('Upserted id:', upsertedId);

Debug

Known issues

breakingESM-only since v5: require() will throw ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import(). Node.js >=22.13.1 required.

affects: >=5.0.0

gotchaThe db object is not exported from the flyweightjs package; you must run npx create-flyweight to generate it locally.

fix

Run 'npx create-flyweight database' in your project root.

affects: >=5.0.0

deprecatedinsertMany does not return a value. Use insert in a loop if you need primary keys.

fix

Prefer insert inside a transaction for batch inserts with return values.

affects: >=5.0.0

gotchaRaw SQL typed queries require starting from a .sql file in the table folder; inline raw query() may not provide TypeScript types.

fix

Place custom SQL in a .sql file under the table's folder and regenerate types.

affects: >=5.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using require() to import an ESM-only package.

fix

Change to import statement: import { createFlyweight } from 'flyweightjs';

Cannot find module './database/db.js'

The database folder was not generated by create-flyweight.

fix

Run npx create-flyweight database in your project root.

Upgrade

Version history

5.0.34latest on npm

Audit

Dependencies

better-sqlite3optionalUsed for SQLite database driver when not using Turso

@libsql/clientoptionalUsed for Turso database driver

Agent activity

2 hits · last 30 days

node

Resources

packageflyweightjs ↗