s3-orm

library2.1.2jsnpmunverified

s3-orm (v2.1.2) is an experimental Object-Relational Mapping (ORM) library that uses AWS S3 as its storage backend. It provides decorator-based schema definition (@Entity, @Column) with support for indexes, queries (including comparisons like $gte), and CRUD operations. Useful for low-cost, massively scalable storage for slowly-changing data (e.g., CMS content). Released irregularly as an experiment. Unlike traditional ORMs (e.g., Sequelize, Mongoose), it uses S3's key-value store instead of a relational or document DB. Ships TypeScript types. There is no active development; use with caution in production.

database

npm install s3-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · S3-ORM

s3-orm

databasejavascriptv2.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.

Stash

✓ import { Stash } from 's3-orm'

✗ const Stash = require('s3-orm').Stash

ESM is supported; named import is correct. CommonJS require also works but destructure from default.

Entity

✓ import { Entity } from 's3-orm'

✗ import Entity from 's3-orm'

Entity is a named export, not default.

Column

✓ import { Column } from 's3-orm'

✗ const { Column } = require('s3-orm').default

Column is a named export; CommonJS users must destructure from the module, not .default.

Model

✓ import { Model } from 's3-orm'

✗ import Model from 's3-orm'

Model is a named export, not default.

Defines a Person model with @Entity/@Column, connects to S3, saves a document, and queries using $gte operator.

import { Stash, Entity, Column, Model } from 's3-orm'; const config = { bucket: process.env.AWS_BUCKET ?? 'my-bucket', prefix: 's3orm/', region: process.env.AWS_REGION ?? 'us-east-1', accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '', }; Stash.connect(config); @Entity() class Person extends Model { @Column({ unique: true }) email: string; @Column({ type: 'integer', index: true }) age: number; @Column({ type: 'string', index: true }) fullName: string; } async function main() { const instance = new Person(); instance.email = 'test@example.com'; instance.age = 30; instance.fullName = 'Test User'; await instance.save(); console.log('Saved document to S3'); const results = await Person.find({ where: { age: { $gte: 18 } } }); console.log('Found:', results); } main().catch(console.error);

Debug

Known issues

gotchaS3-ORM is experimental and not recommended for production use. Use a real database for critical data.

fix

Consider using DynamoDB or a SQL database for production workloads.

affects: >=0.0.0

gotchaNo built-in caching or write-batching: each save issues a direct S3 PutObject. High-frequency writes will be slow and costly.

fix

Batch writes manually or use a proper database designed for high throughput.

affects: >=0.0.0

gotchaS3 eventually consistent for overwrite PUTS and DELETEs; reads may return stale data immediately after write. Use --region with consistent reads if needed.

fix

Design your application to tolerate eventual consistency, or use S3 features like read-after-write for new objects.

affects: >=0.0.0

breakingIn v2.0, the Stash.connect() method was introduced and the library changed from a global singleton to requiring explicit connection. Code written for v1.x using global connection will break.

fix

Call Stash.connect() with your config before any model operations.

affects: >=2.0.0 <3.0.0

Errors

Common errors & fixes

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

Model is not imported correctly (CommonJS vs ESM).

fix

Use `import { Model } from 's3-orm'` or `const { Model } = require('s3-orm')` (not .default).

Error: S3 ORM not connected

Stash.connect() was not called before performing operations.

fix

Call `Stash.connect(config)` at app startup before any model operations.

Expected object with 'type' or a string field type

@Column() decorator used without any argument or with an invalid argument.

fix

Provide a valid column definition, e.g., @Column({ type: 'string' }) or @Column() for default string type.

Upgrade

Version history

2.1.2latest on npm

Audit

Dependencies

aws-sdkrequiredRequired to interact with AWS S3 for all storage operations.

Agent activity

12 hits · last 30 days

node