vasta-orm

library0.0.14jsnpmunverified

Vasta is a type-safe Active Record ORM for TypeScript, built on top of Kysely (v0.29+). It provides a Laravel Eloquent-inspired interface for defining models with relationships, attributes, and lifecycle hooks, while leveraging Kysely's SQL query builder for raw performance. Version 0.0.14 is the latest stable, with an active development cadence (weekly releases). Key differentiators: full TypeScript type safety via Kysely's types, active record pattern with instance-based saves, and support for eloquent-style relationships (hasOne, hasMany, belongsTo) without sacrificing the ability to drop down to raw SQL via Kysely.

database

npm install vasta-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VASTA-ORM

vasta-orm

databasejavascriptv0.0.14

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.

Model

✓ import { Model } from 'vasta-orm'

✗ import Model from 'vasta-orm'

Model is a named export; default export is not provided.

Pet

✓ import { Pet } from './models/Pet'

✗ const Pet = require('./models/Pet')

Vasta models are typically defined as classes extending Model and exported as named exports. Use ESM imports for type safety.

HasManyRelation

✓ import { HasManyRelation } from 'vasta-orm/relations'

✗ import { HasManyRelation } from 'vasta-orm'

Relation classes are exported from a subpath 'vasta-orm/relations' to avoid polluting the main module.

Shows defining a Pet model extending Model, setting up Kysely with PostgreSQL, querying a record, modifying it, saving, and accessing a relationship.

import { Model } from 'vasta-orm'; import { Kysely, PostgresDialect } from 'kysely'; import { Pool } from 'pg'; // Define your database type (optional but recommended) interface Database { pets: PetsTable; owners: OwnersTable; } interface PetsTable { id: number; name: string; owner_id: number; species: string; } interface OwnersTable { id: number; name: string; } // Create Kysely instance const db = new Kysely<Database>({ dialect: new PostgresDialect({ pool: new Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://localhost/mydb', }), }), }); // Define your model export class Pet extends Model<Pet, PetsTable> { static tableName = 'pets'; static primaryKey = 'id'; static timestamps = true; // define relationships owner() { return this.belongsTo<Owner>('owners', 'owner_id'); } } // Use the model async function main() { const pet = await Pet.findOrFail(1); pet.name = 'Fluffy'; await pet.save(); const owner = await pet.owner().fetch(); console.log(owner.name); } main().catch(console.error);

Debug

Known issues

gotchaVasta requires Kysely v0.29.0 or higher; using an older Kysely version will cause runtime errors.

fix

Install kysely@^0.29.0 via npm install kysely@^0.29.0

affects: >=0.0.0

deprecatedThe 'relation' method on Model is deprecated in favor of specific relationship methods (hasMany, belongsTo, etc.)

fix

Use explicit relationship methods like this.hasMany(RelatedModel, foreignKey) instead of this.relation('hasMany', ...).

affects: <0.1.0

breakingIn v0.0.10, the Model constructor signature changed: you must now pass the database instance as the first argument.

fix

Update Model instantiation: new Model(db, attributes) or use Model.findOrFail(db, id).

affects: >=0.0.10

gotchaWhen using TypeScript strict mode, you must provide generic type arguments to Model (e.g., Model<ModelClass, TableInterface>) or you'll get implicit any errors.

fix

Define an interface for your table and pass it as the second generic parameter.

affects: >=0.0.0

deprecatedThe 'timestamps' property is currently boolean; in future versions it may become an object configuration.

fix

For now, set static timestamps = true. Monitor changelog for changes.

affects: >=0.0.0

gotchaVasta does not automatically handle transactions; each save() call runs in its own implicit transaction if Kysely's dialect supports it.

fix

For atomic operations, wrap multiple saves in a Kysely transaction and pass the transaction object to Vasta methods if supported (check docs).

affects: >=0.0.0

Errors

Common errors & fixes

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

Importing Model incorrectly (e.g., using default import) causing Model to be undefined.

fix

Use named import: import { Model } from 'vasta-orm'

Error: Kysely instance is required. Use Model.setDb(kyselyInstance) or pass it when constructing models.

Trying to use a model without setting up Kysely database instance.

fix

Call Model.setDb(kyselyInstance) before any model operations, or pass db to constructor.

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

Missing package installation or incorrect import path.

fix

Run npm install vasta-orm and ensure tsconfig.json has 'moduleResolution': 'node' or 'bundler'.

Upgrade

Version history

0.0.14latest on npm

Audit

Dependencies

kyselyrequiredPeer dependency: Vasta uses Kysely as its underlying query builder and database interface

Agent activity

19 hits · last 30 days

node