@tstdl/base 0.92.124 → 0.92.126

package/orm/query.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @module
+ * Defines types for constructing database queries using a MongoDB-like syntax.
+ * Supports logical operators, comparison operators, and specialized queries like text search and geospatial queries.
+ */
+import type { SQLWrapper } from 'drizzle-orm';
+import type { Flatten, Record } from '../types.js';
+import type { Geometry } from '../types/geo-json.js';
+import type { UntaggedDeep } from '../types/tagged.js';
+/** Represents a logical query combining multiple sub-queries (e.g., $and, $or, $nor). */
+export type LogicalQuery<T = any> = LogicalAndQuery<T> | LogicalOrQuery<T> | LogicalNorQuery<T>;
+/** Union of keys representing logical query operators ('$and', '$or', '$nor'). */
+export type LogicalQueryTypes = keyof (LogicalAndQuery & LogicalOrQuery & LogicalNorQuery);
+/** Array containing all valid logical query operator keys. */
+export declare const allLogicalQueryTypes: LogicalQueryTypes[];
+/** Represents the body of a comparison query, mapping field paths to comparison operators or values. Allows nested structures. */
+export type ComparisonQueryBody<T = any> = {
+    [P in keyof T]?: T[P] extends Record ? ComparisonQueryBody<T[P]> : ComparisonQueryOrValue<T[P]>;
+} & Record<ComparisonQueryOrValue>;
+/** Represents either a full comparison query object or a direct value for equality comparison. */
+export type ComparisonQueryOrValue<T = any> = ComparisonQuery<T> | ComparisonValue<T>;
+/** Represents a comparison query using various operators like $eq, $ne, $gt, $in, etc. */
+export type ComparisonQuery<T = any> = Partial<ComparisonNotQuery<T> & ComparisonEqualsQuery<T> & ComparisonNotEqualsQuery<T> & ComparisonExistsQuery & ComparisonItemQuery<T> & ComparisonInQuery<T> & ComparisonNotInQuery<T> & ComparisonAllQuery<T> & ComparisonGreaterThanQuery<T> & ComparisonGreaterThanOrEqualsQuery<T> & ComparisonLessThanQuery<T> & ComparisonLessThanOrEqualsQuery<T> & ComparisonRegexQuery & ComparisonTextQuery & ComparisonGeoShapeQuery & ComparisonGeoDistanceQuery>;
+/** Union of keys representing comparison query operators. */
+export type ComparisonQueryTypes = keyof ComparisonQuery;
+/** Array containing all valid comparison query operator keys. */
+export declare const allComparisonQueryTypes: ComparisonQueryTypes[];
+/** Represents specialized query types beyond simple comparisons (e.g., $textSpan). */
+export type SpecialQuery<T = any> = Partial<TextSpanQuery<T>>;
+/** Union of keys representing special query operators. */
+export type SpecialQueryTypes = keyof SpecialQuery;
+/** Array containing all valid special query operator keys. */
+export declare const allSpecialQueryTypes: SpecialQueryTypes[];
+/**
+ * Represents a complete query, which can be either a raw Drizzle SQLWrapper
+ * or a structured query object using logical and comparison operators.
+ * @template T - The type of the entity being queried.
+ */
+export type Query<T = any> = SQLWrapper | QueryObject<UntaggedDeep<T>>;
+/** Represents a structured query object, combining logical, comparison, and special queries. */
+export type QueryObject<T> = LogicalQuery<T> | (ComparisonQueryBody<T> & SpecialQuery<T>);
+/** Union of all possible query operator keys (logical, comparison, special). */
+export type QueryTypes = LogicalQueryTypes | ComparisonQueryTypes | SpecialQueryTypes;
+/** Array containing all valid query operator keys. */
+export declare const allQueryTypes: ("$and" | "$or" | "$nor" | "$not" | "$eq" | "$neq" | "$exists" | "$item" | "$in" | "$nin" | "$all" | "$gt" | "$gte" | "$lt" | "$lte" | "$regex" | "$text" | "$geoShape" | "$geoDistance" | "$textSpan")[];
+/** Logical operators used within certain query types like $text. */
+export type Operator = 'and' | 'or';
+/** Array containing all valid logical operators ('and', 'or'). */
+export declare const allOperators: Operator[];
+/** Represents an AND logical query. All sub-queries must be true. */
+export type LogicalAndQuery<T = any> = {
+    $and: readonly Query<T>[];
+};
+/** Represents an OR logical query. At least one sub-query must be true. */
+export type LogicalOrQuery<T = any> = {
+    $or: readonly Query<T>[];
+};
+/** Represents a NOR logical query. All sub-queries must be false. */
+export type LogicalNorQuery<T = any> = {
+    $nor: readonly Query<T>[];
+};
+/** Represents a value used in comparisons, can be a direct value, a flattened value, or a Drizzle SQLWrapper. */
+export type ComparisonValue<T> = T | Flatten<T> | SQLWrapper;
+/** Represents a comparison value that can also include a RegExp for string comparisons. */
+export type ComparisonValueWithRegex<T> = T extends string ? ComparisonValue<T | RegExp> : T extends readonly string[] ? ComparisonValue<readonly (Flatten<T> | RegExp)[]> : (T | Flatten<T>);
+/** Represents a NOT comparison query. Inverts the result of the nested comparison. */
+export type ComparisonNotQuery<T = any> = {
+    $not: ComparisonQuery<T>;
+};
+/** Represents an equality comparison query ($eq). */
+export type ComparisonEqualsQuery<T = any> = {
+    $eq: ComparisonValueWithRegex<T>;
+};
+/** Represents a non-equality comparison query ($neq). */
+export type ComparisonNotEqualsQuery<T = any> = {
+    $neq: ComparisonValueWithRegex<T>;
+};
+/** Represents an existence check query ($exists). Checks if a field exists (or not). */
+export type ComparisonExistsQuery = {
+    $exists: ComparisonValue<boolean>;
+};
+/** Represents a query targeting elements within an array field ($item). */
+export type ComparisonItemQuery<T = any> = {
+    $item: T extends readonly (infer U)[] ? U extends Record ? Query<U> : ComparisonQuery<U> : never;
+};
+/** Represents an "in list" comparison query ($in). Checks if a field value is within a specified array. */
+export type ComparisonInQuery<T = any> = {
+    $in: readonly ComparisonValueWithRegex<T>[];
+};
+/** Represents a "not in list" comparison query ($nin). Checks if a field value is not within a specified array. */
+export type ComparisonNotInQuery<T = any> = {
+    $nin: readonly ComparisonValueWithRegex<T>[];
+};
+/** Represents an "all elements match" query ($all). Checks if an array field contains all specified values. */
+export type ComparisonAllQuery<T = any> = {
+    $all: readonly ComparisonValueWithRegex<T>[];
+};
+/** Represents a "greater than" comparison query ($gt). */
+export type ComparisonGreaterThanQuery<T = any> = {
+    $gt: ComparisonValue<T>;
+};
+/** Represents a "greater than or equals" comparison query ($gte). */
+export type ComparisonGreaterThanOrEqualsQuery<T = any> = {
+    $gte: ComparisonValue<T>;
+};
+/** Represents a "less than" comparison query ($lt). */
+export type ComparisonLessThanQuery<T = any> = {
+    $lt: ComparisonValue<T>;
+};
+/** Represents a "less than or equals" comparison query ($lte). */
+export type ComparisonLessThanOrEqualsQuery<T = any> = {
+    $lte: ComparisonValue<T>;
+};
+/** Represents a regular expression comparison query ($regex). */
+export type ComparisonRegexQuery = {
+    $regex: string | RegExp | {
+        pattern: string;
+        flags: string;
+    };
+};
+/** Represents a full-text search query ($text). */
+export type ComparisonTextQuery = {
+    $text: string | {
+        text: string;
+        operator?: Operator;
+    };
+};
+/** Defines the possible spatial relationships for geospatial shape queries. */
+export type GeoShapeRelation = 'intersects' | 'within' | 'disjoint' | 'contains';
+/** Represents a geospatial query based on shape relationships ($geoShape). */
+export type ComparisonGeoShapeQuery = {
+    $geoShape: {
+        geometry: Geometry;
+        relation: GeoShapeRelation;
+    };
+};
+/** Represents a geospatial query based on distance from a point ($geoDistance). */
+export type ComparisonGeoDistanceQuery = {
+    $geoDistance: {
+        longitude: number;
+        latitude: number;
+        /**
+         * Maximum distance in meters
+         */
+        maxDistance?: number;
+        /**
+         * Minimum distance in meters
+         */
+        minDistance?: number;
+    };
+};
+/** Defines the modes for text span queries, affecting how multiple field matches are handled. */
+export type TextSpanQueryMode = 'best' | 'most' | 'cross';
+/** Array containing all valid text span query modes. */
+export declare const allTextSpanQueryModes: TextSpanQueryMode[];
+/** Represents a text span query ($textSpan), searching for text across multiple fields. */
+export type TextSpanQuery<T = any> = {
+    $textSpan: {
+        fields: readonly (Extract<keyof T, string>)[];
+        text: string;
+        mode?: TextSpanQueryMode;
+        operator?: Operator;
+    };
+};

