@tstdl/base 0.93.35 → 0.93.36

package/source/orm/decorators.ts

@@ -0,0 +1,546 @@
+/**
+ * @module
+ * Defines decorators for ORM entities and columns, used to configure database schema mapping.
+ */
+import type { SQL } from 'drizzle-orm';
+import type { ExtraConfigColumn } from 'drizzle-orm/pg-core';
+import { match } from 'ts-pattern';
+import type { LiteralUnion, SetRequired } from 'type-fest';
+
+import { createClassDecorator, createDecorator, createPropertyDecorator, type PropertyDecoratorData, type PropertyMetadata, type SpecificCreateDecoratorOptions, type TypeMetadata } from '#/reflection/index.js';
+import { Property } from '#/schema/index.js';
+import type { AbstractConstructor, Record, TypedOmit } from '#/types/index.js';
+import { merge } from '#/utils/merge.js';
+import { filterUndefinedObjectProperties, objectEntries, propertyNameOf } from '#/utils/object/index.js';
+import { isArray, isFunction, isString, isUndefined } from '#/utils/type-guards.js';
+import type { ValueOrProvider } from '#/utils/value-or-provider.js';
+import type { AnyEntity, BaseEntity, Entity, EntityType } from './entity.js';
+import type { Query } from './query/index.js';
+import type { TargetColumnPath } from './repository.types.js';
+import type { ExtraConfigColumnsFromType } from './server/types.js';
+
+type IndexMethod = LiteralUnion<'hash' | 'btree' | 'gist' | 'spgist' | 'gin' | 'brin' | 'hnsw' | 'ivfflat' | 'bm25', string>;
+type NamingStrategy = 'abbreviated-table';
+
+type Column<T extends BaseEntity> = TargetColumnPath<T>;
+type Columns<T extends BaseEntity> = [Column<T>, ...Column<T>[]];
+
+export type ParadeIndexColumn<T extends BaseEntity> = TargetColumnPath<T> | SQL | ExtraConfigColumn;
+export type ParadeIndexColumnConfig<T extends BaseEntity> = ValueOrProvider<ParadeIndexColumn<T> | readonly [ParadeIndexColumn<T>, ParadeFieldOptions], ExtraConfigColumnsFromType<EntityType<T>>>;
+export type ParadeIndexCompoundColumnColumnsProvider<T extends BaseEntity> = ValueOrProvider<readonly ParadeIndexColumn<T>[], ExtraConfigColumnsFromType<EntityType<T>>>;
+export type ParadeIndexCompoundColumnConfig<T extends BaseEntity> = readonly [ParadeIndexCompoundColumnColumnsProvider<T>, SetRequired<ParadeFieldOptions, 'alias' | 'tokenizer'>];
+export type ParadeIndexExpressionProvider<T extends BaseEntity> = SqlOrBuilder<T, string>;
+export type ParadeIndexExpressionConfig<T extends BaseEntity> = readonly [ParadeIndexExpressionProvider<T>, SetRequired<ParadeFieldOptions, 'alias' | 'tokenizer'>];
+
+export type SqlBuilder<T extends BaseEntity = any, R = SQL> = (table: ExtraConfigColumnsFromType<EntityType<T>>) => R;
+
+export type SqlOrBuilder<T extends BaseEntity = any, V = unknown> = SQL<V> | SqlBuilder<T, SQL<V>>;
+
+/**
+ * Builder function type for creating SQL check constraints.
+ * @param table The Drizzle table object.
+ */
+export type CheckBuilder<T extends BaseEntity = BaseEntity> = SqlBuilder<T>;
+
+/**
+ * Builder function type for creating partial index WHERE clauses.
+ * @param table The Drizzle table object.
+ */
+export type WhereBuilder<T extends BaseEntity = BaseEntity> = SqlBuilder<T, Query<T>>;
+
+/**
+ * Reflection data stored for ORM table decorators.
+ */
+export type OrmTableReflectionData<T extends BaseEntity = BaseEntity> = {
+  name?: string,
+  schema?: string,
+  compoundPrimaryKeyName?: string,
+  compoundPrimaryKeyNaming?: NamingStrategy,
+  unique?: UniqueReflectionData[],
+  index?: IndexReflectionData[],
+  paradeIndex?: ParadeIndexReflectionData<T>,
+  checks?: CheckReflectionData[],
+  foreignKeys?: ForeignKeyReflectionData[],
+};
+
+/**
+ * Reflection data stored for ORM column decorators.
+ */
+export type OrmColumnReflectionData = {
+  name?: string,
+  primaryKey?: boolean,
+  unique?: TypedOmit<UniqueReflectionData, 'columns'>,
+  index?: IndexReflectionData,
+  uuid?: { defaultRandom?: boolean },
+  embedded?: { type: AbstractConstructor, prefix?: string | null },
+  references?: { target: () => EntityType, targetColumn?: TargetColumnPath<any> }[],
+  paradeField?: ParadeFieldOptions,
+  tsVector?: TsVectorOptions<any>,
+  encrypted?: boolean,
+  expirationField?: { after: number, mode: 'soft' | 'hard' },
+};
+
+/**
+ * Reflection data for unique constraints.
+ */
+export type UniqueReflectionData = {
+  columns?: string[],
+  options?: {
+    name?: string,
+    naming?: NamingStrategy,
+    nulls?: 'distinct' | 'not distinct',
+  },
+};
+
+/**
+ * Reflection data for index definitions.
+ * @template T The entity type.
+ */
+export type IndexReflectionData<T extends BaseEntity = any> = {
+  columns?: ValueOrProvider<(TargetColumnPath<T> | [TargetColumnPath<T>, 'asc' | 'desc'] | SQL | ExtraConfigColumn)[], ExtraConfigColumnsFromType<EntityType<T>>>,
+  order?: 'asc' | 'desc',
+  options?: IndexOptions<T>,
+};
+
+type CheckReflectionData = {
+  name: string,
+  builder: CheckBuilder,
+  options?: {
+    naming?: NamingStrategy,
+  },
+};
+
+export type ForeignKeyReflectionData = {
+  target: () => EntityType,
+  columns: TargetColumnPath<any>[],
+  foreignColumns: TargetColumnPath<any>[],
+  options?: {
+    name?: string,
+    naming?: NamingStrategy,
+  },
+};
+
+export type IndexOptions<T extends BaseEntity> = {
+  name?: string,
+  naming?: NamingStrategy,
+  using?: IndexMethod,
+  unique?: boolean,
+  where?: WhereBuilder<T>,
+  with?: Record<string, number | string | boolean | SQL>,
+  concurrently?: boolean,
+  nulls?: 'first' | 'last',
+  opclass?: string,
+};
+
+export type ParadeIndexReflectionData<T extends BaseEntity> = Pick<IndexOptions<T>, 'naming' | 'where' | 'concurrently'> & {
+  /**
+   * Columns to include in the Parade index.
+   */
+  columns?: readonly ParadeIndexColumnConfig<T>[],
+
+  /**
+   * Columns to include in the Parade index.
+   */
+  compoundColumns?: readonly ParadeIndexCompoundColumnConfig<T>[],
+
+  /**
+   * Expressions to include in the Parade index based on combined.
+   */
+  expressions?: readonly ParadeIndexExpressionConfig<T>[],
+
+  targetSegmentCount?: number,
+  layerSizes?: string,
+  backgroundLayerSizes?: string,
+  mutableSegmentRows?: number,
+};
+
+export type ParadeTokenizer = 'simple' | 'whitespace' | 'literal' | 'literal_normalized' | 'ngram' | 'regex_pattern' | 'source_code' | 'chinese_compatible' | 'lindera' | 'jieba' | 'icu';
+
+/**
+ * A type-safe object for configuring ParadeDB token filters.
+ */
+export type ParadeTokenizerFilters = {
+  /**
+   * Reduces words to their root form for a given language.
+   * Corresponds to the `stemmer` parameter.
+   */
+  stemmer?: 'arabic' | 'danish' | 'dutch' | 'english' | 'finnish' | 'french' | 'german' | 'greek' | 'hungarian' | 'italian' | 'norwegian' | 'portuguese' | 'romanian' | 'russian' | 'spanish' | 'swedish' | 'tamil' | 'turkish',
+
+  /**
+   * Removes language-specific stopwords from the index.
+   * Corresponds to the `stopwords_language` parameter.
+   */
+  stopwordsLanguage?: 'danish' | 'dutch' | 'english' | 'finnish' | 'french' | 'german' | 'hungarian' | 'italian' | 'norwegian' | 'portuguese' | 'russian' | 'spanish' | 'swedish',
+
+  /**
+   * Strips away diacritical marks (accents, umlauts, etc.).
+   * Corresponds to the `ascii_folding` parameter.
+   */
+  asciiFolding?: boolean,
+
+  /**
+   * Removes any tokens that contain characters that are not ASCII letters or digits.
+   * Corresponds to the `alpha_num_only` parameter.
+   */
+  alphaNumOnly?: boolean,
+
+  /**
+   * Converts all characters to lowercase. Enabled by default. Set to `false` to disable.
+   * Corresponds to the `lowercase` parameter.
+   */
+  lowercase?: boolean,
+
+  /**
+   * Removes tokens that are longer than a certain byte length.
+   * Corresponds to the `remove_long` parameter.
+   */
+  removeLong?: number,
+
+  /**
+   * Removes tokens that are shorter than a certain byte length.
+   * Corresponds to the `remove_short` parameter.
+   */
+  removeShort?: number,
+};
+
+export type ParadeTokenizerConfig = ParadeTokenizer | {
+  /** The type of tokenizer to use. */
+  type: ParadeTokenizer,
+
+  /**
+   * Raw parameters for the tokenizer (e.g., for ngram min/max length).
+   * For common token filters, prefer using the structured `filters` property.
+   */
+  parameters?: (string | number)[],
+
+  /** Type-safe configuration for common token filters. */
+  filters?: ParadeTokenizerFilters,
+};
+
+export type ParadeFieldOptions = {
+  /**
+   * The tokenizer configuration for this field. Can be a simple string (e.g., 'literal')
+   * or a configuration object for advanced settings.
+   */
+  tokenizer?: ParadeTokenizerConfig,
+
+  /**
+   * Provides an alias for this field configuration, allowing the same source column
+   * to be indexed in multiple ways. The aliased field can be queried using
+   * a `$parade` query on the original field, specifying the alias.
+   */
+  alias?: string,
+};
+
+/**
+ * Merges ORM reflection data into the target's metadata.
+ * @param metadata The metadata object for the class or property.
+ * @param data The ORM reflection data to merge.
+ */
+function mergeOrmReflectionData(metadata: TypeMetadata | PropertyMetadata, data: Record): void {
+  const reflectionData = metadata.data.tryGet<Record>('orm') ?? {};
+  const dataEntries = objectEntries(data);
+
+  if (dataEntries.length == 0) {
+    return;
+  }
+
+  for (const [key, value] of dataEntries) {
+    const existingValue = reflectionData[key];
+
+    if (isArray(existingValue)) {
+      reflectionData[key] = [...existingValue, ...(value as any[])];
+    }
+    else {
+      reflectionData[key] = value;
+    }
+  }
+
+  metadata.data.set('orm', reflectionData, true);
+}
+
+/**
+ * Factory function to create a class decorator for ORM table configuration.
+ * Merges provided data with existing ORM reflection data on the class metadata.
+ * @param data The ORM table reflection data to add.
+ */
+export function createTableDecorator<T extends BaseEntity = BaseEntity>(data: OrmTableReflectionData<T> = {}) {
+  return createClassDecorator({
+    handler: (_, metadata) => mergeOrmReflectionData(metadata, data),
+  });
+}
+
+/**
+ * Factory function to create a property decorator for ORM column configuration.
+ * Merges provided data with existing ORM reflection data on the property metadata.
+ * @param data The ORM column reflection data to add.
+ */
+export function createColumnDecorator(data: OrmColumnReflectionData = {}, decoratorOptions?: TypedOmit<SpecificCreateDecoratorOptions<'property'>, 'handler'>) {
+  return createPropertyDecorator({
+    handler: (_, metadata) => mergeOrmReflectionData(metadata, data),
+    ...decoratorOptions,
+  });
+}
+
+/**
+ * Factory function to create a decorator applicable to both classes and properties for ORM configuration.
+ * Merges provided data with existing ORM reflection data on the target's metadata.
+ * @param data The ORM reflection data to add.
+ */
+export function createTableAndColumnDecorator(data?: OrmColumnReflectionData) {
+  return createDecorator({ class: true, property: true, data: { orm: data }, mergeData: true });
+}
+
+/**
+ * Specify ORM column options.
+ * @param options Column configuration options.
+ */
+export function Column(options: OrmColumnReflectionData) {
+  return createColumnDecorator({ ...options });
+}
+
+/**
+ * Mark a property as the primary key column.
+ */
+export function PrimaryKeyProperty() {
+  return createColumnDecorator({ primaryKey: true });
+}
+
+/**
+ * Define a foreign key relationship.
+ * @param type A function returning the referenced entity type.
+ */
+export function References(target: () => EntityType): PropertyDecorator;
+export function References<T extends AnyEntity>(target: () => EntityType<T>, targetColumn?: TargetColumnPath<T>): PropertyDecorator;
+export function References<T extends AnyEntity>(target: () => EntityType<T>, targetColumn?: TargetColumnPath<T>): PropertyDecorator {
+  return createColumnDecorator({ references: [{ target, targetColumn }] });
+}
+
+/**
+ * Define a table check constraint.
+ * @template T The entity type.
+ * @param name The name of the check constraint.
+ * @param builder A function to build the SQL check expression.
+ */
+export function Check<T extends Entity>(name: string, builder: CheckBuilder<T>) {
+  return createTableDecorator({ checks: [{ name, builder }] });
+}
+
+/**
+ * Mark a column for encryption.
+ * The underlying database type will typically be `bytea`.
+ */
+export function EncryptedProperty() {
+  return createColumnDecorator({ encrypted: true });
+}
+
+/**
+ * Embed another class's properties into the current entity's table.
+ * @param type The constructor of the class to embed.
+ * @param options Embedding options, like prefixing column names.
+ */
+export function EmbeddedProperty(type: AbstractConstructor, options?: TypedOmit<NonNullable<OrmColumnReflectionData['embedded']>, 'type'>) {
+  return createPropertyDecorator({
+    include: [Property(type), createColumnDecorator({ embedded: { type, ...options } })],
+  });
+}
+
+export type TableOptions = Partial<Pick<OrmTableReflectionData, 'name' | 'schema'>>;
+
+/**
+ * Specify the database table name and optionally the schema.
+ * @param name The table name.
+ * @param options Additional table options (currently only schema).
+ */
+export function Table(name?: string, options?: TypedOmit<TableOptions, 'schema'>): ClassDecorator;
+
+/**
+ * Specify database table options like name and schema.
+ * @param options Table options including name and schema.
+ */
+export function Table(options?: TableOptions): ClassDecorator;
+export function Table(nameOrOptions?: string | TableOptions, optionsOrNothing?: TableOptions): ClassDecorator {
+  const name = isString(nameOrOptions) ? nameOrOptions : nameOrOptions?.name;
+  const schema = isString(nameOrOptions) ? optionsOrNothing?.schema : nameOrOptions?.schema;
+
+  const data: OrmTableReflectionData | undefined = (isUndefined(name) && isUndefined(schema))
+    ? undefined
+    : filterUndefinedObjectProperties({ name, schema });
+
+  return createTableDecorator(data);
+}
+
+/**
+ * Define a foreign key relationship.
+ * @param target A function returning the referenced entity type.
+ * @param columns The columns in the current entity that form the foreign key.
+ * @param foreignColumns The columns in the referenced entity that the foreign key points to.
+ * @param options Additional foreign key options (e.g., name, naming strategy).
+ * @template TThis The entity type of the current entity.
+ * @template TTarget The entity type of the referenced entity.
+ */
+export function ForeignKey<TThis extends AnyEntity, TTarget extends AnyEntity>(target: () => EntityType<TTarget>, columns: Columns<TThis>, foreignColumns: Columns<TTarget>, options?: ForeignKeyReflectionData['options']): ClassDecorator {
+  return createTableDecorator({ foreignKeys: [{ target, columns, foreignColumns, options }] });
+}
+
+/**
+ * Define a unique constraint on a single column.
+ * @param name Optional name for the unique constraint.
+ * @param options Additional unique constraint options.
+ */
+export function Unique(options?: UniqueReflectionData['options']): PropertyDecorator;
+
+/**
+ * Define a composite unique constraint on multiple columns.
+ * @template T The entity type.
+ * @param columns An array of property names included in the constraint.
+ * @param options Additional unique constraint options.
+ */
+export function Unique<T extends AnyEntity>(columns: Columns<T>, options?: UniqueReflectionData['options']): ClassDecorator;
+export function Unique<T extends AnyEntity>(columnsOrOptions?: Columns<T> | UniqueReflectionData['options'], options?: UniqueReflectionData['options']) {
+  if (isArray(columnsOrOptions)) {
+    return createTableDecorator({ unique: [{ columns: columnsOrOptions, options }] });
+  }
+
+  return createColumnDecorator({ unique: { options: columnsOrOptions } });
+}
+
+/**
+ * Define an index on a single column.
+ * @template T The entity type.
+ * @param name Optional name for the index.
+ * @param options Additional index options (e.g., method, uniqueness, conditions).
+ */
+export function Index<T extends BaseEntity = BaseEntity>(options?: IndexReflectionData<T>['options']): PropertyDecorator;
+
+/**
+ * Define a composite index on multiple columns.
+ * @template T The entity type.
+ * @param columns An array of property names (or tuples with direction) included in the index.
+ * @param options Additional index options.
+ */
+export function Index<T extends BaseEntity>(columns: NonNullable<IndexReflectionData<T>['columns']>, options?: IndexReflectionData<T>['options']): ClassDecorator;
+export function Index<T extends BaseEntity>(columnsOrOptions?: NonNullable<IndexReflectionData<T>['columns']> | IndexReflectionData<T>['options'], options?: IndexReflectionData<T>['options']) {
+  if (isArray(columnsOrOptions) || isFunction(columnsOrOptions)) {
+    return createTableDecorator({ index: [{ columns: columnsOrOptions, options }] });
+  }
+
+  return createColumnDecorator({ index: { options: columnsOrOptions } });
+}
+
+/**
+ * Automatically expire records after a certain time to live (TTL) based on the createTimestamp metadata. Requires extension of {@link Entity} instead of {@link BaseEntity}.
+ * @param ttl Time To Live in milliseconds.
+ * @param mode Whether to delete soft or hard.
+ */
+export function TimeToLive(ttl: number, mode: 'soft' | 'hard'): ClassDecorator {
+  return createClassDecorator({
+    handler: (data) => Expires({ after: ttl, mode })(data.prototype, propertyNameOf<Entity>((entity) => entity.metadata.createTimestamp)),
+  });
+}
+
+/**
+ * Mark a column as an expiration field, automatically deleting records after the specified duration after the column value.
+ * @param options.after Time in milliseconds after which the record expires.
+ * @param options.mode Whether to delete soft or hard.
+ */
+export function Expires(options?: { after?: number, mode?: 'soft' | 'hard' }): PropertyDecorator {
+  return createColumnDecorator({ expirationField: { after: options?.after ?? 0, mode: options?.mode ?? 'soft' } });
+}
+
+/**
+ * Define a trigram index on a text column for similarity searches.
+ * @param options Index options, like the method to use ('gin' or 'gist').
+ */
+export function TrigramIndex(options?: { method?: 'gin' | 'gist', name?: string }): PropertyDecorator {
+  const method = options?.method ?? 'gin';
+
+  return Index({
+    name: options?.name,
+    using: method,
+    opclass: `${method}_trgm_ops`,
+  });
+}
+
+export type TsVectorOptions<T extends BaseEntity> = {
+  /** The source columns to generate the tsvector from. */
+  sources: (TargetColumnPath<T>)[],
+
+  /** The text search configuration language. Defaults to 'simple'. */
+  language?: string | SQL,
+
+  /** Weights for different source columns. */
+  weights?: Partial<Record<TargetColumnPath<T>, 'A' | 'B' | 'C' | 'D'>>,
+
+  /** The index method to use on the generated column. Defaults to 'gin'. */
+  indexMethod?: 'gin' | 'gist',
+};
+
+/**
+ * Defines a `tsvector` column that is automatically generated from other columns.
+ * Also creates a GIN or GiST index on the column for efficient full-text search.
+ * @param options Configuration for the generated tsvector column.
+ */
+export function GeneratedTsVector<T extends BaseEntity>(options: TsVectorOptions<T>): PropertyDecorator {
+  const { indexMethod = 'gin' } = options;
+
+  return createPropertyDecorator({
+    include: [
+      createColumnDecorator({ tsVector: options }),
+      Index({ using: indexMethod }),
+    ],
+  });
+}
+
+/**
+ * Defines a Parade BM25 full-text search index on the entity.
+ * Can be used on a class to define the index and its columns, or on a property to configure a specific field's tokenization.
+ *
+ * @example
+ * // On a class, defining index expressions
+ * @ParadeIndex({
+ *   columns: [
+ *     'description', // simple column
+ *     ['category', { tokenizer: 'literal' }], // column with options
+ *     [sql`(data->>'name')::text`, { tokenizer: 'simple' }] // expression with options
+ *   ]
+ * })
+ *
+ * @example
+ * // On a property, defining field-specific options with type-safe filters
+ * @ParadeIndex({
+ *   tokenizer: {
+ *     type: 'simple',
+ *     filters: {
+ *       stemmer: 'english',
+ *       stopwordsLanguage: 'english'
+ *     }
+ *   }
+ * })
+ * description: string;
+ */
+export function ParadeIndex<T extends BaseEntity>(options: ParadeIndexReflectionData<T>): ClassDecorator;
+export function ParadeIndex(options?: ParadeFieldOptions): PropertyDecorator;
+export function ParadeIndex<T extends BaseEntity>(options?: ParadeIndexReflectionData<T> | ParadeFieldOptions): ClassDecorator | PropertyDecorator {
+  return createDecorator(
+    { class: true, property: true },
+    (data, metadata) => {
+      match(metadata.metadataType)
+        .with('type', () => {
+          const existing = metadata.data.tryGet<OrmTableReflectionData>('orm')?.paradeIndex;
+          const merged = merge(existing, options as ParadeIndexReflectionData<T>);
+          return createTableDecorator<T>({ paradeIndex: merged })(data.constructor);
+        })
+        .with('property', () => createColumnDecorator({ paradeField: (options as ParadeFieldOptions | undefined) ?? {} })(data.prototype, (data as PropertyDecoratorData).propertyKey))
+        .exhaustive();
+    }
+  );
+}
+
+export function ParadeCompoundIndex<T extends BaseEntity>(alias: string, compoundColumns: ParadeIndexCompoundColumnColumnsProvider<T>, options?: TypedOmit<ParadeFieldOptions, 'alias'>): ClassDecorator {
+  return ParadeIndex<T>({ compoundColumns: [[compoundColumns, { alias, tokenizer: 'simple', ...options }]] });
+}
+
+export function ParadeExpressionIndex<T extends BaseEntity>(alias: string, expression: ParadeIndexExpressionProvider<T>, options?: TypedOmit<ParadeFieldOptions, 'alias'>): ClassDecorator {
+  return ParadeIndex<T>({ expressions: [[expression, { alias, tokenizer: 'simple', ...options }]] });
+}

