@hedystia/db 2.0.9 → 2.0.11

package/dist/types.d.mts

@@ -5,7 +5,7 @@ type ColumnDataType = "integer" | "varchar" | "text" | "boolean" | "json" | "arr
  * Database type identifier — can be a simple string shorthand or an object
  * specifying both the database name and the driver provider to use
  */
-type DatabaseType = "mysql" | "mariadb" | "sqlite" | "file" | {
+type DatabaseType = "mysql" | "mariadb" | "sqlite" | "file" | "s3" | {
   name: "mysql";
   provider: "mysql" | "mysql2";
 } | {
@@ -17,6 +17,9 @@ type DatabaseType = "mysql" | "mariadb" | "sqlite" | "file" | {
 } | {
   name: "file";
   provider: string;
+} | {
+  name: "s3";
+  provider: string;
 };
 /** Metadata describing a single database column */
 interface ColumnMetadata {
@@ -217,8 +220,23 @@ interface FileConnectionConfig {
   /** Directory where data files are stored */
   directory: string;
 }
+/** Connection configuration for S3-based storage */
+interface S3ConnectionConfig {
+  /** S3 bucket name */
+  bucket: string;
+  /** S3 endpoint URL */
+  endpoint?: string;
+  /** AWS region */
+  region?: string;
+  /** S3 access key ID */
+  accessKeyId?: string;
+  /** S3 secret access key */
+  secretAccessKey?: string;
+  /** Key prefix for stored objects */
+  prefix?: string;
+}
 /** Union of all supported connection configurations */
-type ConnectionConfig = MySQLConnectionConfig | SQLiteConnectionConfig | FileConnectionConfig;
+type ConnectionConfig = MySQLConnectionConfig | SQLiteConnectionConfig | FileConnectionConfig | S3ConnectionConfig;
 /**
  * Global cache configuration for the database instance.
  * Controls query result caching and entity caching behavior.
@@ -361,16 +379,18 @@ type SchemaByName<S extends readonly AnyTableDef[], N extends string> = Extract<
 type StripIdSuffix<S extends string> = S extends `${infer Base}Id` ? Base : S extends `${infer Base}_id` ? Base : S;
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
 type Simplify<T> = { [K in keyof T]: T[K] } & {};
-type ForwardRelationEntries<S extends readonly AnyTableDef[], T extends AnyTableDef> = TableRefs<T> extends infer R ? R extends DeferredRefMeta<infer Col, infer ToTable, any, infer Name> ? { [K in Name extends string ? Name : StripIdSuffix<Col>]: {
-  table: SchemaByName<S, ToTable>;
+type IsArray<T> = T extends readonly any[] ? true : false;
+type SchemaKey<S, T extends AnyTableDef> = IsArray<S> extends true ? TableName<T> : { [K in keyof S]: S[K] extends T ? K : never }[keyof S];
+type ForwardRelationEntries<S, T extends AnyTableDef> = TableRefs<T> extends infer R ? R extends DeferredRefMeta<infer Col, infer ToTable, any, infer Name> ? { [K in Name extends string ? Name : StripIdSuffix<Col>]: {
+  table: SchemaByName<InferSchemas<S>, ToTable>;
   many: false;
 } } : never : never;
-type ReverseRelationEntry<U extends AnyTableDef, TargetName extends string> = TableRefs<U> extends infer R ? R extends DeferredRefMeta<any, TargetName, any, any> ? { [K in TableName<U>]: {
+type ReverseRelationEntry<S, U extends AnyTableDef, TargetName extends string> = TableRefs<U> extends infer R ? R extends DeferredRefMeta<any, TargetName, any, any> ? { [K in SchemaKey<S, U> & string]: {
   table: U;
   many: true;
 } } : never : never;
-type ReverseRelationEntries<S extends readonly AnyTableDef[], T extends AnyTableDef> = ReverseRelationEntry<S[number], TableName<T>>;
-type RelationsFor<S extends readonly AnyTableDef[], T extends AnyTableDef> = Simplify<UnionToIntersection<ForwardRelationEntries<S, T> | ReverseRelationEntries<S, T>>>;
+type ReverseRelationEntries<S, T extends AnyTableDef> = ReverseRelationEntry<S, InferSchemas<S>[number], TableName<T>>;
+type RelationsFor<S, T extends AnyTableDef> = Simplify<UnionToIntersection<ForwardRelationEntries<S, T> | ReverseRelationEntries<S, T>>>;
 type InferSchemas<T> = T extends readonly AnyTableDef[] ? T : T extends Record<string, any> ? Array<{ [K in keyof T]: T[K] extends AnyTableDef ? T[K] : never }[keyof T]> : readonly AnyTableDef[];
 type DepthPrev = [never, 0, 1, 2, 3];
 type ExtractRelationRow<Rel> = Rel extends {
@@ -379,17 +399,17 @@ type ExtractRelationRow<Rel> = Rel extends {
 type ExtractRelationMany<Rel> = Rel extends {
   many: true;
 } ? true : false;
-type RelationQueryMap<S extends readonly AnyTableDef[], T extends AnyTableDef, D extends number = 3> = [D] extends [never] ? {} : { [K in keyof RelationsFor<S, T>]: {
+type RelationQueryMap<S, T extends AnyTableDef, D extends number = 3> = [D] extends [never] ? {} : { [K in keyof RelationsFor<S, T>]: {
   row: ExtractRelationRow<RelationsFor<S, T>[K]>;
   many: ExtractRelationMany<RelationsFor<S, T>[K]>;
   relations: RelationsFor<S, T>[K] extends {
     table: infer R extends AnyTableDef;
   } ? RelationQueryMap<S, R, DepthPrev[D]> : {};
 } };
-type ResolveWith<S extends readonly AnyTableDef[], T extends AnyTableDef, W> = [W] extends [undefined] ? {} : W extends Record<string, any> ? { [K in keyof W & keyof RelationsFor<S, T>]: ExtractRelationMany<RelationsFor<S, T>[K]> extends true ? ExtractRelationRow<RelationsFor<S, T>[K]>[] : ExtractRelationRow<RelationsFor<S, T>[K]> | null } : {};
-type ResolveResult<S extends readonly AnyTableDef[], T extends AnyTableDef, O> = InferRow<T> & ResolveWith<S, T, O extends {
+type ResolveWith<S, T extends AnyTableDef, W> = [W] extends [undefined] ? {} : W extends Record<string, any> ? { [K in keyof W & keyof RelationsFor<S, T>]: ExtractRelationMany<RelationsFor<S, T>[K]> extends true ? ExtractRelationRow<RelationsFor<S, T>[K]>[] : ExtractRelationRow<RelationsFor<S, T>[K]> | null } : {};
+type ResolveResult<S, T extends AnyTableDef, O> = InferRow<T> & ResolveWith<S, T, O extends {
   with: infer W;
 } ? W : undefined>;
 //#endregion
-export { AnyTableDef, CacheConfig, ColumnDataType, ColumnMetadata, ConnectionConfig, DatabaseConfig, DatabaseDriver, DatabaseType, DeferredRefMeta, DeleteOptions, FileConnectionConfig, InferInsert, InferRow, InferSchemas, InferUpdate, MigrationContext, MigrationDefinition, MySQLConnectionConfig, QueryOptions, ReferenceAction, RelationQueryMap, RelationsFor, Repository, ResolveResult, SQLiteConnectionConfig, TableCacheConfig, TableDefinition, TableMetadata, UpdateOptions, WhereClause, WhereCondition };
+export { AnyTableDef, CacheConfig, ColumnDataType, ColumnMetadata, ConnectionConfig, DatabaseConfig, DatabaseDriver, DatabaseType, DeferredRefMeta, DeleteOptions, FileConnectionConfig, InferInsert, InferRow, InferUpdate, MigrationContext, MigrationDefinition, MySQLConnectionConfig, QueryOptions, ReferenceAction, RelationQueryMap, RelationsFor, Repository, ResolveResult, S3ConnectionConfig, SQLiteConnectionConfig, TableCacheConfig, TableDefinition, TableMetadata, UpdateOptions, WhereClause, WhereCondition };
 //# sourceMappingURL=types.d.mts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hedystia/db",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "Next-gen TypeScript ORM for building type-safe database layers at lightspeed",
   "homepage": "https://docs.hedystia.com",
   "devDependencies": {
@@ -12,7 +12,8 @@
     "mysql": ">= 2.0.0",
     "better-sqlite3": ">= 12.0.0",
     "sqlite3": ">= 6.0.0",
-    "sql.js": ">= 1.0.0"
+    "sql.js": ">= 1.0.0",
+    "@aws-sdk/client-s3": ">= 3.0.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -32,6 +33,9 @@
     },
     "sql.js": {
       "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
     }
   },
   "bin": {

package/readme.md

@@ -1,6 +1,15 @@
 # @hedystia/db
 
-Next-gen TypeScript ORM for building type-safe database layers at lightspeed.
+Next-gen TypeScript ORM for building type-safe database layers at lightspeed. Focused on performance, developer experience, and multi-driver flexibility.
+
+## Features
+
+- 💎 **Type-safe by Design**: First-class TypeScript inference for all your queries.
+- 🚀 **Multi-Driver Support**: Native drivers for SQLite, MySQL, and experimental support for File/S3 storage.
+- ⚡ **Auto-Mapping**: Decouple database table/column names from your TypeScript models.
+- 🔗 **Smart Relations**: Define relationships once and load them eagerly with intuitive `with` queries.
+- 📦 **Zero-Config Migrations**: CLI for generating atomic migrations and schema synchronization.
+- 🧠 **Built-in Caching**: Adaptive TTL caching with automatic invalidation on writes.
 
 ## Installation
 
@@ -8,111 +17,94 @@ Next-gen TypeScript ORM for building type-safe database layers at lightspeed.
 bun add @hedystia/db
 ```
 
-### Database Drivers
-
-Install the driver for your database. The ORM will automatically detect and use the most appropriate library available.
-
-#### SQLite Driver
-Supports multiple libraries in the following priority:
-1. `better-sqlite3`
-2. `sqlite3`
-3. `sql.js`
-4. `bun:sqlite`
-
-```bash
-# You can install any of these
-
-bun add better-sqlite3
-bun add sqlite3
-bun add sql.js
-
-# Or use bun:sqlite if you are using Bun
-```
+### Choose your Driver
 
-#### MySQL & MariaDB Driver
-Supports both `mysql2` and `mysql` libraries.
-- **Naming**: Use `database: "mysql"` or `database: "mariadb"`.
-- **MariaDB**: Fully supported through the same drivers.
+| Database | Driver Package | Command |
+| --- | --- | --- |
+| **SQLite** | `better-sqlite3`, `sqlite3`, `sql.js` | `bun add better-sqlite3` |
+| **MySQL** | `mysql2` or `mysql` | `bun add mysql2` |
+| **S3** | `@aws-sdk/client-s3` | `bun add @aws-sdk/client-s3` |
+| **File** | *Built-in* | *No installation needed* |
+| **Edge** | `bun:sqlite` (Bun only) | *No installation needed* |
 
-```bash
-bun add mysql2 # Preferred
-# or
-bun add mysql
-```
 
-# File-based (no extra install needed)
+---
 
 ## Quick Start
 
-### Define your schema
+### Define your Schema
+
+Define your tables using the `table` function. This allows you to map database properties to your preferred TypeScript keys.
 
-```ts
+```typescript
 import { table, integer, varchar, text } from "@hedystia/db";
 
-export const users = table("users", {
+export const users = table("example_users", {
   id: integer().primaryKey().autoIncrement(),
-  name: varchar(255).notNull(),
+  fullName: varchar(255).name("full_name").notNull(),
   email: varchar(255).unique(),
-  age: integer().default(0),
 });
 
-export const posts = table("posts", {
+export const posts = table("example_posts", {
   id: integer().primaryKey().autoIncrement(),
-  userId: integer().references(() => users.id, { onDelete: "CASCADE" }),
+  authorId: integer().name("author_id").references(() => users.id),
   title: varchar(255).notNull(),
-  content: text(),
+  body: text(),
 });
 ```
 
-> **Note:** The `d.xxx()` prefix style (e.g., `d.integer()`) is still supported for backward compatibility.
+### Initialize the Database
 
-### Create the database
+Use the **Object Schema** method (recommended) to automatically alias your tables on the database instance.
 
-```ts
+```typescript
 import { database } from "@hedystia/db";
-import { users, posts } from "./schemas";
+import { users, posts } from "./schema";
 
 const db = database({
-  schemas: [users, posts],
+  schemas: { users, posts }, // Alias tables as db.users and db.posts
   database: "sqlite",
-  connection: { filename: "./data.db" },
-  syncSchemas: true,
-  cache: true,
+  connection: { filename: "./main.db" },
+  syncSchemas: true, // Auto-create tables during development
 });
 
 await db.initialize();
 ```
 
-### Query your data
-
-```ts
-// Insert
-const user = await db.users.insert({ name: "Alice", email: "alice@example.com" });
-
-// Find
-const allUsers = await db.users.find();
-const alice = await db.users.findFirst({ where: { name: "Alice" } });
+### Query your Data
 
-// Update
-await db.users.update({ where: { id: 1 }, data: { age: 26 } });
+```typescript
+// Insert a record
+const newUser = await db.users.insert({ 
+  fullName: "Alice Vance", 
+  email: "alice@hedystia.com" 
+});
 
-// Delete
-await db.users.delete({ where: { id: 1 } });
+// Find with eager relations
+const userWithPosts = await db.users.findFirst({
+  where: { fullName: "Alice Vance" },
+  with: { posts: true }
+});
 
-// Relations
-const usersWithPosts = await db.users.find({ with: { posts: true } });
+// Powerful filtering
+const recentPosts = await db.posts.find({
+  where: { authorId: 1, title: { like: "%Hedystia%" } },
+  orderBy: { id: "desc" },
+  take: 5
+});
 ```
 
-## Features
+## Advanced Usage
+
+Explore our detailed documentation for advanced topics:
 
-- **One schema, multiple databases** — MySQL, SQLite, and File drivers
-- **Type-safe queries** — Full TypeScript inference for all operations
-- **Smart caching** — Adaptive TTL cache with automatic invalidation
-- **Migrations** — CLI and programmatic migration support
-- **Schema sync** — Automatic table creation and column diffing
-- **Relations** — Foreign key references with eager loading
+- [**Schema Definition**](https://docs.hedystia.com/db/schema) - Custom types, constraints, and aliases.
+- [**Relations**](https://docs.hedystia.com/db/relations) - One-to-many, many-to-one, and cascade behaviors.
+- [**Queries**](https://docs.hedystia.com/db/queries) - Full API reference for find, insert, update, and delete.
+- [**CLI & Migrations**](https://docs.hedystia.com/db/cli) - Managing schema changes safely.
+- [**Drivers**](https://docs.hedystia.com/db/drivers/sqlite) - Specific configuration for MySQL, SQLite, S3, and more.
 
-## Links
+## Community & Links
 
 - [Documentation](https://docs.hedystia.com/db/start)
 - [GitHub](https://github.com/Hedystia/Hedystia)