@uql/core 1.0.12 → 3.0.0

package/src/type/universalQuerier.ts

@@ -0,0 +1,133 @@
+import type { IdValue } from './entity.js';
+import type { Query, QueryConflictPaths, QueryOne, QueryOptions, QuerySearch } from './query.js';
+import type { UniversalRepository } from './repository.js';
+import type { Type } from './utility.js';
+
+/**
+ * A `querier` allows to interact with the datasource to perform persistence operations on any entity.
+ */
+export interface UniversalQuerier {
+  /**
+   * obtains the record with the given primary key.
+   * @param entity the target entity
+   * @param id the primary key value
+   * @param q the additional criteria options
+   * @return the record
+   */
+  findOneById<E>(entity: Type<E>, id: IdValue<E>, q?: QueryOne<E>): Promise<unknown>;
+
+  /**
+   * obtains the first record matching the given search parameters.
+   * @param entity the target entity
+   * @param q the criteria options
+   * @return the record
+   */
+  findOne<E>(entity: Type<E>, q: QueryOne<E>): Promise<unknown>;
+
+  /**
+   * obtains the records matching the given search parameters.
+   * @param entity the target entity
+   * @param q the criteria options
+   * @return the records
+   */
+  findMany<E>(entity: Type<E>, q: Query<E>): Promise<unknown>;
+
+  /**
+   * obtains the records matching the given search parameters,
+   * also counts the number of matches ignoring pagination.
+   * @param entity the target entity
+   * @param q the criteria options
+   * @return the records and the count
+   */
+  findManyAndCount<E>(entity: Type<E>, q: Query<E>): Promise<unknown>;
+
+  /**
+   * counts the number of records matching the given search parameters.
+   * @param entity the target entity
+   * @param q the search options
+   * @return the count
+   */
+  count<E>(entity: Type<E>, q: QuerySearch<E>): Promise<unknown>;
+
+  /**
+   * inserts a record.
+   * @param entity the entity to persist on
+   * @param payload the data to be persisted
+   * @return the ID
+   */
+  insertOne<E>(entity: Type<E>, payload: E): Promise<unknown>;
+
+  /**
+   * Inserts many records.
+   * @param entity the entity to persist on
+   * @param payload the data to be persisted
+   * @return the IDs
+   */
+  insertMany?<E>(entity: Type<E>, payload: E[]): Promise<unknown>;
+
+  /**
+   * updates a record partially.
+   * @param entity the entity to persist on
+   * @param id the primary key of the record to be updated
+   * @param payload the data to be persisted
+   * @return the number of affected records
+   */
+  updateOneById<E>(entity: Type<E>, id: IdValue<E>, payload: E): Promise<unknown>;
+
+  /**
+   * updates many records partially.
+   * @param entity the entity to persist on
+   * @param q the criteria to look for the records
+   * @param payload the data to be persisted
+   * @return the number of affected records
+   */
+  updateMany?<E>(entity: Type<E>, q: QuerySearch<E>, payload: E): Promise<unknown>;
+
+  /**
+   * Insert or update a record given a search criteria.
+   * @param entity the entity to persist on
+   * @param conflictPaths  the keys to use for the unique search
+   * @param payload the data to be persisted
+   * @return void
+   */
+  upsertOne?<E>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<unknown>;
+
+  /**
+   * insert or update a record.
+   * @param entity the entity to persist on
+   * @param payload the data to be persisted
+   * @return the ID
+   */
+  saveOne<E>(entity: Type<E>, payload: E): Promise<unknown>;
+
+  /**
+   * Insert or update records.
+   * @param entity the entity to persist on
+   * @param payload the data to be persisted
+   * @return the IDs
+   */
+  saveMany?<E>(entity: Type<E>, payload: E[]): Promise<unknown>;
+
+  /**
+   * delete or SoftDelete a record.
+   * @param entity the entity to persist on
+   * @param id the primary key of the record
+   * @return the number of affected records
+   */
+  deleteOneById<E>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<unknown>;
+
+  /**
+   * delete or SoftDelete records.
+   * @param entity the entity to persist on
+   * @param q the criteria to look for the records
+   * @return the number of affected records
+   */
+  deleteMany<E>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<unknown>;
+
+  /**
+   * get a repository for the given entity.
+   * @param entity the entity to get the repository for
+   * @return the repository
+   */
+  getRepository<E>(entity: Type<E>): UniversalRepository<E>;
+}

package/src/type/utility.ts

@@ -0,0 +1,21 @@
+export type Type<T> = new (...args: unknown[]) => T;
+
+export type BooleanLike = boolean | 0 | 1;
+
+export type MongoId = {
+  toHexString: () => string;
+};
+
+export type Scalar = string | number | boolean | bigint | Date | RegExp | Buffer | MongoId;
+
+export type ExpandScalar<T> = null | (T extends Date ? Date | string : T);
+
+export type Writable<T> = { -readonly [K in keyof T]: T[K] };
+
+export type Unpacked<T> = T extends (infer U)[]
+  ? U
+  : T extends (...args: unknown[]) => infer U
+    ? U
+    : T extends Promise<infer U>
+      ? U
+      : T;