package/orm/repository.types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @module
+ * Defines types used by ORM repositories for operations like loading, updating, and creating entities.
+ * Includes types for ordering, loading options, and entity data structures for create/update operations.
+ */
+import type { Paths, Record, TypedOmit } from '../types.js';
+import type { UntaggedDeep } from '../types/tagged.js';
+import type { SQL, SQLWrapper } from 'drizzle-orm';
+import type { PartialDeep } from 'type-fest';
+import type { Entity, EntityMetadata, EntityWithoutMetadata } from './entity.js';
+type WithSql<T> = {
+    [P in keyof T]: T[P] extends Record ? WithSql<T[P]> : (T[P] | SQL);
+};
+/**
+ * Specifies the target column (e.g. for ordering, distinct on), which can be a property path within the entity
+ * or a raw Drizzle SQLWrapper for a complex target.
+ * @template T - The entity type.
+ */
+export type TargetColumnPaths<T extends EntityWithoutMetadata> = Paths<UntaggedDeep<T>>;
+/**
+ * Specifies the target column (e.g. for ordering, distinct on), which can be a property path within the entity
+ * or a raw Drizzle SQLWrapper for a complex target.
+ * @template T - The entity type.
+ */
+export type TargetColumn<T extends EntityWithoutMetadata> = TargetColumnPaths<T> | SQLWrapper;
+/** Specifies the direction for ordering results ('asc' or 'desc'). */
+export type OrderDirection = 'asc' | 'desc';
+/**
+ * Defines how results should be ordered. Can be a single target, an array of targets
+ * (optionally with direction), or an object mapping property paths to directions.
+ * @template T - The entity type.
+ */
+export type Order<T extends EntityWithoutMetadata> = TargetColumn<T> | (TargetColumn<T> | [TargetColumn<T>, OrderDirection])[] | Partial<Record<Exclude<TargetColumn<T>, SQLWrapper>, OrderDirection>>;
+/**
+ * Options object containing ordering configuration.
+ * @template T - The entity type.
+ */
+export type OrderOptions<T extends EntityWithoutMetadata> = {
+    order?: Order<T>;
+};
+/**
+ * Options for loading a single entity, including ordering and offset.
+ * @template T - The entity type.
+ */
+export type LoadOptions<T extends EntityWithoutMetadata> = OrderOptions<T> & {
+    offset?: number;
+};
+/**
+ * Options for loading multiple entities, including ordering, offset, and limit.
+ * @template T - The entity type.
+ */
+export type LoadManyOptions<T extends EntityWithoutMetadata> = LoadOptions<T> & {
+    limit?: number;
+    distinct?: boolean | TargetColumn<T>[];
+};
+/**
+ * Options for update operations (currently inherits from LoadOptions, primarily for ordering).
+ * @template T - The entity type.
+ */
+export type UpdateOptions<T extends EntityWithoutMetadata> = LoadOptions<T>;
+/** Type definition for updating entity metadata attributes, allowing partial updates and SQL expressions. */
+export type EntityMetadataUpdate = WithSql<Partial<UntaggedDeep<Pick<EntityMetadata, 'attributes'>>>>;
+/**
+ * Represents the data structure for creating a new entity.
+ * Excludes 'id' and 'metadata' by default, but allows providing an optional 'id' and partial 'metadata.attributes'.
+ * Allows SQL expressions for values.
+ * @template T - The entity type.
+ */
+export type NewEntity<T extends Entity | EntityWithoutMetadata> = T extends Entity ? WithSql<UntaggedDeep<TypedOmit<T, 'id' | 'metadata'> & {
+    id?: string;
+    metadata?: Partial<Pick<EntityMetadata, 'attributes'>>;
+}>> : WithSql<UntaggedDeep<TypedOmit<T, 'id'> & {
+    id?: string;
+}>>;
+/**
+ * Represents the data structure for updating an existing entity.
+ * Allows partial updates for all properties (using PartialDeep) and specific updates for 'metadata.attributes'.
+ * Allows SQL expressions for values.
+ * @template T - The entity type.
+ */
+export type EntityUpdate<T extends EntityWithoutMetadata> = T extends Entity ? WithSql<PartialDeep<UntaggedDeep<TypedOmit<T, 'metadata'>>>> & {
+    metadata?: EntityMetadataUpdate;
+} : WithSql<PartialDeep<UntaggedDeep<T>>>;
+export {};