package/source/orm/entity.ts

@@ -0,0 +1,84 @@
+/**
+ * @module
+ * Defines base entity classes and related types for the ORM.
+ */
+import { Defaulted, Integer } from '#/schema/index.js';
+import type { Type } from '#/types/index.js';
+import { EmbeddedProperty, PrimaryKeyProperty } from './decorators.js';
+import { JsonProperty, TimestampProperty, UuidProperty } from './schemas/index.js';
+import type { Embedded, HasDefault, IsPrimaryKey, Json, Timestamp, Uuid } from './types.js';
+
+/**
+ * Represents the type (constructor) of an entity, potentially holding an entity name.
+ * @template T - The entity class type.
+ */
+export interface EntityType<T extends BaseEntity = BaseEntity | Entity> extends Type<T> {
+  readonly entityName?: string;
+}
+
+export type AnyEntity = BaseEntity | Entity;
+
+/**
+ * Base class for extensible metadata attributes associated with an entity.
+ * Allows storing arbitrary key-value pairs.
+ */
+@JsonProperty()
+export abstract class EntityMetadataAttributes { // eslint-disable-line @typescript-eslint/no-extraneous-class
+  [key: string]: unknown;
+}
+
+/**
+ * Base class defining common metadata fields for entities, such as revision tracking and timestamps.
+ */
+export abstract class EntityMetadata {
+  @Integer()
+  revision: number;
+
+  @TimestampProperty()
+  revisionTimestamp: Timestamp;
+
+  @TimestampProperty()
+  createTimestamp: Timestamp;
+
+  @TimestampProperty({ nullable: true })
+  deleteTimestamp: Timestamp | null;
+
+  @Defaulted(EntityMetadataAttributes, {})
+  attributes: HasDefault<Json<EntityMetadataAttributes>>;
+}
+
+/**
+ * Abstract base class for entities that do *not* include the standard metadata fields.
+ * Provides only a default `id` (UUID primary key). Useful for simpler tables or join tables.
+ */
+export abstract class BaseEntity {
+  @PrimaryKeyProperty()
+  @UuidProperty({ defaultRandom: true })
+  id: IsPrimaryKey<HasDefault<Uuid>>;
+}
+
+/**
+ * Abstract base class for entities that include standard metadata.
+ * Provides a default `id` (UUID primary key) and an `metadata` field.
+ */
+export abstract class Entity extends BaseEntity {
+  @EmbeddedProperty(EntityMetadata, { prefix: null })
+  metadata: Embedded<EntityMetadata>;
+}
+
+export abstract class TenantEntity extends Entity {
+  @UuidProperty()
+  tenantId: Uuid;
+}
+
+export abstract class TenantBaseEntity extends BaseEntity {
+  @UuidProperty()
+  tenantId: Uuid;
+}
+
+export {
+  /**
+   * @deprecated Use BaseEntity instead.
+   */
+  BaseEntity as EntityWithoutMetadata
+};

package/source/orm/index.ts

@@ -0,0 +1,13 @@
+/**
+ * {@include ./README.md}
+ *
+ * @module ORM
+ */
+export * from './decorators.js';
+export * from './entity.js';
+export * from './query/index.js';
+export * from './repository.types.js';
+export * from './schemas/index.js';
+export * from './sqls.js';
+export * from './types.js';
+export * from './utils.js';