package/src/util/dialect.util-extra.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'bun:test';
+import { Entity, Field, getMeta, Id, OneToMany } from '../entity/index.js';
+import { QueryRaw } from '../type/index.js';
+import {
+  buildSortMap,
+  buldQueryWhereAsMap,
+  fillOnFields,
+  filterFieldKeys,
+  filterPersistableRelationKeys,
+  filterRelationKeys,
+  getFieldCallbackValue,
+  isCascadable,
+  isSelectingRelations,
+} from './dialect.util.js';
+
+@Entity()
+class DialectUser {
+  @Id() id?: number;
+  @Field({ updatable: false }) readonlyProp?: string;
+  @Field({ virtual: new QueryRaw('1') }) virtualProp?: string;
+  @Field({ onInsert: () => 'inserted', onUpdate: 'updated' }) callbackProp?: string;
+  @OneToMany({ entity: () => DialectPost, mappedBy: 'user', cascade: true }) posts?: DialectPost[];
+}
+
+@Entity()
+class DialectPost {
+  @Id() id?: number;
+  @Field() user?: DialectUser;
+}
+
+describe('dialect.util', () => {
+  const meta = getMeta(DialectUser);
+
+  it('filterFieldKeys should filter virtual and non-updatable keys', () => {
+    const payload = { id: 1, readonlyProp: 'val', virtualProp: 'val', other: 'val' } as DialectUser;
+    const insertKeys = filterFieldKeys(meta, payload, 'onInsert');
+    expect(insertKeys).toContain('readonlyProp');
+    expect(insertKeys).not.toContain('virtualProp');
+
+    const updateKeys = filterFieldKeys(meta, payload, 'onUpdate');
+    expect(updateKeys).not.toContain('readonlyProp');
+    expect(updateKeys).not.toContain('virtualProp');
+  });
+
+  it('getFieldCallbackValue should handle functions and constants', () => {
+    expect(getFieldCallbackValue(() => 'test')).toBe('test');
+    expect(getFieldCallbackValue('constant')).toBe('constant');
+  });
+
+  it('fillOnFields should populate callback fields', () => {
+    const payload = { id: 1 } as DialectUser;
+    const filled = fillOnFields(meta, { ...payload }, 'onInsert');
+    expect(filled[0].callbackProp).toBe('inserted');
+
+    const updated = fillOnFields(meta, { ...payload }, 'onUpdate');
+    expect(updated[0].callbackProp).toBe('updated');
+  });
+
+  it('isCascadable should check action', () => {
+    expect(isCascadable('persist', true)).toBe(true);
+    expect(isCascadable('persist', false)).toBe(false);
+    expect(isCascadable('persist', 'persist')).toBe(true);
+    expect(isCascadable('persist', 'delete')).toBe(false);
+  });
+
+  it('filterPersistableRelationKeys should filter by cascade', () => {
+    const payload = { posts: [] } as DialectUser;
+    const keys = filterPersistableRelationKeys(meta, payload, 'persist');
+    expect(keys).toContain('posts');
+  });
+
+  it('filterRelationKeys should return relation keys from select', () => {
+    const select = { id: true, posts: true } as import('../type/index.js').QuerySelect<DialectUser>;
+    const keys = filterRelationKeys(meta, select);
+    expect(keys).toContain('posts');
+    expect(keys).not.toContain('id');
+  });
+
+  it('isSelectingRelations should check if any relation is selected', () => {
+    expect(isSelectingRelations(meta, { posts: true } as any)).toBe(true);
+    expect(isSelectingRelations(meta, { id: true } as any)).toBe(false);
+  });
+
+  it('buildSortMap should handle arrays and objects', () => {
+    expect(buildSortMap({ id: 1 } as any)).toEqual({ id: 1 });
+    expect(buildSortMap([['id', 1], { field: 'id', sort: -1 }] as any)).toEqual({ id: -1 });
+  });
+
+  it('buldQueryWhereAsMap should handle various types', () => {
+    expect(buldQueryWhereAsMap(meta, 123)).toEqual({ id: 123 });
+    expect(buldQueryWhereAsMap(meta, [1, 2])).toEqual({ id: [1, 2] });
+    const raw = new QueryRaw('test');
+    expect(buldQueryWhereAsMap(meta, raw)).toEqual({ $and: [raw] });
+    expect(buldQueryWhereAsMap(meta, { id: 1 } as any)).toEqual({ id: 1 });
+  });
+});

package/src/util/dialect.util.spec.ts