package/orm/schemas/json.d.ts

@@ -0,0 +1,9 @@
+import { type Decorator } from '../../reflection/index.js';
+import { ObjectSchema, type ObjectSchemaOptions, type SchemaDecoratorOptions } from '../../schema/index.js';
+export type JsonSchemaOptions = Pick<ObjectSchemaOptions, 'factory'>;
+export declare class JsonSchema extends ObjectSchema {
+    readonly name = "Json";
+    constructor(options?: JsonSchemaOptions);
+}
+export declare function json(options?: JsonSchemaOptions): JsonSchema;
+export declare function Json(options?: JsonSchemaOptions & SchemaDecoratorOptions): Decorator<'class' | 'property' | 'accessor'>;

package/orm/schemas/numeric-date.d.ts

@@ -0,0 +1,8 @@
+import { NumberSchema, type NumberSchemaOptions, type SchemaPropertyDecorator, type SchemaDecoratorOptions, type SimpleSchemaOptions } from '../../schema/index.js';
+export type NumericDateSchemaOptions = SimpleSchemaOptions<number> & Pick<NumberSchemaOptions, 'minimum' | 'maximum'>;
+export declare class NumericDateSchema extends NumberSchema {
+    readonly name = "NumericDate";
+    constructor(options?: NumericDateSchemaOptions);
+}
+export declare function numericDate(options?: NumericDateSchemaOptions): NumericDateSchema;
+export declare function NumericDate(options?: NumericDateSchemaOptions & SchemaDecoratorOptions): SchemaPropertyDecorator;

