@uql/core 3.1.0 → 3.1.2

package/src/type/query.ts

@@ -1,506 +0,0 @@
-import type { FieldKey, IdValue, Key, RelationKey } from './entity.js';
-import type { BooleanLike, ExpandScalar, Scalar, Type, Unpacked } from './utility.js';
-
-export type QueryOptions = {
-  /**
-   * use or omit `softDelete` attribute.
-   */
-  softDelete?: boolean;
-  /**
-   * prefix the query with this.
-   */
-  prefix?: string;
-  /**
-   * automatically infer the prefix for the query.
-   */
-  autoPrefix?: boolean;
-};
-
-export type QuerySelectOptions = {
-  /**
-   * prefix the query with this.
-   */
-  prefix?: string;
-  /**
-   * automatically add the prefix for the alias.
-   */
-  autoPrefixAlias?: boolean;
-};
-
-/**
- * query selection as an array.
- */
-export type QuerySelectArray<E> = (Key<E> | QueryRaw)[];
-
-/**
- * query selection as a map.
- */
-export type QuerySelectMap<E> = QuerySelectFieldMap<E> | QuerySelectRelationMap<E>;
-
-/**
- * query selection.
- */
-export type QuerySelect<E> = QuerySelectArray<E> | QuerySelectMap<E>;
-
-/**
- * query selection of fields as a map.
- */
-export type QuerySelectFieldMap<E> = {
-  [K in FieldKey<E>]?: BooleanLike;
-};
-
-/**
- * query conflict paths map.
- */
-export type QueryConflictPathsMap<E> = {
-  [K in FieldKey<E>]?: true;
-};
-
-/**
- * query conflict paths.
- */
-export type QueryConflictPaths<E> = QueryConflictPathsMap<E>;
-
-/**
- * query selection of relations as a map.
- */
-export type QuerySelectRelationMap<E> = {
-  [K in RelationKey<E>]?: BooleanLike | Key<Unpacked<E[K]>>[] | QuerySelectRelationOptions<E[K]>;
-};
-
-/**
- * options to select a relation.
- */
-export type QuerySelectRelationOptions<E> = (E extends unknown[] ? Query<Unpacked<E>> : QueryUnique<Unpacked<E>>) & {
-  $required?: boolean;
-};
-
-/**
- * options for full-text-search operator.
- */
-export type QueryTextSearchOptions<E> = {
-  /**
-   * text to search for.
-   */
-  $value: string;
-  /**
-   * list of fields to search on.
-   */
-  $fields?: FieldKey<E>[];
-};
-
-/**
- * comparison by fields.
- */
-export type QueryWhereFieldMap<E> = { [K in FieldKey<E>]?: QueryWhereFieldValue<E[K]> };
-
-/**
- * complex operators.
- */
-export type QueryWhereMap<E> = QueryWhereFieldMap<E> & QueryWhereRootOperator<E>;
-
-export type QueryWhereRootOperator<E> = {
-  /**
-   * joins query clauses with a logical `AND`, returns records that match all the clauses.
-   */
-  $and?: QueryWhereArray<E>;
-  /**
-   * joins query clauses with a logical `OR`, returns records that match any of the clauses.
-   */
-  $or?: QueryWhereArray<E>;
-  /**
-   * joins query clauses with a logical `AND`, returns records that do not match all the clauses.
-   */
-  $not?: QueryWhereArray<E>;
-  /**
-   * joins query clauses with a logical `OR`, returns records that do not match any of the clauses.
-   */
-  $nor?: QueryWhereArray<E>;
-  /**
-   * whether the specified fields match against a full-text search of the given string.
-   */
-  $text?: QueryTextSearchOptions<E>;
-  /**
-   * whether the record exists in the given sub-query.
-   */
-  $exists?: QueryRaw;
-  /**
-   * whether the record does not exists in the given sub-query.
-   */
-  $nexists?: QueryRaw;
-};
-
-export type QueryWhereFieldOperatorMap<T> = {
-  /**
-   * whether a value is equal to the given value.
-   */
-  $eq?: ExpandScalar<T>;
-  /**
-   * whether a value is not equal to the given value.
-   */
-  $ne?: ExpandScalar<T>;
-  /**
-   * negates the given comparison.
-   */
-  $not?: QueryWhereFieldValue<T>;
-  /**
-   * whether a value is less than the given value.
-   */
-  $lt?: ExpandScalar<T>;
-  /**
-   * whether a value is less than or equal to the given value.
-   */
-  $lte?: ExpandScalar<T>;
-  /**
-   * whether a value is greater than the given value.
-   */
-  $gt?: ExpandScalar<T>;
-  /**
-   * whether a value is greater than or equal to the given value.
-   */
-  $gte?: ExpandScalar<T>;
-  /**
-   * whether a string begins with the given string (case sensitive).
-   */
-  $startsWith?: string;
-  /**
-   * whether a string begins with the given string (case insensitive).
-   */
-  $istartsWith?: string;
-  /**
-   * whether a string ends with the given string (case sensitive).
-   */
-  $endsWith?: string;
-  /**
-   * whether a string ends with the given string (case insensitive).
-   */
-  $iendsWith?: string;
-  /**
-   * whether a string is contained within the given string (case sensitive).
-   */
-  $includes?: string;
-  /**
-   * whether a string is contained within the given string (case insensitive).
-   */
-  $iincludes?: string;
-  /**
-   * whether a string fulfills the given pattern (case sensitive).
-   */
-  $like?: string;
-  /**
-   * whether a string fulfills the given pattern (case insensitive).
-   */
-  $ilike?: string;
-  /**
-   * whether a string matches the given regular expression.
-   */
-  $regex?: string;
-  /**
-   * whether a value matches any of the given values.
-   */
-  $in?: ExpandScalar<T>[];
-  /**
-   * whether a value does not match any of the given values.
-   */
-  $nin?: ExpandScalar<T>[];
-};
-
-/**
- * Value for a field comparison.
- */
-export type QueryWhereFieldValue<T> = T | T[] | QueryWhereFieldOperatorMap<T> | QueryRaw;
-
-/**
- * query single filter.
- */
-export type QueryWhereSingle<E> = IdValue<E> | IdValue<E>[] | QueryWhereMap<E> | QueryRaw;
-
-/**
- * query filter array.
- */
-export type QueryWhereArray<E> = QueryWhereSingle<E>[];
-
-/**
- * query filter.
- */
-export type QueryWhere<E> = QueryWhereSingle<E> | QueryWhereArray<E>;
-
-/**
- * direction for the sort.
- */
-export type QuerySortDirection = -1 | 1 | 'asc' | 'desc';
-
-/**
- * sort by tuples
- */
-export type QuerySortTuples<E> = [FieldKey<E>, QuerySortDirection][];
-
-/**
- * sort by objects.
- */
-export type QuerySortObjects<E> = { field: FieldKey<E>; sort: QuerySortDirection }[];
-
-/**
- * sort by fields.
- */
-export type QuerySortFieldMap<E> = {
-  [K in FieldKey<E>]?: QuerySortDirection;
-};
-
-/**
- * sort by relations fields.
- */
-export type QuerySortRelationMap<E> = {
-  [K in RelationKey<E>]?: QuerySortMap<Unpacked<E[K]>>;
-};
-
-/**
- * sort by map.
- */
-export type QuerySortMap<E> = QuerySortFieldMap<E> | QuerySortRelationMap<E>;
-
-/**
- * sort options.
- */
-export type QuerySort<E> = QuerySortMap<E> | QuerySortTuples<E> | QuerySortObjects<E>;
-
-/**
- * pager options.
- */
-export type QueryPager = {
-  /**
-   * Index from where start the search
-   */
-  $skip?: number;
-
-  /**
-   * Max number of records to retrieve
-   */
-  $limit?: number;
-};
-
-/**
- * search options.
- */
-export type QuerySearch<E> = {
-  /**
-   * filtering options.
-   */
-  $where?: QueryWhere<E>;
-
-  /**
-   * sorting options.
-   */
-  $sort?: QuerySort<E>;
-} & QueryPager;
-
-/**
- * criteria one options.
- */
-export type QuerySearchOne<E> = Omit<QuerySearch<E>, '$limit'>;
-
-/**
- * query options.
- */
-export type Query<E> = {
-  /**
-   * selection options.
-   */
-  $select?: QuerySelect<E>;
-} & QuerySearch<E>;
-
-/**
- * options to get a single record.
- */
-export type QueryOne<E> = Omit<Query<E>, '$limit'>;
-
-/**
- * options to get an unique record.
- */
-export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$where'>;
-
-/**
- * stringified query.
- */
-export type QueryStringified = {
-  [K in keyof Query<unknown>]?: string;
-};
-
-/**
- * result of an update operation.
- */
-export type QueryUpdateResult = {
-  /**
-   * number of affected records.
-   */
-  changes?: number;
-  /**
-   * the inserted IDs.
-   */
-  ids?: number[] | string[];
-  /**
-   * first inserted ID.
-   */
-  firstId?: number | string;
-};
-
-/**
- * options for the `raw` function.
- */
-export type QueryRawFnOptions = {
-  /**
-   * the current dialect.
-   */
-  dialect?: QueryDialect;
-  /**
-   * the prefix.
-   */
-  prefix?: string;
-  /**
-   * the escaped prefix.
-   */
-  escapedPrefix?: string;
-  /**
-   * the query context.
-   */
-  ctx?: QueryContext;
-};
-
-/**
- * a `raw` function
- */
-export type QueryRawFn = (opts?: QueryRawFnOptions) => void | Scalar;
-
-export class QueryRaw {
-  constructor(
-    readonly value: Scalar | QueryRawFn,
-    readonly alias?: string,
-  ) {}
-}
-
-/**
- * comparison options.
- */
-export type QueryComparisonOptions = QueryOptions & {
-  /**
-   * use precedence for the comparison or not.
-   */
-  usePrecedence?: boolean;
-};
-
-/**
- * query filter options.
- */
-export type QueryWhereOptions = QueryComparisonOptions & {
-  /**
-   * clause to be used in the filter.
-   */
-  clause?: 'WHERE' | false;
-};
-
-export interface QueryContext {
-  append(sql: string): this;
-  addValue(value: unknown): this;
-  pushValue(value: unknown): this;
-  readonly sql: string;
-  readonly values: unknown[];
-}
-
-export interface QueryDialect {
-  /**
-   * obtains the records matching the given search parameters.
-   * @param ctx the query context
-   * @param entity the target entity
-   * @param q the criteria options
-   * @param opts the query options
-   */
-  find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
-
-  /**
-   * counts the number of records matching the given search parameters.
-   * @param ctx the query context
-   * @param entity the target entity
-   * @param q the criteria options
-   * @param opts the query options
-   */
-  count<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
-
-  /**
-   * insert records.
-   * @param ctx the query context
-   * @param entity the target entity
-   * @param payload the payload
-   * @param opts the query options
-   */
-  insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
-
-  /**
-   * update records.
-   * @param ctx the query context
-   * @param entity the target entity
-   * @param q the criteria options
-   * @param payload
-   * @param opts the query options
-   */
-  update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: E, opts?: QueryOptions): void;
-
-  /**
-   * upsert records.
-   * @param ctx the query context
-   * @param entity the target entity
-   * @param conflictPaths the conflict paths
-   * @param payload
-   */
-  upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): void;
-
-  /**
-   * delete records.
-   * @param ctx the query context
-   * @param entity the target entity
-   * @param q the criteria options
-   * @param opts the query options
-   */
-  delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
-
-  /**
-   * escape an identifier.
-   * @param val the value to be escaped
-   * @param forbidQualified don't escape dots
-   * @param addDot use a dot as suffix
-   */
-  escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
-
-  /**
-   * escape a value.
-   * @param val the value to escape
-   */
-  escape(val: unknown): string;
-
-  /**
-   * add a value to the query.
-   * @param values the values array
-   * @param value the value to add
-   */
-  addValue(values: unknown[], value: unknown): string;
-
-  /**
-   * create a new query context.
-   */
-  createContext(): QueryContext;
-}
-
-/**
- * Minimal dialect interface exposing escapeIdChar for SQL operations
- */
-export interface SqlQueryDialect extends QueryDialect {
-  /**
-   * the escape character for identifiers.
-   */
-  readonly escapeIdChar: '"' | '`';
-
-  /**
-   * Get the placeholder for a parameter at the given index (1-based).
-   * Default: '?' for MySQL/MariaDB/SQLite, '$n' for PostgreSQL.
-   */
-  placeholder(index: number): string;
-}