@@ -0,0 +1,23 @@
+import { expect, it } from 'bun:test';
+import { getMeta } from '../entity/decorator/index.js';
+import { User } from '../test/entityMock.js';
+import { augmentWhere } from './dialect.util.js';
+import { raw } from './raw.js';
+
+it('augmentWhere empty', () => {
+  const meta = getMeta(User);
+  expect(augmentWhere(meta)).toEqual({});
+  expect(augmentWhere(meta, {})).toEqual({});
+  expect(augmentWhere(meta, {}, {})).toEqual({});
+});
+
+it('augmentWhere', () => {
+  const meta = getMeta(User);
+  expect(augmentWhere(meta, { name: 'a' }, { name: 'b' })).toEqual({ name: 'b' });
+  expect(augmentWhere(meta, { name: 'a' }, { id: 1 })).toEqual({ name: 'a', id: 1 });
+  expect(augmentWhere(meta, { name: 'a' }, { $and: [1, 2] })).toEqual({ name: 'a', $and: [1, 2] });
+  expect(augmentWhere(meta, 1, { $or: [2, 3] })).toEqual({ id: 1, $or: [2, 3] });
+  const rawFilter = raw(() => 'a > 1');
+  expect(augmentWhere(meta, rawFilter, 1)).toEqual({ $and: [rawFilter], id: 1 });
+  expect(augmentWhere(meta, 1, rawFilter)).toEqual({ id: 1, $and: [rawFilter] });
+});

package/src/util/dialect.util.ts

@@ -0,0 +1,134 @@
+import {
+  type CascadeType,
+  type EntityMeta,
+  type FieldKey,
+  type FieldOptions,
+  type IdValue,
+  type Key,
+  type MongoId,
+  type OnFieldCallback,
+  QueryRaw,
+  type QuerySelect,
+  type QuerySort,
+  type QuerySortMap,
+  type QueryWhere,
+  type QueryWhereMap,
+  type RelationKey,
+} from '../type/index.js';
+import { getKeys } from './object.util.js';
+
+export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate' | 'onDelete'>;
+
+export function filterFieldKeys<E>(meta: EntityMeta<E>, payload: E, callbackKey: CallbackKey): FieldKey<E>[] {
+  const persistableKeys = getKeys(payload).filter((key) => {
+    const fieldOpts = meta.fields[key as FieldKey<E>];
+    return fieldOpts && !fieldOpts.virtual && (callbackKey !== 'onUpdate' || (fieldOpts.updatable ?? true));
+  }) as FieldKey<E>[];
+  return persistableKeys;
+}
+
+export function getFieldCallbackValue(val: OnFieldCallback) {
+  return typeof val === 'function' ? val() : val;
+}
+
+export function fillOnFields<E>(meta: EntityMeta<E>, payload: E | E[], callbackKey: CallbackKey): E[] {
+  const payloads = Array.isArray(payload) ? payload : [payload];
+  const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey]);
+  return payloads.map((it) => {
+    for (const key of keys) {
+      if (it[key] === undefined) {
+        it[key] = getFieldCallbackValue(meta.fields[key][callbackKey]);
+      }
+    }
+    return it;
+  });
+}
+
+export function filterPersistableRelationKeys<E>(
+  meta: EntityMeta<E>,
+  payload: E,
+  action: CascadeType,
+): RelationKey<E>[] {
+  const keys = getKeys(payload);
+  return keys.filter((key) => {
+    const relOpts = meta.relations[key as RelationKey<E>];
+    return relOpts && isCascadable(action, relOpts.cascade);
+  }) as RelationKey<E>[];
+}
+
+export function isCascadable(action: CascadeType, configuration?: boolean | CascadeType): boolean {
+  if (typeof configuration === 'boolean') {
+    return configuration;
+  }
+  return configuration === action;
+}
+
+export function filterRelationKeys<E>(meta: EntityMeta<E>, select: QuerySelect<E>): RelationKey<E>[] {
+  const keys = filterPositiveKeys(select);
+  return keys.filter((key) => key in meta.relations) as RelationKey<E>[];
+}
+
+export function isSelectingRelations<E>(meta: EntityMeta<E>, select: QuerySelect<E>): boolean {
+  const keys = filterPositiveKeys(select);
+  return keys.some((key) => key in meta.relations);
+}
+
+function filterPositiveKeys<E>(select: QuerySelect<E>): Key<E>[] {
+  if (Array.isArray(select)) {
+    return select as Key<E>[];
+  }
+  return getKeys(select).filter((key) => select[key]) as Key<E>[];
+}
+
+export function buildSortMap<E>(sort: QuerySort<E>): QuerySortMap<E> {
+  if (Array.isArray(sort)) {
+    return sort.reduce(
+      (acc, it) => {
+        if (Array.isArray(it)) {
+          acc[it[0]] = it[1];
+        } else {
+          acc[it.field] = it.sort;
+        }
+        return acc;
+      },
+      {} as QuerySortMap<E>,
+    );
+  }
+  return sort as QuerySortMap<E>;
+}
+
+export function augmentWhere<E>(
+  meta: EntityMeta<E>,
+  target: QueryWhere<E> = {},
+  source: QueryWhere<E> = {},
+): QueryWhere<E> {
+  const targetComparison = buldQueryWhereAsMap(meta, target);
+  const sourceComparison = buldQueryWhereAsMap(meta, source);
+  return {
+    ...targetComparison,
+    ...sourceComparison,
+  };
+}
+
+export function buldQueryWhereAsMap<E>(meta: EntityMeta<E>, filter: QueryWhere<E> = {}): QueryWhereMap<E> {
+  if (filter instanceof QueryRaw) {
+    return { $and: [filter] } as QueryWhereMap<E>;
+  }
+  if (isIdValue(filter)) {
+    return {
+      [meta.id]: filter,
+    } as QueryWhereMap<E>;
+  }
+  return filter as QueryWhereMap<E>;
+}
+
+function isIdValue<E>(filter: QueryWhere<E>): filter is IdValue<E> | IdValue<E>[] {
+  const type = typeof filter;
+  return (
+    type === 'string' ||
+    type === 'number' ||
+    type === 'bigint' ||
+    typeof (filter as MongoId).toHexString === 'function' ||
+    Array.isArray(filter)
+  );
+}