package/orm/schemas/timestamp.d.ts

@@ -0,0 +1,10 @@
+import type { JsonPath } from '../../json-path/json-path.js';
+import { NumberSchema, type NumberSchemaOptions, type SchemaPropertyDecorator, type SchemaDecoratorOptions, type SchemaTestOptions, type SchemaTestResult, type SimpleSchemaOptions } from '../../schema/index.js';
+export type TimestampSchemaOptions = SimpleSchemaOptions<number> & Pick<NumberSchemaOptions, 'minimum' | 'maximum'>;
+export declare class TimestampSchema extends NumberSchema {
+    readonly name = "Timestamp";
+    constructor(options?: TimestampSchemaOptions);
+    _test(value: any, path: JsonPath, options: SchemaTestOptions): SchemaTestResult<number>;
+}
+export declare function timestamp(options?: TimestampSchemaOptions): TimestampSchema;
+export declare function Timestamp(options?: TimestampSchemaOptions & SchemaDecoratorOptions): SchemaPropertyDecorator;

package/orm/schemas/uuid.d.ts

@@ -0,0 +1,11 @@
+import { StringSchema, type SchemaPropertyDecorator, type SchemaDecoratorOptions } from '../../schema/index.js';
+export type UuidSchemaOptions = {
+    defaultRandom?: boolean;
+};
+export declare class UuidSchema extends StringSchema {
+    readonly name = "uuid";
+    readonly defaultRandom: boolean;
+    constructor(options?: UuidSchemaOptions);
+}
+export declare function uuid(options?: UuidSchemaOptions): UuidSchema;
+export declare function Uuid(options?: UuidSchemaOptions & SchemaDecoratorOptions): SchemaPropertyDecorator;