package/src/type/repository.ts

@@ -1,142 +0,0 @@
-import type { IdValue } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
-import type { UniversalQuerier } from './universalQuerier.js';
-import type { Type } from './utility.js';
-
-/**
- * A `repository` allows to interact with the datasource to perform persistence operations on a specific entity.
- */
-export type UniversalRepository<E> = {
-  /**
-   * the `entity` class to which this `repository` is linked to.
-   */
-  readonly entity: Type<E>;
-
-  /**
-   * the `querier` instance to which this `repository` is linked to.
-   */
-  readonly querier: UniversalQuerier;
-
-  /**
-   * obtains the record with the given primary key.
-   * @param id the primary key value
-   * @param q the criteria options
-   */
-  findOneById(id: IdValue<E>, q?: QueryOne<E>): Promise<unknown>;
-
-  /**
-   * obtains the first record matching the given search parameters.
-   * @param q the criteria options
-   */
-  findOne(q: QueryOne<E>): Promise<unknown>;
-
-  /**
-   * obtains the records matching the given search parameters.
-   * @param q the criteria options
-   */
-  findMany(q: Query<E>): Promise<unknown>;
-
-  /**
-   * obtains the records matching the given search parameters,
-   * also counts the number of matches ignoring pagination.
-   * @param q the criteria options
-   */
-  findManyAndCount(q: Query<E>): Promise<unknown>;
-
-  /**
-   * counts the number of records matching the given search parameters.
-   * @param q the search options
-   */
-  count(q: QuerySearch<E>): Promise<unknown>;
-
-  /**
-   * inserts a record.
-   * @param payload the data to be persisted
-   */
-  insertOne(payload: E): Promise<unknown>;
-
-  /**
-   * Inserts many records.
-   * @param entity the entity to persist on
-   * @param payload the data to be persisted
-   */
-  insertMany?(payload: E[]): Promise<unknown>;
-
-  /**
-   * updates a record partially.
-   * @param id the primary key of the record to be updated
-   * @param payload the data to be persisted
-   */
-  updateOneById(id: IdValue<E>, payload: E): Promise<unknown>;
-
-  /**
-   * updates many records partially.
-   * @param qm the criteria to look for the records
-   * @param payload the data to be persisted
-   */
-  updateMany?(qm: QuerySearch<E>, payload: E): Promise<unknown>;
-
-  /**
-   * Insert or update a record given a search criteria.
-   * @param conflictPaths the keys to use for the unique search.
-   * @param payload the data to insert or update.
-   */
-  upsertOne?(conflictPaths: QueryConflictPaths<E>, payload: E): Promise<unknown>;
-
-  /**
-   * Insert or update a record.
-   * @param payload the data to be persisted
-   */
-  saveOne(payload: E): Promise<unknown>;
-
-  /**
-   * insert or update records.
-   * @param payload the data to be persisted
-   */
-  saveMany?(payload: E[]): Promise<unknown>;
-
-  /**
-   * delete or SoftDelete a record.
-   * @param id the primary key of the record
-   */
-  deleteOneById(id: IdValue<E>, opts?: QueryOptions): Promise<unknown>;
-
-  /**
-   * delete or SoftDelete records.
-   * @param qm the criteria to look for the records
-   */
-  deleteMany(qm: QuerySearch<E>, opts?: QueryOptions): Promise<unknown>;
-};
-
-/**
- * base contract for the backend repositories.
- */
-export interface Repository<E> extends UniversalRepository<E> {
-  findOneById(id: IdValue<E>, q?: QueryOne<E>): Promise<E>;
-
-  findOne(qm: QueryOne<E>): Promise<E>;
-
-  findMany(qm: Query<E>): Promise<E[]>;
-
-  findManyAndCount(qm: Query<E>): Promise<[E[], number]>;
-
-  count(q?: QuerySearch<E>): Promise<number>;
-
-  insertOne(payload: E): Promise<IdValue<E>>;
-
-  insertMany(payload: E[]): Promise<IdValue<E>[]>;
-
-  updateOneById(id: IdValue<E>, payload: E): Promise<number>;
-
-  updateMany(qm: QuerySearch<E>, payload: E): Promise<number>;
-
-  upsertOne(conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-
-  saveOne(payload: E): Promise<IdValue<E>>;
-
-  saveMany?(payload: E[]): Promise<IdValue<E>[]>;
-
-  deleteOneById(id: IdValue<E>, opts?: QueryOptions): Promise<number>;
-
-  deleteMany(qm: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-}