uql-orm 0.4.5 → 0.5.2

package/CHANGELOG.md

@@ -1,28 +1,21 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-## [0.4.5](https://github.com/rogerpadilla/uql/compare/uql-orm@0.4.0...uql-orm@0.4.5) (2026-03-14)
-
-
-### Features
-
-* add vector search integration tests for `findMany` with `$sort: { $vector }` and update test infrastructure. ([c920cde](https://github.com/rogerpadilla/uql/commit/c920cde46dbb4985d07a1926dfc3ac845862244c))
-* implement cursor-based stream with  across all queriers and deprecate  in favor of ([2d6c2ea](https://github.com/rogerpadilla/uql/commit/2d6c2ea0851d9c20ca9d092717087eaa65e5f937))
-* upgrade to Vite 8 and TypeScript 6, removing redundant compiler options and `vite-tsconfig-paths` plugin. ([f81563c](https://github.com/rogerpadilla/uql/commit/f81563cfe5246bfa59966f08493fd9786a817e02))
-
-
-
-
-
 # Changelog
 
 All notable changes to this project will be documented in this file. Please add new changes to the top.
 
 date format is [yyyy-mm-dd]
 
-## [0.4.5] - 2026-03-14
+## [0.5.1] - 2026-03-15
+### Chore
+- **Documentation**: Unified documentation strategy using NPM lifecycle scripts across subpackages.
+- **Maintenance**: Removed redundant `copyfiles` dependency and cleaned up build scripts.
+- **README**: Refined technical copy and visual feedback sections for a better developer documentation experience.
+
+## [0.5.0] - 2026-03-15
+### Features
+- **CockroachDB Support**: Full integration with a new dialect, querier, and Docker Compose configuration. Supports native upsert and mapped driver execution.
+### New Features
+- **CockroachDB Support**: Added first-class support for `cockroachdb` dialect, leveraging its PostgreSQL wire-compatibility. Includes native `upsert` support and seamlessly mapped driver execution.
+
 ### Testing
 - **Vector search integration tests**: Added 7 end-to-end tests for `findMany` with `$sort: { $vector }` against a real Postgres+pgvector database — covers cosine/L2 similarity ordering, `$project` distance projection, filter+sort combo, `$limit`, and empty-table edge case.
 - Docker Postgres image switched to `pgvector/pgvector:pg18` for pgvector extension support.

package/README.md

@@ -4,11 +4,10 @@
 
 [![tests](https://github.com/rogerpadilla/uql/actions/workflows/tests.yml/badge.svg)](https://github.com/rogerpadilla/uql) [![Coverage Status](https://coveralls.io/repos/github/rogerpadilla/uql/badge.svg?branch=main)](https://coveralls.io/github/rogerpadilla/uql?branch=main) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/rogerpadilla/uql/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/uql-orm.svg)](https://www.npmjs.com/package/uql-orm)
 
-**[UQL](https://uql-orm.dev)** is the [best TypeScript ORM](https://www.uql-orm.dev/blog/in-search-of-the-fastest-typescript-orm/). It is engineered to be **fast**, **safe**, and **universally compatible**.
-
+**[UQL](https://uql-orm.dev)** is a clean, ultra-fast TypeScript ORM designed for developers who value portability and performance. It eliminates the friction between SQL and MongoDB, providing a unified, type-safe experience without proprietary DSLs or heavy codegen steps.
 
 ```ts
-const users = await querier.findMany(User, {
+const results = await querier.findMany(User, {
   $select: { name: true, profile: { $select: { picture: true } } },
   $where: { name: { $istartsWith: 'a' }, posts: { tags: { name: 'typescript' } } },
   $sort: { createdAt: 'desc' },
@@ -20,22 +19,22 @@ const users = await querier.findMany(User, {
 
 ## Features
 
-| Feature                                                                  | Description                                                                                                                     |
-| :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
-| **[Intelligent Querying](https://uql-orm.dev/querying/relations)**       | Deep auto-completion for operators and [relations](https://uql-orm.dev/querying/relations) at any depth.                         |
-| **Serializable JSON**                                              | 100% valid JSON queries for easy transport over HTTP/Websockets.                                                                |
-| **Unified Dialects**                                               | Write once, run anywhere: PostgreSQL, MySQL, SQLite, MongoDB, and more.                                                         |
-| **[Naming Strategies](https://uql-orm.dev/naming-strategy)**           | Pluggable system to translate between TypeScript `camelCase` and database `snake_case`.                                     |
-| **Smart SQL Engine**                                               | Optimized sub-queries, placeholders ($1, $2), and minimal SQL generation via `QueryContext`.                                  |
-| **Thread-Safe by Design**                                          | Centralized task queue and `@Serialized()` decorator prevent race conditions.                                                 |
-| **[Declarative Transactions](https://uql-orm.dev/querying/transactions)**  | Standard `@Transactional()` and `@InjectQuerier()` decorators for NestJS/DI.                                                |
-| **[Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks)**| `@BeforeInsert`, `@AfterLoad` and 5 more decorators for validation, timestamps, and computed fields.                        |
-| **[Aggregate Queries](https://uql-orm.dev/querying/aggregate)** | `GROUP BY`, `HAVING`, `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, and `DISTINCT` across all dialects. |
-| **[Semantic Search](https://uql-orm.dev/querying/semantic-search)** | Vector similarity via `$sort` with `$vector`/`$distance`. Supports `vector`, `halfvec`, `sparsevec` types, HNSW/IVFFlat indexes, and 5 distance metrics across Postgres, MariaDB, SQLite, and MongoDB Atlas. |
-| **[Cursor Streaming](https://uql-orm.dev/querying/streaming)** | `findManyStream()` with native cursor-based iteration for SQLite, MongoDB, MariaDB, PostgreSQL, and MySQL. |
-| **[Modern & Versatile](https://uql-orm.dev/entities/virtual-fields)** | **Pure ESM**, high-res timing, [Soft-delete](https://uql-orm.dev/entities/soft-delete), and **JSONB/JSON** support. |
-| **[Database Migrations](https://www.uql-orm.dev/migrations)**          | Built-in [Entity-First synchronization](https://uql-orm.dev/migrations#3-entity-first-synchronization-development) and a robust CLI for version-controlled schema evolution. |
-| **[Logging & Monitoring](https://www.uql-orm.dev/logging)**               | Professional-grade monitoring with slow-query detection and colored output.                                                     |
+| Feature | Why it matters |
+| :--- | :--- |
+| **[Intelligent Querying](https://uql-orm.dev/querying/relations)** | Deep auto-completion for operators and relations at any depth—no more guessing property names. |
+| **Serializable JSON** | 100% valid JSON queries. Send your query logic over HTTP or WebSockets as easily as a string. |
+| **Unified Dialects** | Write once, run anywhere. Seamlessly switch between PostgreSQL, MySQL, SQLite, and MongoDB. |
+| **[Naming Strategies](https://uql-orm.dev/naming-strategy)** | No more `camelCase` vs `snake_case` headaches. Map your code to your database automatically. |
+| **Smart SQL Engine** | Zero-allocation SQL generation. Built for high-throughput apps where every millisecond counts. |
+| **Thread-Safe by Design** | Protect your data integrity with centralized task queues and the `@Serialized()` decorator. |
+| **[Declarative Transactions](https://uql-orm.dev/querying/transactions)** | Clean `@Transactional()` decorators that work beautifully with modern DI frameworks like NestJS. |
+| **[Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks)** | Automate validation, timestamps, and computed logic with intuitive class-based decorators. |
+| **[Aggregate Queries](https://uql-orm.dev/querying/aggregate)** | Real-time analytics with `GROUP BY`, `HAVING`, and native math operators across all dialects. |
+| **[Semantic Search](https://uql-orm.dev/querying/semantic-search)** | Native vector similarity search. Rank results by meaning using standard ORM operators. |
+| **[Cursor Streaming](https://uql-orm.dev/querying/streaming)** | Process millions of rows with a stable memory footprint using native driver-level cursors. |
+| **[Modern & Versatile](https://uql-orm.dev/entities/virtual-fields)** | Pure ESM, high-res timing, built-in soft-delete, and first-class JSONB/JSON support. |
+| **[Database Migrations](https://www.uql-orm.dev/migrations)** | Entity-First synchronization. DDL is auto-generated by diffing your code against the live DB. |
+| **[Logging & Monitoring](https://www.uql-orm.dev/logging)** | High-visibility debugging with slow-query detection and high-contrast terminal output. |
 
  
 
@@ -50,15 +49,16 @@ npm install uql-orm       # or bun add / pnpm add
 
 ### Supported Drivers (pick according to your database)
 
-| Database                                               | Command                        |
-| :----------------------------------------------------- | :----------------------------- |
-| **PostgreSQL** (incl. Neon, Cockroach, Yugabyte) | `npm install pg`             |
-| **MySQL** (incl. TiDB, Aurora)                   | `npm install mysql2`         |
-| **MariaDB**                                      | `npm install mariadb`        |
-| **SQLite**                                       | `npm install better-sqlite3` |
-| **LibSQL** (incl. Turso)                         | `npm install @libsql/client` |
-| **MongoDB**                                      | `npm install mongodb`        |
-| **Cloudflare D1**                                | _Native (no driver needed)_  |
+| Database | Command |
+| :--- | :--- |
+| **PostgreSQL** (incl. Neon, Cockroach, Yugabyte) | `npm install pg` |
+| **MySQL** (incl. TiDB, Aurora) | `npm install mysql2` |
+| **MariaDB** | `npm install mariadb` |
+| **SQLite** | `npm install better-sqlite3` |
+| **LibSQL** (incl. Turso) | `npm install @libsql/client` |
+| **MongoDB** | `npm install mongodb` |
+| **CockroachDB** | `npm install pg` |
+| **Cloudflare D1** | _Native (no driver needed)_ |
 
 ### TypeScript Configuration
 
@@ -75,30 +75,28 @@ Ensure your `tsconfig.json` is configured to support decorators and metadata:
 
  **Note:** UQL is Modern Pure ESM — ensure your project's `module` supports ESM imports (e.g., `NodeNext`, `ESNext`, `Bundler`).
 
-## 2. Define the Entities
+## 2. Define your Entities
 
 Annotate your classes with decorators. UQL's engine uses this metadata for both type-safe querying and precise DDL generation.
 
 ### Core Decorators
 
-| Decorator       | Purpose                                                                        |
-| :-------------- | :----------------------------------------------------------------------------- |
-| `@Entity()`   | Marks a class as a database table/collection.                                  |
-| `@Id()`       | Defines the Primary Key with support for `onInsert` generators (UUIDs, etc). |
-| `@Field()`    | Standard column. Use `{ references: ... }` for Foreign Keys.                 |
-| `@Index()`    | Defines a composite or custom index on one or more columns.                    |
-| `@OneToOne`   | Defines a one-to-one relationship.                                             |
-| `@OneToMany`  | Defines a one-to-many relationship.                                            |
-| `@ManyToOne`  | Defines a many-to-one relationship.                                            |
-| `@ManyToMany` | Defines a many-to-many relationship.                                           |
-| `@BeforeInsert` / `@AfterInsert` | Lifecycle hooks fired around `insert` operations.           |
-| `@BeforeUpdate` / `@AfterUpdate` | Lifecycle hooks fired around `update` operations.           |
-| `@BeforeDelete` / `@AfterDelete` | Lifecycle hooks fired around `delete` operations.           |
-| `@AfterLoad`  | Lifecycle hook fired after loading entities from the database.                  |
+| Decorator | Purpose |
+| :--- | :--- |
+| `@Entity()` | Marks a class as a database table/collection. |
+| `@Id()` | Defines the Primary Key with support for `onInsert` generators. |
+| `@Field()` | Standard column. Use `{ references: ... }` for Foreign Keys. |
+| `@Index()` | Defines a composite or custom index on one or more columns. |
+| `@OneToOne` | Defines a one-to-one relationship. |
+| `@OneToMany` | Defines a one-to-many relationship. |
+| `@ManyToOne` | Defines a many-to-one relationship. |
+| `@ManyToMany` | Defines a many-to-many relationship. |
+| `@BeforeInsert` | Lifecycle hooks fired around database operations. |
+| `@AfterLoad` | Lifecycle hook fired after loading entities. |
 
 ### Type Abstraction: Logical vs. Physical
 
-UQL separates the **intent** of your data from its **storage**. Both properties are **optional**; if omitted, UQL performs a *best-effort inference* using the TypeScript types from your class (provided `emitDecoratorMetadata` is enabled).
+UQL separates the **intent** of your data from its **storage**. Both properties are **optional**; if omitted, UQL performs a *best-effort inference* using the TypeScript types from your class.
 
 | Property | Purpose | Values |
 | :--- | :--- | :--- |
@@ -226,7 +224,7 @@ export class PostTag {
 }
 ```
 
-> **Pro Tip**: Use the `Relation<T>` utility type for relationship properties. It prevents TypeScript circular dependency errors while maintaining full type-safety.
+> **Senior Insight**: Use the `Relation<T>` utility type for relationship properties. It prevents TypeScript circular dependency errors while maintaining full type-safety throughout your app.
 
 &nbsp;
 
@@ -255,7 +253,7 @@ export default {
 } satisfies Config;
 ```
 
-> **Pro Tip**: Reusing the same connection pool for both your application and migrations is recommended. It reduces connection overhead and ensures consistent query settings (like naming strategies).
+> **Senior Insight**: Don't overcomplicate your setup. Reusing the same connection pool for both your application and migrations reduces overhead and ensures consistent behavior (like naming strategies) across your entire stack.
 
 &nbsp;
 
@@ -268,20 +266,19 @@ UQL provides a straightforward API to interact with your data. **Always ensure q
 ```ts
 const querier = await pool.getQuerier();
 try {
-  const users = await querier.findMany(User, {
+  const results = await querier.findMany(User, {
     $select: {
       name: true,
       profile: { $select: { bio: true }, $required: true } // INNER JOIN
     },
     $where: {
       status: 'active',
-      name: { $istartsWith: 'a' } // Case-insensitive search
+      name: { $istartsWith: 'a' }
     },
     $limit: 10,
-    $skip: 0
   });
 } finally {
-  await querier.release(); // Essential for pool health
+  await querier.release(); // Always release back to the pool
 }
 ```
 
@@ -347,7 +344,7 @@ const posts = await querier.findMany(Post, {
 
 **PostgreSQL:** `WHERE EXISTS (SELECT 1 FROM "PostTag" WHERE "PostTag"."postId" = "Post"."id" AND "PostTag"."tagId" IN (SELECT "Tag"."id" FROM "Tag" WHERE "Tag"."name" = $1))`
 
-> **Pro Tip**: Wrap JSONB field types with `Json<T>` (e.g., `settings?: Json<{ isArchived?: boolean }>`) to get IDE autocompletion for dot-notation paths.
+> **Senior Insight**: Wrap your JSON fields with `Json<T>` to get deep autocompletion for dot-notation paths. It turns a "guess and check" process into a type-safe workflow.
 
 &nbsp;
 
@@ -459,10 +456,10 @@ try {
 
 ## 5. Migrations & Synchronization
 
-UQL takes an **Entity-First** approach: you modify your TypeScript entity classes, and UQL auto-generates the migration files for you. No need to write DDL manually — UQL diffs your entities against the live database and generates the exact SQL needed.
+UQL takes an **Entity-First** approach. You modify your TypeScript classes, and UQL handles the heavy lifting—auto-generating migration files by diffing your code against the live database.
 
 ```bash
-# 1. Update your entity (add a field, change a type, add a relation...)
+# 1. Update your entity (add a field, change a type, etc.)
 # 2. Auto-generate the migration
 npx uql-migrate generate:entities add_user_nickname
 
@@ -470,7 +467,7 @@ npx uql-migrate generate:entities add_user_nickname
 npx uql-migrate up
 ```
 
-> **Your entities are the single source of truth.** Want manual migrations for data backfills or custom SQL? You can do that too — full automation + full control when you need it.
+> **Senior Insight**: Your entities are the single source of truth. This workflow eliminates the "drift" between what's in your code and what's in production.
 
 ### 1. Unified Configuration
 
@@ -587,7 +584,7 @@ UQL features a professional-grade, structured logging system designed for high v
 
 ### Visual Feedback
 
-The `DefaultLogger` provides high-contrast, colored output out of the box:
+The `DefaultLogger` provides high-contrast, colored output that makes debugging feel like a premium experience:
 
 ```text
 query: SELECT * FROM "user" WHERE "id" = $1 -- [123] [2ms]
@@ -595,7 +592,7 @@ slow query: UPDATE "post" SET "title" = $1 -- ["New Title"] [1250ms]
 error: Failed to connect to database: Connection timeout
 ```
 
-> **Pro Tip**: Even if you disable general query logging in production (`logger: ['error', 'warn', 'slowQuery']`), UQL stays silent *until* a query exceeds your threshold.
+> **Senior Insight**: In production, keep your logs lean. By setting `logger: ['error', 'warn', 'slowQuery']`, UQL stays silent until a performance bottleneck actually occurs.
 
 &nbsp;
 

package/dist/browser/uql-browser.min.js

@@ -1,207 +1,181 @@
-import sqlstring from 'sqlstring-sqlite';
-import { AbstractSqlDialect } from '../dialect/index.js';
-import { getMeta } from '../entity/index.js';
-import { hasKeys } from '../util/index.js';
-import { AbstractSqlQuerier, AbstractQuerierPool } from '../querier/index.js';
+import { _ as _apply_decs_2203_r } from './cc-BEf4wTUm.js';
+import { randomUUID } from 'node:crypto';
+import { Id, Field, ManyToOne, Entity, OneToOne, OneToMany, ManyToMany } from '../entity/index.js';
+import '../type/index.js';
+import { raw, lowerFirst, upperFirst, getKeys } from '../util/index.js';
+import 'reflect-metadata';
 
-class SqliteDialect extends AbstractSqlDialect {
-    constructor(namingStrategy){
-        super('sqlite', namingStrategy);
-    }
-    addValue(values, value) {
-        if (value instanceof Date) {
-            value = value.getTime();
-        } else if (typeof value === 'boolean') {
-            value = value ? 1 : 0;
-        }
-        return super.addValue(values, value);
-    }
-    compare(ctx, entity, key, val, opts) {
-        if (key === '$text') {
-            const meta = getMeta(entity);
-            const search = val;
-            const fields = search.$fields.map((fKey)=>{
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            });
-            const tableName = this.resolveTableName(entity, meta);
-            ctx.append(`${this.escapeId(tableName)} MATCH {${fields.join(' ')}} : `);
-            ctx.addValue(search.$value);
-            return;
-        }
-        super.compare(ctx, entity, key, val, opts);
-    }
-    compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
-        switch(op){
-            case '$elemMatch':
-                this.buildElemMatchCondition(ctx, entity, key, val, opts);
-                break;
-            case '$all':
-                {
-                    // SQLite: Check JSON array contains all values using multiple json_each subqueries
-                    const values = val;
-                    const conditions = values.map((v)=>{
-                        ctx.pushValue(JSON.stringify(v));
-                        return `EXISTS (SELECT 1 FROM json_each(${this.escapeId(key)}) WHERE value = json(?))`;
-                    }).join(' AND ');
-                    ctx.append(`(${conditions})`);
-                    break;
-                }
-            case '$size':
-                // SQLite: Check JSON array length
-                // e.g., json_array_length(roles) = 3, or json_array_length(roles) >= 2
-                this.buildSizeComparison(ctx, ()=>{
-                    ctx.append('json_array_length(');
-                    this.getComparisonKey(ctx, entity, key, opts);
-                    ctx.append(')');
-                }, val);
-                break;
-            default:
-                super.compareFieldOperator(ctx, entity, key, op, val, opts);
-        }
-    }
-    /**
-   * Build $elemMatch condition for SQLite JSON arrays.
-   * Uses EXISTS with json_each and supports nested operators.
-   */ buildElemMatchCondition(ctx, _entity, key, match, opts) {
-        ctx.append('EXISTS (SELECT 1 FROM json_each(');
-        this.getComparisonKey(ctx, _entity, key, opts);
-        ctx.append(') WHERE ');
-        const conditions = [];
-        for (const [field, value] of Object.entries(match)){
-            if (value && typeof value === 'object' && !Array.isArray(value)) {
-                // Value is an operator object
-                const ops = value;
-                for (const [op, opVal] of Object.entries(ops)){
-                    conditions.push(this.buildJsonFieldOperator(ctx, field, op, opVal));
-                }
-            } else {
-                // Simple equality
-                ctx.pushValue(value);
-                conditions.push(`json_extract(value, '$.${field}') = ?`);
-            }
-        }
-        ctx.append(conditions.join(' AND '));
-        ctx.append(')');
-    }
-    /**
-   * Build a comparison condition for a JSON field with an operator.
-   */ buildJsonFieldOperator(ctx, field, op, value) {
-        return this.buildJsonFieldCondition(ctx, {
-            ...this.getBaseJsonConfig(),
-            fieldAccessor: (f)=>`json_extract(value, '$.${f}')`
-        }, field, op, value);
-    }
-    getJsonFieldConfig(escapedColumn, jsonPath) {
-        return {
-            ...this.getBaseJsonConfig(),
-            fieldAccessor: ()=>`json_extract(${escapedColumn}, '$.${jsonPath}')`
-        };
-    }
-    getBaseJsonConfig() {
-        return {
-            ...super.getBaseJsonConfig(),
-            numericCast: (expr)=>`CAST(${expr} AS REAL)`,
-            neExpr: (f, ph)=>`${f} IS NOT ${ph}`
-        };
-    }
-    upsert(ctx, entity, conflictPaths, payload) {
-        this.onConflictUpsert(ctx, entity, conflictPaths, payload, this.insert.bind(this));
-    }
-    formatJsonMerge(ctx, escapedCol, value) {
-        let expr = escapedCol;
-        if (hasKeys(value.$merge)) {
-            ctx.pushValue(JSON.stringify(value.$merge));
-            expr = `json_patch(COALESCE(${escapedCol}, '{}'), ?)`;
-        }
-        if (value.$unset?.length) {
-            const paths = value.$unset.map((k)=>`'$.${this.escapeJsonKey(k)}'`).join(', ');
-            expr = `json_remove(${expr}, ${paths})`;
-        }
-        ctx.append(`${escapedCol} = ${expr}`);
-    }
+var _dec, _dec1, _dec2, _dec3, _dec4, _dec5, _dec6, /**
+   * auto-generated primary-key (when the `onInsert` property is omitted).
+   */ _init_id, /**
+   * foreign-keys are really simple to specify with the `reference` property.
+   */ _init_companyId, /**
+   * The `Relation` wrapper type can be used in ESM projects for the relations to
+   * avoid circular dependency issues.
+   */ _init_company, _init_creatorId, _init_creator, /**
+   * 'onInsert' property can be used to specify a custom mechanism for
+   * obtaining the value of a field when inserting:
+   */ _init_createdAt, /**
+   * 'onUpdate' property can be used to specify a custom mechanism for
+   * obtaining the value of a field when updating:
+   */ _init_updatedAt, _initProto, _dec7, _initClass, _BaseEntity, _dec8, _dec9, _dec10, _init_name, _init_description, _init_kind, _initProto1, _dec11, _initClass1, _BaseEntity1, _dec12, _dec13, /**
+   * an entity can specify its own ID Field and still inherit the others
+   * columns/relations from its parent entity.
+   */ _init_pk, _init_picture, _initProto2, _dec14, _initClass2, _BaseEntity2, _dec15, _dec16, _dec17, _dec18, _dec19, _init_name1, _init_email, _init_password, /**
+   * `mappedBy` property can be a callback or a string (callback is useful for auto-refactoring).
+   */ _init_profile, _init_users, _initProto3, _dec20, _initClass3, _dec21, _dec22, _init_id1, _init_name2, _initProto4, _dec23, _initClass4, _BaseEntity3, _dec24, _dec25, _dec26, _dec27, _init_name3, _init_description1, _init_parentLedgerId, _init_parentLedger, _initProto5, _dec28, _initClass5, _BaseEntity4, _dec29, _dec30, _dec31, /**
+   * an entity can override the ID Field and still inherit the others
+   * columns/relations from its parent entity.
+   * 'onInsert' property can be used to specify a custom mechanism for
+   * auto-generating the primary-key's value when inserting.
+   */ _init_pk1, _init_name4, _init_description2, _initProto6, _dec32, _initClass6, _BaseEntity5, _dec33, _dec34, _dec35, _dec36, _dec37, _init_name5, _init_percentage, _init_categoryId, _init_category, _init_description3, _initProto7, _dec38, _initClass7, _BaseEntity6, _dec39, _dec40, _dec41, _init_name6, _init_measureUnits, /**
+   * `onDelete` callback allows to specify which field will be used when deleting/querying this entity.
+   */ _init_deletedAt, _initProto8, _dec42, _initClass8, _BaseEntity7, _dec43, _dec44, _dec45, _dec46, _init_name7, _init_categoryId1, _init_category1, _init_deletedAt1, _initProto9, _dec47, _initClass9, _BaseEntity8, _dec48, _dec49, _dec50, _init_name8, _init_address, _init_description4, _initProto10, _dec51, _initClass10, _BaseEntity9, _dec52, _dec53, _dec54, _dec55, _dec56, _dec57, _dec58, _dec59, _dec60, _dec61, _dec62, _dec63, _dec64, _dec65, _dec66, _init_name9, _init_description5, _init_code, _init_buyLedgerAccountId, _init_buyLedgerAccount, _init_saleLedgerAccountId, _init_saleLedgerAccount, _init_taxId, _init_tax, _init_measureUnitId, _init_measureUnit, _init_salePrice, _init_inventoryable, _init_tags, _init_tagsCount, _initProto11, _dec67, _initClass11, _BaseEntity10, _dec68, _dec69, _dec70, _init_name10, _init_items, _init_itemsCount, _initProto12, _dec71, _initClass12, _dec72, _dec73, _dec74, _init_id2, _init_itemId, _init_tagId, _initProto13, _dec75, _initClass13, _BaseEntity11, _dec76, _dec77, _dec78, _init_itemAdjustments, _init_date, _init_description6, _initProto14, _dec79, _initClass14, _BaseEntity12, _dec80, _dec81, _dec82, _dec83, _dec84, _dec85, _dec86, _dec87, _init_itemId1, _init_item, _init_number, _init_buyPrice, _init_storehouseId, _init_storehouse, _init_inventoryAdjustmentId, _init_inventoryAdjustment, _initProto15, _dec88, _initClass15, _dec89, _dec90, _dec91, _init_id3, _init_name11, _init_vec, _initProto16;
+_dec = Id(), _dec1 = Field({
+    references: ()=>_Company
+}), _dec2 = ManyToOne({
+    entity: ()=>_Company
+}), _dec3 = Field({
+    references: ()=>_User
+}), _dec4 = ManyToOne({
+    entity: ()=>_User
+}), _dec5 = Field({
+    onInsert: Date.now
+}), _dec6 = Field({
+    onUpdate: Date.now
+});
+/**
+ * an `abstract` class can (optionally) be used as the base "template" for the entities
+ * (so common fields' declaration is easily reused).
+ */ class BaseEntity {
     static{
-        /** sqlite-vec distance functions. */ this.VECTOR_FNS = {
-            cosine: 'vec_distance_cosine',
-            l2: 'vec_distance_L2',
-            hamming: 'vec_distance_hamming'
-        };
+        ({ e: [_init_id, _init_companyId, _init_company, _init_creatorId, _init_creator, _init_createdAt, _init_updatedAt, _initProto] } = _apply_decs_2203_r(this, [
+            [
+                _dec,
+                0,
+                "id"
+            ],
+            [
+                _dec1,
+                0,
+                "companyId"
+            ],
+            [
+                _dec2,
+                0,
+                "company"
+            ],
+            [
+                _dec3,
+                0,
+                "creatorId"
+            ],
+            [
+                _dec4,
+                0,
+                "creator"
+            ],
+            [
+                _dec5,
+                0,
+                "createdAt"
+            ],
+            [
+                _dec6,
+                0,
+                "updatedAt"
+            ]
+        ], []));
     }
-    /** Emit a sqlite-vec distance function: `vec_distance_<metric>(col, ?)`. */ appendVectorSort(ctx, meta, key, search) {
-        this.appendFunctionVectorSort(ctx, meta, key, search, SqliteDialect.VECTOR_FNS, 'SQLite');
+    constructor(){
+        this.id = (_initProto(this), _init_id(this));
+        this.companyId = _init_companyId(this);
+        this.company = _init_company(this);
+        this.creatorId = _init_creatorId(this);
+        this.creator = _init_creator(this);
+        this.createdAt = _init_createdAt(this);
+        this.updatedAt = _init_updatedAt(this);
+    }
+}
+let _Company;
+_dec7 = Entity(), _dec8 = Field(), _dec9 = Field(), _dec10 = Field({
+    type: 'jsonb'
+});
+class Company extends (_BaseEntity = BaseEntity) {
+    static{
+        ({ e: [_init_name, _init_description, _init_kind, _initProto1], c: [_Company, _initClass] } = _apply_decs_2203_r(this, [
+            [
+                _dec8,
+                0,
+                "name"
+            ],
+            [
+                _dec9,
+                0,
+                "description"
+            ],
+            [
+                _dec10,
+                0,
+                "kind"
+            ]
+        ], [
+            _dec7
+        ], _BaseEntity));
     }
-    escape(value) {
-        return sqlstring.escape(value);
+    static{
+        _initClass();
     }
-}
-
-class AbstractSqliteQuerier extends AbstractSqlQuerier {
-    buildUpdateResult(changes, lastInsertRowid) {
-        const firstId = lastInsertRowid ? Number(lastInsertRowid) - (changes - 1) : undefined;
-        const ids = firstId ? Array(changes).fill(firstId).map((i, index)=>i + index) : [];
-        return {
-            changes,
-            ids,
-            firstId
-        };
+    constructor(...args){
+        super(...args), this.name = (_initProto1(this), _init_name(this)), this.description = _init_description(this), this.kind = _init_kind(this);
     }
 }
-
-class SqliteQuerier extends AbstractSqliteQuerier {
-    constructor(db, extra){
-        super(new SqliteDialect(extra?.namingStrategy), extra), this.db = db, this.extra = extra;
-    }
-    async internalAll(query, values) {
-        return this.db.prepare(query).all(values || []);
-    }
-    async *internalStream(query, values) {
-        for (const row of this.db.prepare(query).iterate(values || [])){
-            yield row;
-        }
-    }
-    async internalRun(query, values) {
-        const { changes, lastInsertRowid } = this.db.prepare(query).run(values || []);
-        return this.buildUpdateResult(changes, lastInsertRowid);
-    }
-    async internalRelease() {
-        if (this.hasOpenTransaction) {
-            throw TypeError('pending transaction');
-        }
-    // no-op
+let _Profile;
+_dec11 = Entity({
+    name: 'user_profile'
+}), _dec12 = Id(), _dec13 = Field({
+    name: 'image'
+});
+class Profile extends (_BaseEntity1 = BaseEntity) {
+    static{
+        ({ e: [_init_pk, _init_picture, _initProto2], c: [_Profile, _initClass1] } = _apply_decs_2203_r(this, [
+            [
+                _dec12,
+                0,
+                "pk"
+            ],
+            [
+                _dec13,
+                0,
+                "picture"
+            ]
+        ], [
+            _dec11
+        ], _BaseEntity1));
     }
-}
-
-class Sqlite3QuerierPool extends AbstractQuerierPool {
-    constructor(filename, opts, extra){
-        super('sqlite', extra), this.filename = filename, this.opts = opts;
-    }
-    async getQuerier() {
-        if (!this.querier) {
-            let db;
-            if (typeof Bun !== 'undefined') {
-                const { Database: BunDatabase } = await import('bun:sqlite');
-                const bunDb = new BunDatabase(this.filename, this.opts);
-                bunDb.run('PRAGMA journal_mode = WAL');
-                db = bunDb;
-            } else {
-                const { default: BetterSqlite3 } = await import('better-sqlite3');
-                db = new BetterSqlite3(this.filename, this.opts);
-                db.pragma('journal_mode = WAL');
-            }
-            this.querier = new SqliteQuerier(db, this.extra);
-        }
-        return this.querier;
+    static{
+        _initClass1();
     }
-    async end() {
-        await this.querier?.db.close();
-        this.querier = undefined;
+    constructor(...args){
+        super(...args), this.pk = (_initProto2(this), _init_pk(this)), this.picture = _init_picture(this);
     }
 }
-
-export { Sqlite3QuerierPool, SqliteDialect, SqliteQuerier };
-//# sourceMappingURL=uql-browser.min.js.map
-1, _init_email, _init_password, _init_profile, _init_users, _initProto3], c: [_User, _initClass2] } = _apply_decs_2203_r(this, [
+let _User;
+_dec14 = Entity(), _dec15 = Field(), _dec16 = Field({
+    updatable: false
+}), _dec17 = Field({
+    eager: false
+}), _dec18 = OneToOne({
+    entity: ()=>_Profile,
+    mappedBy: (profile)=>profile.creator,
+    cascade: true
+}), _dec19 = OneToMany({
+    entity: ()=>_User,
+    mappedBy: 'creator'
+});
+class User extends (_BaseEntity2 = BaseEntity) {
+    static{
+        ({ e: [_init_name1, _init_email, _init_password, _init_profile, _init_users, _initProto3], c: [_User, _initClass2] } = _apply_decs_2203_r(this, [
             [
                 _dec15,
                 0,