package/orm/server/database-schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module
+ * Provides utilities for defining and accessing database schemas, tables, and enums
+ * within a specific PostgreSQL schema.
+ */
+import type { PgEnum } from 'drizzle-orm/pg-core';
+import type { Enumeration, EnumerationValue, UnionToTuple } from '../../types.js';
+import type { EntityType } from '../entity.js';
+import type { PgTableFromType } from './types.js';
+/**
+ * Represents a database schema, providing methods to access tables and enums within that schema.
+ * @template SchemaName The name of the PostgreSQL schema.
+ */
+export declare class DatabaseSchema<SchemaName extends string> {
+    /** The name of the PostgreSQL schema. */
+    readonly name: SchemaName;
+    /**
+     * Creates an instance of DatabaseSchema.
+     * @param name The name of the PostgreSQL schema.
+     */
+    constructor(name: SchemaName);
+    /**
+     * Gets the Drizzle table object corresponding to the given entity type within this schema.
+     * @template T The entity type.
+     * @param type The entity class.
+     * @returns The Drizzle table object.
+     */
+    getTable<T extends EntityType>(type: T): PgTableFromType<T, SchemaName>;
+    /**
+     * Gets the Drizzle enum object corresponding to the given enumeration within this schema.
+     * If a name is provided, it registers the enum with that name first.
+     * @template T The enumeration type.
+     * @param enumeration The enumeration object.
+     * @param name Optional name to register the enum with.
+     * @returns The Drizzle enum object.
+     */
+    getEnum<T extends Enumeration>(enumeration: T, name?: string): PgEnum<UnionToTuple<`${EnumerationValue<T>}`> extends [string, ...string[]] ? UnionToTuple<`${EnumerationValue<T>}`> : never>;
+}
+/**
+ * Factory function to create a DatabaseSchema instance.
+ * @template Name The name of the PostgreSQL schema.
+ * @param name The name of the PostgreSQL schema.
+ * @returns A new DatabaseSchema instance.
+ */
+export declare function databaseSchema<Name extends string>(name: Name): DatabaseSchema<Name>;

package/orm/server/database.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module
+ * Provides the core database connection and migration functionality using Drizzle ORM and node-postgres.
+ * It sets up the dependency injection for the database instance.
+ */
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { type PoolConfig } from 'pg';
+import type { Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
+/**
+ * Type alias for the argument required to resolve a Database instance via the injector.
+ * Represents the PostgreSQL pool configuration.
+ */
+export type DatabaseArgument = PoolConfig;
+/**
+ * Represents the application's database connection.
+ * Extends Drizzle's `NodePgDatabase` and integrates with the dependency injection system.
+ * Can be resolved using a `PoolConfig` argument.
+ */
+export declare class Database extends NodePgDatabase<any> implements Resolvable<DatabaseArgument> {
+    readonly [resolveArgumentType]?: DatabaseArgument;
+}
+/**
+ * Re-exports the `migrate` function from `drizzle-orm/node-postgres/migrator`
+ * for running database migrations.
+ */
+export { migrate };

package/orm/server/drizzle/schema-converter.d.ts

@@ -0,0 +1,15 @@
+import { type PgEnum, type PgSchema, type PgTableWithColumns } from 'drizzle-orm/pg-core';
+import type { AbstractConstructor, Enumeration } from '../../../types.js';
+import type { EntityType } from '../../entity.js';
+import type { ColumnDefinition, ColumnDefinitionsMap, PgTableFromType } from '../types.js';
+type ConverterContext = {
+    type: AbstractConstructor;
+    property: string;
+};
+export declare const getDrizzleTableFromType: typeof _getDrizzleTableFromType;
+export declare function getColumnDefinitions(table: PgTableWithColumns<any>): ColumnDefinition[];
+export declare function getColumnDefinitionsMap(table: PgTableWithColumns<any>): ColumnDefinitionsMap;
+export declare function _getDrizzleTableFromType<T extends EntityType, S extends string>(type: T, fallbackSchemaName?: S): PgTableFromType<T, S>;
+export declare function registerEnum(enumeration: Enumeration, name: string): void;
+export declare function getPgEnum(schema: string | PgSchema, enumeration: Enumeration, context?: ConverterContext): PgEnum<[string, ...string[]]>;
+export {};