swan-orm

library1.0.9jsnpmunverified

Swan ORM is a lightweight ORM for Node.js and PostgreSQL, designed for TypeScript-first development. The current stable version is 1.0.9. It provides a simple, intuitive API for defining models, querying with chainable methods, and managing database migrations. Key differentiators include zero external runtime dependencies, automatic type inference from models, and a focus on PostgreSQL-specific features. Compared to larger ORMs like Sequelize or TypeORM, Swan ORM offers minimal overhead and a simpler learning curve, suitable for projects that need quick setup without heavy abstraction.

database

npm install swan-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SWAN-ORM

swan-orm

databasejavascriptv1.0.9

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.

Swan

✓ import { Swan } from 'swan-orm'

✗ const Swan = require('swan-orm');

Swan ORM is ESM-only since v1.0.0. Use named import for the main class.

Model

✓ import { Model } from 'swan-orm'

Base class for defining database models. TypeScript decorators are optional.

Column

✓ import { Column } from 'swan-orm'

Decorator for defining column properties in models. Requires TypeScript.

Demonstrates connecting to PostgreSQL, defining a User model with Swan ORM decorators, syncing the schema, and performing basic CRUD operations.

import { Swan, Model, Column } from 'swan-orm'; import { Client } from 'pg'; const client = new Client({ connectionString: process.env.DATABASE_URL ?? 'postgresql://localhost:5432/mydb' }); const swan = new Swan({ client }); class User extends Model { @Column({ type: 'integer', primaryKey: true, autoIncrement: true }) id: number; @Column({ type: 'varchar', length: 255 }) name: string; @Column({ type: 'varchar', length: 255, unique: true }) email: string; } async function main() { await client.connect(); await swan.sync(); // Creates tables const user = await User.create({ name: 'Alice', email: 'alice@example.com' }); console.log('Created user:', user); const users = await User.find({ where: { name: 'Alice' } }); console.log('Found users:', users); await client.end(); } main().catch(console.error);

Debug

Known issues

breakingMigration from v0.x to v1.0: The API has changed from function-based to class-based models. Swan() constructor now requires a client instance.

fix

Rewrite models as classes extending Model and instantiate Swan with a pg Client.

affects: <1.0.0

gotchaCustom column types must be registered manually before using them in decorators.

fix

Use swan.registerType('mytype', ...) prior to model definition.

affects: >=1.0.0

deprecatedThe 'autoIncrement' column option is deprecated in favor of 'serial' type.

fix

Use @Column({ type: 'serial', primaryKey: true }) instead.

affects: >=1.0.5

Errors

Common errors & fixes

TypeError: Swan is not a constructor

Using CommonJS require instead of ESM import or forgetting to import { Swan }.

fix

Use 'import { Swan } from 'swan-orm'' and ensure the project uses ES modules (type: 'module' in package.json).

Error: No client provided. Use new Swan({ client })

Swan instance created without a client or client is undefined.

fix

Instantiate Swan with a pg.Client or pg.Pool instance.

QueryFailedError: relation "users" does not exist

Tables not created before querying. Need to call swan.sync() or run migrations.

fix

Add await swan.sync() after instantiating Swan and before performing queries.

Upgrade

Version history

1.0.9latest on npm

Audit

Dependencies

pgrequiredPostgreSQL driver for Node.js

Agent activity

12 hits · last 30 days

node