package/src/util/index.ts

@@ -0,0 +1,5 @@
+export * from './dialect.util.js';
+export * from './object.util.js';
+export * from './raw.js';
+export * from './sql.util.js';
+export * from './string.util.js';

package/src/util/object.util.spec.ts

@@ -0,0 +1,29 @@
+import { expect, it } from 'bun:test';
+import { clone, getKeys, hasKeys } from './object.util.js';
+
+it('clone', () => {
+  expect(clone({})).toEqual({});
+  expect(clone({ a: 1 })).toEqual({ a: 1 });
+  expect(clone([])).toEqual([]);
+  expect(clone([{ a: 1 }])).toEqual([{ a: 1 }]);
+
+  const source = [{ a: 1 }];
+  const cloned = clone(source);
+
+  expect(cloned[0]).not.toBe(source[0]);
+  expect(cloned).not.toBe(source);
+  expect(cloned[0]).toEqual(source[0]);
+  expect(cloned).toEqual(source);
+});
+
+it('hasKeys', () => {
+  expect(hasKeys({})).toBe(false);
+  expect(hasKeys({ a: 1 })).toBe(true);
+});
+
+it('getKeys', () => {
+  expect(getKeys(undefined)).toEqual([]);
+  expect(getKeys(null)).toEqual([]);
+  expect(getKeys({})).toEqual([]);
+  expect(getKeys({ a: 1 })).toEqual(['a']);
+});

package/src/util/object.util.ts

@@ -0,0 +1,27 @@
+import type { FieldKey, FieldOptions } from '../type/index.js';
+
+export function clone<T>(value: T): T {
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((it) => clone(it)) as unknown as T;
+  }
+  return { ...value };
+}
+
+export function hasKeys<T>(obj: T): boolean {
+  return getKeys(obj).length > 0;
+}
+
+export function getKeys<T>(obj: T): string[] {
+  return obj ? Object.keys(obj) : [];
+}
+
+export function getFieldKeys<E>(
+  fields: {
+    [K in FieldKey<E>]?: FieldOptions;
+  },
+): FieldKey<E>[] {
+  return getKeys(fields).filter((field) => fields[field as FieldKey<E>].eager ?? true) as FieldKey<E>[];
+}

package/src/util/raw.ts

@@ -0,0 +1,11 @@
+import { QueryRaw, type QueryRawFn, type Scalar } from '../type/index.js';
+
+/**
+ * Allow using any raw value that shouldn't be automatically escaped by the ORM.
+ * @param value the raw value
+ * @param alias optional alias
+ * @returns a QueryRaw instance
+ */
+export function raw(value: Scalar | QueryRawFn, alias?: string): any {
+  return new QueryRaw(value, alias);
+}

package/src/util/sql.util-extra.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'bun:test';
+import { obtainAttrsPaths } from './sql.util.js';
+
+describe('sql.util extras', () => {
+  it('obtainAttrsPaths should handle nested objects with depth', () => {
+    const res = obtainAttrsPaths({
+      'user.profile.name': 1,
+      'user.email': 1,
+      user_profile_name: 1,
+    });
+    expect(res).toEqual({
+      'user.profile.name': ['user', 'profile', 'name'],
+      'user.email': ['user', 'email'],
+      user_profile_name: ['user', 'profile', 'name'],
+    });
+  });
+});