ts-prorm-orm 2.0.0 → 2.1.0

package/dist/decorators/trigger.d.ts

@@ -1,11 +1,12 @@
 /**
- * @Trigger class decorator — declare a database trigger on a model class.
+ * `@Trigger` class decorator — declare a database trigger on a model class.
  *
  * Stores trigger metadata using plain class properties (no reflect-metadata
  * dependency) consistent with the rest of this decorator suite.
  *
  * Example:
  *
+ * ```ts
  *   @Trigger({
  *     name: 'trg_users_audit',
  *     timing: 'AFTER',
@@ -20,6 +21,7 @@
  *
  *   // Generate DDL:
  *   const sql = buildCreateTriggerSQL('users', triggers[0], 'mysql');
+ * ```
  */
 export interface TriggerOptions {
     /** The trigger name in the database. */

package/dist/decorators/trigger.js

@@ -1,12 +1,13 @@
 "use strict";
 /**
- * @Trigger class decorator — declare a database trigger on a model class.
+ * `@Trigger` class decorator — declare a database trigger on a model class.
  *
  * Stores trigger metadata using plain class properties (no reflect-metadata
  * dependency) consistent with the rest of this decorator suite.
  *
  * Example:
  *
+ * ```ts
  *   @Trigger({
  *     name: 'trg_users_audit',
  *     timing: 'AFTER',
@@ -21,6 +22,7 @@
  *
  *   // Generate DDL:
  *   const sql = buildCreateTriggerSQL('users', triggers[0], 'mysql');
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Trigger = Trigger;

package/dist/decorators/uuid.d.ts

@@ -6,6 +6,7 @@
  *
  * Usage:
  *
+ * ```ts
  *   // Auto-generate UUID using gen_random_uuid() (PostgreSQL 13+)
  *   @UUID()
  *   id: string;
@@ -17,6 +18,7 @@
  *   // With custom default
  *   @UUID({ defaultValue: 'gen_random_uuid' })
  *   id: string;
+ * ```
  */
 /**
  * Options for UUID column type
@@ -49,14 +51,18 @@ export interface UUIDMetadata {
  * @example
  * // Auto-generate UUID
  * class User extends Model {
+ * ```ts
  *   @UUID()
  *   id: string;
+ * ```
  * }
  *
  * // With specific default
  * class User extends Model {
+ * ```ts
  *   @UUID({ defaultValue: 'uuid_generate_v4' })
  *   id: string;
+ * ```
  * }
  */
 export declare function UUID(options?: UUIDDecoratorOptions): PropertyDecorator;

package/dist/decorators/uuid.js

@@ -7,6 +7,7 @@
  *
  * Usage:
  *
+ * ```ts
  *   // Auto-generate UUID using gen_random_uuid() (PostgreSQL 13+)
  *   @UUID()
  *   id: string;
@@ -18,6 +19,7 @@
  *   // With custom default
  *   @UUID({ defaultValue: 'gen_random_uuid' })
  *   id: string;
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UUID = UUID;
@@ -37,14 +39,18 @@ const uuidMetadataMap = new Map();
  * @example
  * // Auto-generate UUID
  * class User extends Model {
+ * ```ts
  *   @UUID()
  *   id: string;
+ * ```
  * }
  *
  * // With specific default
  * class User extends Model {
+ * ```ts
  *   @UUID({ defaultValue: 'uuid_generate_v4' })
  *   id: string;
+ * ```
  * }
  */
 function UUID(options) {

package/dist/decorators/view.d.ts

@@ -1,10 +1,11 @@
 /**
- * @View class decorator — annotate a Model class so it maps to a database view
+ * `@View` class decorator — annotate a Model class so it maps to a database view
  * instead of a base table. The ORM stores the view definition and can generate
  * the CREATE VIEW DDL for you.
  *
  * Example:
  *
+ * ```ts
  *   @View({
  *     name: 'active_users_view',
  *     query: `
@@ -30,6 +31,7 @@
  *
  *   // Query it just like a normal model:
  *   const users = await ActiveUser.findAll({ where: { name: 'Alice' } });
+ * ```
  */
 import type { Prorm } from '../prorm';
 export interface ViewOptions {
@@ -83,8 +85,10 @@ export declare function getViewOptions(target: Function): ViewOptions | undefine
  * - Sets the `tableName` option to the view name so findAll() etc. work correctly.
  * - Registers view metadata so the ORM can generate CREATE VIEW DDL.
  *
+ * ```ts
  *   @View({ name: 'active_users_view', query: 'SELECT ...' })
  *   class ActiveUser extends Model { ... }
+ * ```
  */
 export declare function View(options: ViewOptions): (target: Function) => void;
 export declare const ViewRegistry: {
@@ -166,6 +170,7 @@ export declare function getMaterializedViewOptions(target: Function): Materializ
  * - Registers materialized view metadata so the ORM can generate CREATE MATERIALIZED VIEW DDL.
  * - Adds a `refresh()` static method for refreshing the view data.
  *
+ * ```ts
  *   @MaterializedView({
  *     name: 'user_stats_view',
  *     query: `
@@ -194,6 +199,7 @@ export declare function getMaterializedViewOptions(target: Function): Materializ
  *   await UserStats.refresh();
  *   // Or concurrently (requires unique index):
  *   await UserStats.refresh({ concurrently: true });
+ * ```
  */
 export declare function MaterializedView(options: MaterializedViewDecoratorOptions): (target: Function) => void;
 export declare const MaterializedViewRegistry: {

package/dist/decorators/view.js

@@ -1,11 +1,12 @@
 "use strict";
 /**
- * @View class decorator — annotate a Model class so it maps to a database view
+ * `@View` class decorator — annotate a Model class so it maps to a database view
  * instead of a base table. The ORM stores the view definition and can generate
  * the CREATE VIEW DDL for you.
  *
  * Example:
  *
+ * ```ts
  *   @View({
  *     name: 'active_users_view',
  *     query: `
@@ -31,6 +32,7 @@
  *
  *   // Query it just like a normal model:
  *   const users = await ActiveUser.findAll({ where: { name: 'Alice' } });
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MaterializedViewRegistry = exports.ViewRegistry = void 0;
@@ -54,8 +56,10 @@ function getViewOptions(target) {
  * - Sets the `tableName` option to the view name so findAll() etc. work correctly.
  * - Registers view metadata so the ORM can generate CREATE VIEW DDL.
  *
+ * ```ts
  *   @View({ name: 'active_users_view', query: 'SELECT ...' })
  *   class ActiveUser extends Model { ... }
+ * ```
  */
 function View(options) {
     return function (target) {
@@ -143,6 +147,7 @@ function getMaterializedViewOptions(target) {
  * - Registers materialized view metadata so the ORM can generate CREATE MATERIALIZED VIEW DDL.
  * - Adds a `refresh()` static method for refreshing the view data.
  *
+ * ```ts
  *   @MaterializedView({
  *     name: 'user_stats_view',
  *     query: `
@@ -171,6 +176,7 @@ function getMaterializedViewOptions(target) {
  *   await UserStats.refresh();
  *   // Or concurrently (requires unique index):
  *   await UserStats.refresh({ concurrently: true });
+ * ```
  */
 function MaterializedView(options) {
     return function (target) {

package/dist/dialects/dialect.d.ts

@@ -4,6 +4,16 @@
  */
 import { Transaction, TransactionOptions, QueryResult, QueryOptions, DataType, WhereOptions, Order, IncludeOptions, PartitionBound, CreatePartitionOptions, AttachPartitionOptions, DetachPartitionOptions, RefreshOptions, MaterializedViewOptions, DropMaterializedViewOptions, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, TriggerOptions, DropTriggerOptions, SequenceOptions, DropSequenceOptions, PolicyOptions, DropPolicyOptions, StreamOptions } from '../types';
 import type { Readable } from 'stream';
+/**
+ * The contract every SQL engine implements.
+ *
+ * A dialect owns everything engine-specific: identifier quoting, value escaping,
+ * how DDL is written, which clauses are legal, and how pagination and locking
+ * are spelled. Model code builds the same `FindOptions` regardless, and
+ * the dialect is the single place that turns it into SQL for one engine —
+ * which is why `LIMIT ... OFFSET` on PostgreSQL becomes `OFFSET ... FETCH
+ * NEXT` on MSSQL without the caller changing.
+ */
 export interface Dialect {
     /**
      * The name of the dialect
@@ -582,6 +592,10 @@ export interface Dialect {
     executeStoredProcedure(options: ExecuteStoredProcedureOptions): Promise<QueryResult>;
     hasStoredProcedure(procedureName: string, schema?: string): Promise<boolean>;
 }
+/**
+ * One column in a `CREATE TABLE` or `ALTER TABLE`: its type, nullability,
+ * default, and key or reference membership.
+ */
 export interface ColumnDefinition {
     type: DataType;
     allowNull?: boolean;
@@ -616,6 +630,10 @@ export interface ColumnDefinition {
      */
     invisible?: boolean;
 }
+/**
+ * Table-level options for `CREATE TABLE` — the engine, charset, comment,
+ * partitioning and any indexes or constraints declared inline.
+ */
 export interface TableOptions {
     ifNotExists?: boolean;
     engine?: string;
@@ -667,6 +685,9 @@ export interface TableOptions {
         validToColumn?: string;
     };
 }
+/**
+ * An index declared alongside the table rather than in a separate statement.
+ */
 export interface TableIndex {
     name?: string;
     unique?: boolean;
@@ -680,6 +701,10 @@ export interface TableIndex {
     /** Include columns for covering index (PostgreSQL 11+, MySQL 8.0.17+) */
     include?: string[];
 }
+/**
+ * A constraint declared alongside the table: primary key, unique, check,
+ * foreign key or exclusion.
+ */
 export interface TableConstraint {
     name?: string;
     type: 'PRIMARY KEY' | 'UNIQUE' | 'FOREIGN KEY' | 'CHECK';
@@ -692,10 +717,18 @@ export interface TableConstraint {
     };
     check?: string;
 }
+/**
+ * Options for `DROP TABLE`, including `ifExists` and whether to cascade to
+ * dependent objects.
+ */
 export interface DropTableOptions {
     ifExists?: boolean;
     cascade?: boolean;
 }
+/**
+ * What the engine reports back about an existing table — the shape returned
+ * by `describeTable`, used by schema diffing.
+ */
 export interface TableDescription {
     [columnName: string]: {
         type: string;
@@ -705,6 +738,11 @@ export interface TableDescription {
         autoIncrement: boolean;
     };
 }
+/**
+ * Options for `CREATE INDEX`: uniqueness, method, included columns, and the
+ * `where` predicate that makes it partial. Not every engine supports partial
+ * indexes; the dialect rejects the option rather than silently dropping it.
+ */
 export interface IndexOptions {
     /** Explicit index name (used by the `(tableName, fields, options)` addIndex shorthand) */
     name?: string;
@@ -744,6 +782,9 @@ export interface IndexOptions {
      */
     invisible?: boolean;
 }
+/**
+ * An existing index as reported by the engine.
+ */
 export interface IndexDefinition {
     name: string;
     unique?: boolean;
@@ -755,10 +796,17 @@ export interface IndexDefinition {
     /** See {@link IndexOptions.invisible}. */
     invisible?: boolean;
 }
+/**
+ * Options for `DROP INDEX`, including `ifExists` and concurrency where the
+ * engine offers it.
+ */
 export interface DropIndexOptions {
     ifExists?: boolean;
     cascade?: boolean;
 }
+/**
+ * An existing constraint as reported by the engine.
+ */
 export interface ConstraintDefinition {
     name: string;
     type: 'PRIMARY KEY' | 'UNIQUE' | 'FOREIGN KEY' | 'CHECK';
@@ -772,6 +820,9 @@ export interface ConstraintDefinition {
     check?: string;
     deferrable?: 'INITIALLY DEFERRED' | 'INITIALLY IMMEDIATE';
 }
+/**
+ * Options for dropping a named constraint.
+ */
 export interface DropConstraintOptions {
     ifExists?: boolean;
     cascade?: boolean;
@@ -796,6 +847,10 @@ export interface DropViewOptions {
     /** If true, also drops dependent views (PostgreSQL) */
     cascade?: boolean;
 }
+/**
+ * Options for dropping a schema, including whether to cascade to the objects
+ * inside it.
+ */
 export interface DropSchemaOptions {
     ifExists?: boolean;
     cascade?: boolean;
@@ -889,6 +944,10 @@ export interface DropDomainOptions {
     /** Schema the domain lives in */
     schema?: string;
 }
+/**
+ * Options for `CREATE VIEW` — the defining query, whether it is materialised,
+ * and whether to replace an existing view.
+ */
 export interface ViewOptions {
     /** Replace the view if it already exists (CREATE OR REPLACE) */
     replace?: boolean;
@@ -897,12 +956,19 @@ export interface ViewOptions {
     /** View comment */
     comment?: string;
 }
+/**
+ * A foreign server: the wrapper that reaches it and the connection options it
+ * needs. See the foreign-data-wrappers guide.
+ */
 export interface FdwForeignServerOptions {
     fdw: string;
     options?: Record<string, string>;
     version?: string;
     ifNotExists?: boolean;
 }
+/**
+ * Changes to an existing foreign server's version or options.
+ */
 export interface FdwAlterForeignServerOptions {
     options?: Record<string, string>;
     addOptions?: Record<string, string>;
@@ -910,16 +976,26 @@ export interface FdwAlterForeignServerOptions {
     dropOptions?: string[];
     version?: string;
 }
+/**
+ * Maps a local role to credentials on a foreign server.
+ */
 export interface FdwUserMappingOptions {
     serverName: string;
     user: string;
     options?: Record<string, string>;
     ifNotExists?: boolean;
 }
+/**
+ * One column of a foreign table, including the remote name when it differs.
+ */
 export interface FdwForeignTableColumnDef {
     type: string;
     options?: string;
 }
+/**
+ * A foreign table: which server it lives on, its columns, and the remote
+ * object it maps to.
+ */
 export interface FdwForeignTableOptions {
     serverName: string;
     schema?: string;
@@ -927,21 +1003,36 @@ export interface FdwForeignTableOptions {
     options?: Record<string, string>;
     ifNotExists?: boolean;
 }
+/**
+ * Options for importing a remote schema wholesale, with optional limits on
+ * which tables come across.
+ */
 export interface FdwImportForeignSchemaOptions {
     localSchema?: string;
     limitTo?: string[];
     except?: string[];
     options?: Record<string, string>;
 }
+/**
+ * Options for dropping a view, including the materialised variant.
+ */
 export interface DropViewOptions {
     ifExists?: boolean;
     cascade?: boolean;
 }
+/**
+ * Shared options for the statement builders: the transaction to run inside
+ * and any per-statement logging override.
+ */
 export interface BuildOptions {
     replacements?: Record<string, any>;
     model?: any;
     include?: IncludeOptions[];
 }
+/**
+ * Options for building an `INSERT`, including returning clauses and conflict
+ * handling where the engine supports them.
+ */
 export interface InsertOptions {
     /** Schema to use for the table */
     schema?: string;
@@ -951,6 +1042,10 @@ export interface InsertOptions {
     /** Fields to update on conflict (MySQL: ON DUPLICATE KEY UPDATE, PostgreSQL/SQLite: ON CONFLICT DO UPDATE, MariaDB: ON DUPLICATE KEY UPDATE) */
     updateOnDuplicate?: string[];
 }
+/**
+ * Options for an insert-or-update, including which columns decide whether a
+ * row already exists and which are written on conflict.
+ */
 export interface UpsertQueryOptions {
     /** Fields to use for conflict resolution (ON CONFLICT for PostgreSQL/SQLite, ON DUPLICATE KEY for MySQL/MariaDB) */
     conflictFields?: string[];
@@ -963,15 +1058,28 @@ export interface UpsertQueryOptions {
     /** Model raw attributes for type casting */
     model?: any;
 }
+/**
+ * Options for building an `UPDATE`: the `where` that selects rows, and any
+ * limit or ordering the engine permits on it.
+ */
 export interface UpdateOptions {
     limit?: number;
     returning?: boolean | string[];
 }
+/**
+ * Options for building a `DELETE`, including the `where` and any limit the
+ * engine permits.
+ */
 export interface DeleteOptions {
     limit?: number;
     returning?: boolean | string[];
     truncate?: boolean;
 }
+/**
+ * Everything a `SELECT` can carry once associations have been resolved:
+ * columns, joins, filtering, grouping, ordering, pagination and locking. This
+ * is the dialect-facing form of `FindOptions`.
+ */
 export interface SelectOptions {
     tableName: string;
     /** Schema to use for the table */
@@ -1051,6 +1159,10 @@ export interface CTEOption {
     /** Optional explicit column list: `name (col1, col2, ...) AS (...)`. */
     columns?: string[];
 }
+/**
+ * Construction options for a dialect instance — the connection settings and
+ * behaviour flags it needs to build and run statements.
+ */
 export interface DialectOptions {
     host?: string;
     port?: number;

package/dist/external-fields/decorator.d.ts

@@ -9,6 +9,7 @@
  *
  *   prorm.registerStore('assets', s3Store, { defaultBucket: 'avatars' });
  *
+ * ```ts
  *   @Table()
  *   class User extends Model {
  *     @Column(DataTypes.STRING) declare name: string;
@@ -21,6 +22,7 @@
  *   await user.loadAvatar();        // GET, populates user.avatar
  *   user.avatar = newBytes;
  *   await user.save();              // PUT, then persists the key column
+ * ```
  *
  * The key column (`avatarKey` by default) is registered automatically, so it
  * does not need its own `@Column`.

package/dist/external-fields/decorator.js

@@ -10,6 +10,7 @@
  *
  *   prorm.registerStore('assets', s3Store, { defaultBucket: 'avatars' });
  *
+ * ```ts
  *   @Table()
  *   class User extends Model {
  *     @Column(DataTypes.STRING) declare name: string;
@@ -22,6 +23,7 @@
  *   await user.loadAvatar();        // GET, populates user.avatar
  *   user.avatar = newBytes;
  *   await user.save();              // PUT, then persists the key column
+ * ```
  *
  * The key column (`avatarKey` by default) is registered automatically, so it
  * does not need its own `@Column`.

package/dist/models/associations.d.ts

@@ -18,6 +18,10 @@ declare abstract class BaseAssociation {
      */
     getAssociationConfig(): AssociationConfig;
 }
+/**
+ * The resolved shape of a declared association: the two models, the foreign
+ * key, the alias, and any join table.
+ */
 export interface AssociationConfig {
     model: ModelStatic<any>;
     as: string;
@@ -28,6 +32,9 @@ export interface AssociationConfig {
     onDelete?: string;
     onUpdate?: string;
 }
+/**
+ * An eager-load nested inside another, for traversing more than one hop.
+ */
 export interface NestedIncludeOptions extends IncludeOptions {
     /**
      * Nested includes - support for multi-level eager loading
@@ -59,6 +66,10 @@ export declare class HasOneAssociation extends BaseAssociation {
      */
     getConstraintSql(tableName: string): string;
 }
+/**
+ * A one-to-many relationship. The foreign key lives on the **target**, so the
+ * child rows are what get written when the association changes.
+ */
 export declare class HasManyAssociation extends BaseAssociation {
     constructor(source: ModelStatic<any>, target: ModelStatic<any>, options?: AssociationOptions);
     inferForeignKey(): string;
@@ -68,6 +79,10 @@ export declare class HasManyAssociation extends BaseAssociation {
      */
     getConstraintSql(tableName: string): string;
 }
+/**
+ * A many-to-one relationship. The foreign key lives on the **source**, so the
+ * row you called it on is what gets written.
+ */
 export declare class BelongsToAssociation extends BaseAssociation {
     constructor(source: ModelStatic<any>, target: ModelStatic<any>, options?: AssociationOptions);
     inferForeignKey(): string;
@@ -81,6 +96,10 @@ export declare class BelongsToAssociation extends BaseAssociation {
      */
     getForeignKeyOptions(): AssociationForeignKeyOptions | undefined;
 }
+/**
+ * A many-to-many relationship through a join table. Neither side holds a
+ * foreign key; the join table holds both.
+ */
 export declare class BelongsToManyAssociation extends BaseAssociation {
     private through;
     private throughModel;
@@ -93,18 +112,37 @@ export declare class BelongsToManyAssociation extends BaseAssociation {
     setThroughModel(model: ModelStatic<any>): void;
     getThroughModel(): ModelStatic<any> | null;
 }
+/**
+ * The instance methods a `hasOne` adds — get, set and create the related row.
+ */
 export interface HasOneMixin {
     (target: ModelStatic<any>, options?: AssociationOptions): HasOneAssociation;
 }
+/**
+ * The instance methods a `hasMany` adds — get, set, add, remove, count and
+ * create related rows.
+ */
 export interface HasManyMixin {
     (target: ModelStatic<any>, options?: AssociationOptions): HasManyAssociation;
 }
+/**
+ * The instance methods a `belongsTo` adds — get, set, unset and create the
+ * parent row.
+ */
 export interface BelongsToMixin {
     (target: ModelStatic<any>, options?: AssociationOptions): BelongsToAssociation;
 }
+/**
+ * The instance methods a `belongsToMany` adds, including the join-table
+ * operations for adding and removing links.
+ */
 export interface BelongsToManyMixin {
     (target: ModelStatic<any>, options?: AssociationOptions): BelongsToManyAssociation;
 }
+/**
+ * Attaches the association helper methods to a model, named after the alias
+ * so `User.hasMany(Post)` yields `getPosts`, `addPost` and the rest.
+ */
 export declare function createAssociationMixins(source: ModelStatic<any>, sourceModelName: string, instancePrototype?: any): {
     hasOne: HasOneMixin;
     hasMany: HasManyMixin;

package/dist/models/associations.js

@@ -130,6 +130,10 @@ class HasOneAssociation extends BaseAssociation {
 }
 exports.HasOneAssociation = HasOneAssociation;
 // HasMany Association - one-to-many where source has many targets
+/**
+ * A one-to-many relationship. The foreign key lives on the **target**, so the
+ * child rows are what get written when the association changes.
+ */
 class HasManyAssociation extends BaseAssociation {
     constructor(source, target, options = {}) {
         super(source, target, options);
@@ -163,6 +167,10 @@ class HasManyAssociation extends BaseAssociation {
 }
 exports.HasManyAssociation = HasManyAssociation;
 // BelongsTo Association - one-to-one where source belongs to target
+/**
+ * A many-to-one relationship. The foreign key lives on the **source**, so the
+ * row you called it on is what gets written.
+ */
 class BelongsToAssociation extends BaseAssociation {
     constructor(source, target, options = {}) {
         super(source, target, options);
@@ -203,6 +211,10 @@ class BelongsToAssociation extends BaseAssociation {
 }
 exports.BelongsToAssociation = BelongsToAssociation;
 // BelongsToMany Association - many-to-many through a junction table
+/**
+ * A many-to-many relationship through a join table. Neither side holds a
+ * foreign key; the join table holds both.
+ */
 class BelongsToManyAssociation extends BaseAssociation {
     constructor(source, target, options = {}) {
         super(source, target, options);
@@ -278,6 +290,10 @@ class BelongsToManyAssociation extends BaseAssociation {
 }
 exports.BelongsToManyAssociation = BelongsToManyAssociation;
 // Factory function to create association mixin methods
+/**
+ * Attaches the association helper methods to a model, named after the alias
+ * so `User.hasMany(Post)` yields `getPosts`, `addPost` and the rest.
+ */
 function createAssociationMixins(source, sourceModelName, instancePrototype) {
     // Use provided instance prototype, or fall back to source.prototype, or source itself
     const prototypeTarget = instancePrototype || source.prototype || source;