uranio

library1.4.1jsnpmunverified

Uranio is a type-safe ODM/ORM for MongoDB, MySQL, and PostgreSQL that generates query methods from TypeScript interfaces extending uranio.atom. Current stable version is 1.4.1. It eliminates the need for a separate Data Access Layer by parsing types at build time and creating a client with collection/table-specific methods. Key differentiators include full TypeScript type safety, support for multiple databases, minimal boilerplate, and peer dependencies only for the database drivers actually used. It supports connection pooling for MySQL and PostgreSQL, custom timezone configuration for MySQL, and works with MongoDB >=7.0, mysql2 >=3.16.0, and pg (PostgreSQL).

database

npm install uranio

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · URANIO

uranio

databasejavascriptv1.4.1

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.

uranio

✓ import uranio from 'uranio'

✗ const { uranio } = require('uranio')

Default import only. CommonJS require must use require('uranio').default or import() ESM.

MongoDBClient

✓ const urn = uranio.MongoDBClient({uri, dbName})

✗ const urn = new uranio.MongoDBClient({uri, dbName})

MongoDBClient is a function, not a constructor. Returns a client object without 'new'.

MySQLClient

✓ const urn = uranio.MySQLClient({uri, usePool: true})

✗ const urn = new uranio.MySQLClient({uri})

MySQLClient is exported as a method on default import. Do not use 'new'.

PostgreSQLClient

✓ import uranio from 'uranio'; const urn = uranio.PostgreSQLClient({uri})

✗ import { PostgreSQLClient } from 'uranio'

PostgreSQLClient is only available via default import object, not as a named export.

atom

✓ interface Product extends uranio.atom

✗ interface Product extends uranio.Atom

The base interface is lowercase 'atom', not 'Atom'. Case-sensitive.

Demonstrates setting up Uranio with MongoDB, defining a Product interface extending uranio.atom, creating a client, and performing basic CRUD operations.

import uranio from 'uranio'; interface Product extends uranio.atom { title: string; description: string; price: number; } const uri = process.env.MONGO_DATABASE_URI || 'mongodb://localhost:27017'; const dbName = process.env.MONGO_DATABASE_NAME || 'test'; const urn = uranio.MongoDBClient({ uri, dbName }); async function run() { // Create a product const newProduct = await urn.products.putAtom({ title: 'Uranio mug', description: 'A radioactive mug for your coding breakfast', price: 4.99 }); console.log('Created product:', newProduct._id); // Get all products const products = await urn.products.getAtoms({}); console.log('Products:', products); // Get a product by ID const product = await urn.products.getAtom({ _id: newProduct._id }); console.log('Found product:', product); } run().catch(console.error);

Debug

Known issues

breakingUranio v1.x requires MongoDB >=7.0. It is not compatible with MongoDB 6.x or earlier.

fix

Upgrade MongoDB to version 7.0 or later (npm install mongodb@7).

affects: >=1.0.0

breakingUranio v1.4.1 requires mysql2 >=3.16.0. Older mysql2 versions may cause unexpected errors.

fix

Update mysql2 to version 3.16.0 or newer (npm install mysql2@latest).

affects: >=1.4.0

gotchaUsing 'new' with MongoDBClient, MySQLClient, or PostgreSQLClient will throw an error because they are not constructors.

fix

Call the function without 'new': const urn = uranio.MongoDBClient({...});

affects: >=1.0.0

gotchaDefault timezone for MySQLClient is UTC ('+00:00'), not the server's local timezone. This can cause date mismatches.

fix

Specify timezone: 'local' to use server timezone, or a specific offset like '+09:00'.

affects: >=1.0.0

deprecatedDynamoDB support is listed in peer dependencies but not documented in README. It may be experimental or deprecated.

fix

Check GitHub issues to confirm DynamoDB support status. It may be removed in future versions.

affects: >=1.4.0

Errors

Common errors & fixes

Error: Cannot find module 'uranio'

Uranio is not installed, or dependencies are missing.

fix

Run 'npm install uranio mongodb' (or appropriate driver) in your project.

Error: Missing database SDK. Make sure you have installed the required peer dependency.

Attempting to create a client without installing the corresponding database driver.

fix

Install the peer dependency: e.g., 'npm install mongodb' for MongoDB, 'npm install mysql2' for MySQL, 'npm install pg' for PostgreSQL.

TypeError: uranio.MongoDBClient is not a constructor

Trying to instantiate with 'new' when MongoDBClient is a plain function.

fix

Remove 'new': const urn = uranio.MongoDBClient({uri, dbName});

Upgrade

Version history

1.4.1latest on npm

Audit

Dependencies

mongodboptionalRequired peer dependency for MongoDB support

mysql2optionalRequired peer dependency for MySQL support

pgoptionalRequired peer dependency for PostgreSQL support

@aws-sdk/client-dynamodboptionalRequired peer dependency for DynamoDB support (not shown in README but listed in metadata)

@aws-sdk/util-dynamodboptionalRequired peer dependency for DynamoDB support (not shown in README but listed in metadata)

Agent activity

35 hits · last 30 days

node