farstorm

library1.1.2jsnpmunverified

Farstorm (v1.1.2) is a TypeScript-first ORM for PostgreSQL leveraging structural typing and providing first-access retrieval patterns for efficient querying. It relies on @electric-sql/pglite for PostgreSQL connectivity. Released on npm, it is designed for Node.js 20+ environments with a focus on type safety and developer experience. Differentiators include its unique 'first access' retrieval strategy that minimizes roundtrips and its full TypeScript support with strong type inference for database schemas and queries.

database

npm install farstorm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FARSTORM

farstorm

databasejavascriptv1.1.2

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.

Farstorm

✓ import { Farstorm } from 'farstorm'

✗ const Farstorm = require('farstorm')

ESM-only package; CommonJS require is not supported. Use import statements.

Model

✓ import { Model } from 'farstorm'

✗ import { Model } from 'farstorm/model'

Model is exported from the main entry point, not a submodule.

QueryResult

✓ import { QueryResult } from 'farstorm'

Type-only import is optional if not used at runtime.

Initializes Farstorm with a PGlite client and defines a simple model to query the first matching user by email.

import { Farstorm, Model } from 'farstorm'; import { PGlite } from '@electric-sql/pglite'; const client = new PGlite(process.env.PG_URL ?? 'postgresql://localhost:5432/mydb'); const farstorm = new Farstorm({ client }); class User extends Model { static table = 'users'; static fields = { id: { type: 'integer', primary: true }, name: { type: 'string', required: true }, email: { type: 'string', unique: true }, }; } async function main() { const users = await User.query().where({ email: 'example@test.com' }).first(); console.log(users); } main();

Debug

Known issues

breakingFarstorm requires Node.js 20 or later. Older versions are not supported and may cause runtime errors.

fix

Upgrade Node.js to version 20 or later.

affects: >=1.0

gotchaThe package is ESM-only. Attempting to import using CommonJS require() will throw an error.

fix

Use 'import' statements instead of require(). Ensure your project is configured for ESM (e.g., 'type': 'module' in package.json).

affects: >=1.0

deprecatedThe 'Farstorm' constructor previously accepted a configuration object with a 'pool' property (from pg). In v1.1, 'client' is required and must be a PGlite instance.

fix

Replace 'pool' with 'client' and use PGlite: new Farstorm({ client: new PGlite(...) }).

affects: >=1.1

gotchaModel fields with 'unique: true' are not automatically indexed; you must create indexes separately in PostgreSQL.

fix

Manually add UNIQUE constraints or indexes to your database tables.

affects: >=1.0

Errors

Common errors & fixes

Cannot find module '@electric-sql/pglite'

Missing peer dependency @electric-sql/pglite

fix

Install the peer dependency: npm install @electric-sql/pglite

TypeError: Farstorm is not a constructor

Using default import instead of named import or incorrect require usage

fix

Use named import: import { Farstorm } from 'farstorm'

Error: Model must have a static 'table' property

Model class definition missing 'table' static field

fix

Add 'static table = 'your_table_name';' to your model class.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

@electric-sql/pgliterequiredProvides PostgreSQL client and connection management for Farstorm

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/Atrocit/Farstorm ↗

packagefarstorm ↗

homepagehttps://github.com/Atrocit/Farstorm#readme ↗