@uql/core 1.0.12 → 3.1.0

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

@@ -0,0 +1,208 @@
+import { expect, it } from 'bun:test';
+import type { Item, ItemAdjustment, Storehouse } from '../test/index.js';
+import type { QuerySortMap } from '../type/index.js';
+import { escapeSqlId, flatObject, obtainAttrsPaths, unflatObjects } from './sql.util.js';
+
+it('flatObject', () => {
+  expect(flatObject(undefined)).toEqual({});
+  expect(flatObject(null)).toEqual({});
+  expect(flatObject({})).toEqual({});
+  const sort: QuerySortMap<Item> = {
+    name: 1,
+    measureUnit: { name: -1, category: { creator: { profile: { picture: 1 } } } },
+  };
+  expect(flatObject(sort)).toEqual<Record<string, number>>({
+    name: 1,
+    'measureUnit.name': -1,
+    'measureUnit.category.creator.profile.picture': 1,
+  });
+});
+
+it('unflatObjects - empty', () => {
+  const res1 = unflatObjects(undefined);
+  expect(res1).toBe(undefined);
+  const res2 = unflatObjects([]);
+  expect(res2).toEqual([]);
+});
+
+it('unflatObjects', () => {
+  const source: Storehouse[] = [
+    {
+      id: 1,
+      name: 'Auxiliar',
+      address: null,
+      description: null,
+      createdAt: 1,
+      updatedAt: null,
+      creatorId: 1,
+      companyId: 1,
+    },
+    {
+      id: 2,
+      name: 'Principal',
+      address: null,
+      description: null,
+      createdAt: 1,
+      updatedAt: 1578759519913,
+      creatorId: 1,
+      companyId: 1,
+    },
+  ];
+  const result = unflatObjects(source);
+  const expected: Storehouse[] = [
+    {
+      id: 1,
+      name: 'Auxiliar',
+      address: null,
+      description: null,
+      createdAt: 1,
+      updatedAt: null,
+      creatorId: 1,
+      companyId: 1,
+    },
+    {
+      id: 2,
+      name: 'Principal',
+      address: null,
+      description: null,
+      createdAt: 1,
+      updatedAt: 1578759519913,
+      creatorId: 1,
+      companyId: 1,
+    },
+  ];
+  expect(result).toEqual(expected);
+});
+
+it('unflatObjects deep', () => {
+  const source = [
+    {
+      id: 9,
+      buyPrice: 1000,
+      number: 10,
+      'item.id': 1,
+      'item.name': 'Arepa de Yuca y Queso x 6',
+      'item.createdAt': 1,
+      'item.buyLedgerAccount': 1,
+      'item.saleLedgerAccount': 1,
+      'item.tax': 1,
+      'item.companyId': 1,
+      'item.measureUnit': 1,
+      'item.inventoryable': 1,
+      'item.buyLedgerAccount.id': 1,
+      'item.buyLedgerAccount.name': 'Ventas',
+      'item.saleLedgerAccount.id': 1,
+      'item.saleLedgerAccount.name': 'Ventas',
+      'item.tax.id': 1,
+      'item.tax.name': 'IVA 0%',
+      'item.tax.percentage': 0,
+      'item.tax.category.pk': '1',
+      'item.tax.category.name': 'Impuestos',
+      'item.tax.category.description': 'Nacionales',
+      'item.measureUnit.id': 1,
+      'item.measureUnit.name': 'Unidad',
+      'item.creatorId': null as string,
+      'item.creator.id': null as string,
+      'item.creator.name': null as string,
+    },
+    {
+      id: 15,
+      buyPrice: 2000,
+      number: 20,
+      'item.id': 2,
+      'item.name': 'Pony Malta 2 litros',
+      'item.createdAt': 1,
+      'item.companyId': 1,
+      'item.creatorId': 5,
+      'item.creator.id': 5,
+      'item.creator.name': 'Roshi Master',
+    },
+  ];
+  const result = unflatObjects(source as Item[]);
+  const expected: ItemAdjustment[] = [
+    {
+      id: 9,
+      buyPrice: 1000,
+      number: 10,
+      item: {
+        id: 1,
+        name: 'Arepa de Yuca y Queso x 6',
+        createdAt: 1,
+        buyLedgerAccount: {
+          id: 1,
+          name: 'Ventas',
+        },
+        saleLedgerAccount: {
+          id: 1,
+          name: 'Ventas',
+        },
+        tax: {
+          id: 1,
+          name: 'IVA 0%',
+          percentage: 0,
+          category: {
+            pk: '1',
+            name: 'Impuestos',
+            description: 'Nacionales',
+          },
+        },
+        companyId: 1,
+        measureUnit: {
+          id: 1,
+          name: 'Unidad',
+        },
+        inventoryable: 1 as any as boolean,
+      },
+    },
+    {
+      id: 15,
+      buyPrice: 2000,
+      number: 20,
+      item: {
+        id: 2,
+        name: 'Pony Malta 2 litros',
+        createdAt: 1,
+        companyId: 1,
+        creatorId: 5,
+        creator: {
+          id: 5,
+          name: 'Roshi Master',
+        },
+      },
+    },
+  ];
+  expect(result).toEqual(expected);
+});
+
+it('obtainAttrsPaths - empty', () => {
+  const res1 = obtainAttrsPaths(undefined);
+  expect(res1).toEqual({});
+  const res2 = obtainAttrsPaths({});
+  expect(res2).toEqual({});
+});
+
+it('obtainAttrsPaths - object', () => {
+  const res1 = obtainAttrsPaths({
+    'prop1.a.b': 1,
+    'prop2.c.d': 2,
+  });
+  console.log('***** res1', res1);
+  expect(res1).toEqual({
+    'prop1.a.b': ['prop1', 'a', 'b'],
+    'prop2.c.d': ['prop2', 'c', 'd'],
+  });
+});
+
+it('escapeSqlId', () => {
+  expect(escapeSqlId('table')).toBe('`table`');
+  expect(escapeSqlId('table', '"')).toBe('"table"');
+  expect(escapeSqlId('table', '`')).toBe('`table`');
+  expect(escapeSqlId('my"table', '"')).toBe('"my""table"');
+  expect(escapeSqlId('my`table', '`')).toBe('`my``table`');
+  expect(escapeSqlId('schema.table')).toBe('`schema`.`table`');
+  expect(escapeSqlId('schema.table', '"')).toBe('"schema"."table"');
+  expect(escapeSqlId('schema.table', '"', true)).toBe('"schema.table"');
+  expect(escapeSqlId('table', '`', false, true)).toBe('`table`.');
+  expect(escapeSqlId('')).toBe('');
+  expect(escapeSqlId(undefined)).toBe('');
+});

package/src/util/sql.util.ts

@@ -0,0 +1,104 @@
+import type { FieldValue, Key } from '../type/index.js';
+import { getKeys, hasKeys } from './object.util.js';
+
+export function flatObject<E>(obj: E, pre?: string): E {
+  return getKeys(obj).reduce(
+    (acc, key) => flatObjectEntry(acc, key, obj[key as Key<E>], typeof obj[key as Key<E>] === 'object' ? '' : pre),
+    {} as E,
+  );
+}
+
+function flatObjectEntry<E>(map: E, key: string, val: any, pre?: string): E {
+  const prefix = pre ? `${pre}.${key}` : key;
+  return typeof val === 'object'
+    ? getKeys(val).reduce((acc, prop) => flatObjectEntry(acc, prop, val[prop], prefix), map)
+    : { ...map, [prefix]: val };
+}
+
+export function unflatObjects<T>(objects: T[]): T[] {
+  if (!Array.isArray(objects) || !objects.length) {
+    return objects;
+  }
+
+  const attrsPaths = obtainAttrsPaths(objects[0]);
+
+  if (!hasKeys(attrsPaths)) {
+    return objects;
+  }
+
+  return objects.map((row) => {
+    const dto = {} as T;
+
+    for (const col in row) {
+      if (row[col] === null) {
+        continue;
+      }
+      const attrPath = attrsPaths[col];
+      if (attrPath) {
+        const target = attrPath.slice(0, -1).reduce(
+          (acc, key) => {
+            if (typeof acc[key as Key<T>] !== 'object') {
+              acc[key as Key<T>] = {} as FieldValue<T>;
+            }
+            return acc[key as Key<T>];
+          },
+          dto as Record<string, any>,
+        );
+        target[attrPath[attrPath.length - 1]] = row[col];
+      } else {
+        dto[col] = row[col];
+      }
+    }
+
+    return dto;
+  });
+}
+
+export function obtainAttrsPaths<T>(row: T) {
+  return getKeys(row).reduce(
+    (acc, col) => {
+      // Support both dot notation (legacy) and underscore notation (new)
+      if (col.includes('.')) {
+        acc[col] = col.split('.');
+      } else if (col.includes('_') && col !== col.toUpperCase()) {
+        // Convert underscore to dot notation for nested paths
+        // Skip all-uppercase (like UPPER_CASE constants)
+        acc[col] = col.split('_');
+      }
+      return acc;
+    },
+    {} as { [k: string]: string[] },
+  );
+}
+
+/**
+ * Escape a SQL identifier (table name, column name, etc.)
+ * @param val the identifier to escape
+ * @param escapeIdChar the escape character to use (e.g. ` or ")
+ * @param forbidQualified whether to forbid qualified identifiers (containing dots)
+ * @param addDot whether to add a dot suffix
+ */
+export function escapeSqlId(
+  val: string,
+  escapeIdChar: '`' | '"' = '`',
+  forbidQualified?: boolean,
+  addDot?: boolean,
+): string {
+  if (!val) {
+    return '';
+  }
+
+  if (!forbidQualified && val.includes('.')) {
+    const result = val
+      .split('.')
+      .map((it) => escapeSqlId(it, escapeIdChar, true))
+      .join('.');
+    return addDot ? result + '.' : result;
+  }
+
+  const escaped = escapeIdChar + val.replace(new RegExp(escapeIdChar, 'g'), escapeIdChar + escapeIdChar) + escapeIdChar;
+
+  const suffix = addDot ? '.' : '';
+
+  return escaped + suffix;
+}

package/src/util/string.util.spec.ts

@@ -0,0 +1,46 @@
+import { expect, it } from 'bun:test';
+import { kebabCase, lowerFirst, snakeCase, upperFirst } from './string.util.js';
+
+it('kebabCase', () => {
+  const res1 = kebabCase('SomeWordsAndMore');
+  expect(res1).toBe('some-words-and-more');
+  const res2 = kebabCase('someWordsAndMore');
+  expect(res2).toBe('some-words-and-more');
+});
+
+it('upperFirst', () => {
+  const res1 = upperFirst('id');
+  expect(res1).toBe('Id');
+  const res2 = upperFirst('Id');
+  expect(res2).toBe('Id');
+  const res3 = upperFirst('idSomething');
+  expect(res3).toBe('IdSomething');
+});
+
+it('lowerFirst', () => {
+  const res1 = lowerFirst('id');
+  expect(res1).toBe('id');
+  const res2 = lowerFirst('Id');
+  expect(res2).toBe('id');
+  const res3 = lowerFirst('IdSomething');
+  expect(res3).toBe('idSomething');
+});
+
+it('snakeCase', () => {
+  const res1 = snakeCase('SomeWordsAndMore');
+  expect(res1).toBe('some_words_and_more');
+  const res2 = snakeCase('someWordsAndMore');
+  expect(res2).toBe('some_words_and_more');
+  const res3 = snakeCase('simple');
+  expect(res3).toBe('simple');
+  const res4 = snakeCase('ID');
+  expect(res4).toBe('i_d');
+  const res5 = snakeCase('already_snake');
+  expect(res5).toBe('already_snake');
+  const res6 = snakeCase('');
+  expect(res6).toBe('');
+  const res7 = snakeCase(undefined);
+  expect(res7).toBe(undefined);
+  const res8 = snakeCase(null);
+  expect(res8).toBe(null);
+});

package/src/util/string.util.ts

@@ -0,0 +1,35 @@
+export function kebabCase(val: string): string {
+  let resp = val.charAt(0).toLowerCase();
+  for (let i = 1; i < val.length; ++i) {
+    resp += val[i] === val[i].toUpperCase() ? '-' + val[i].toLowerCase() : val[i];
+  }
+  return resp;
+}
+
+export function upperFirst(text: string): string {
+  return text[0].toUpperCase() + text.slice(1);
+}
+
+export function lowerFirst(text: string): string {
+  return text[0].toLowerCase() + text.slice(1);
+}
+
+export function snakeCase(val: string): string {
+  if (val === undefined || val === null) {
+    return val;
+  }
+  if (!val) {
+    return '';
+  }
+  let resp = val.charAt(0).toLowerCase();
+  for (let i = 1; i < val.length; ++i) {
+    const char = val[i];
+    const charLower = char.toLowerCase();
+    if (char !== charLower && char === char.toUpperCase()) {
+      resp += '_' + charLower;
+    } else {
+      resp += char;
+    }
+  }
+  return resp;
+}

package/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "**/*/*.spec.ts", "**/*/*-spec.ts", "**/*/*.it.ts", "**/*/*-it.ts", "**/*/test"]
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}

package/README.md

@@ -1,177 +0,0 @@
-# [uql](https://nukak.org) · [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/rogerpadilla/uql/blob/main/LICENSE) [![tests](https://github.com/rogerpadilla/uql/actions/workflows/tests.yml/badge.svg)](https://github.com/rogerpadilla/uql) [![coverage status](https://coveralls.io/repos/rogerpadilla/uql/badge.svg?branch=main)](https://coveralls.io/r/rogerpadilla/uql?branch=main) [![npm version](https://badge.fury.io/js/%40uql%2Fcore.svg)](https://badge.fury.io/js/%40uql%2Fcore)
-
-## Quick Start
-
-`uql` is a flexible and efficient `ORM`, with declarative `JSON` syntax and really smart type-safety.
-
-The `uql` queries can be safely written in the frontend (browser/mobile) and sent to the backend; or only use `uql` in the backend, or even in a mobile app with an embedded database (like `sqlite`).
-
-### <a name="features"></a> Features
-
-- `JSON` (serializable) syntax for all the [queries](https://nukak.org/docs/querying-logical-operators).
-- uses the power of `TypeScript` to get smart type-safety [everywhere](https://nukak.org/docs/api-repository).
-- the generated queries are [performant](https://nukak.org/docs/querying-retrieve-relations), safe, and human-readable.
-- `$project`, `$filter`, `$sort`, `$limit` works at [multiple levels](https://nukak.org/docs/querying-retrieve-relations) (including deep relations and their fields).
-- [declarative](https://nukak.org/docs/transactions-declarative) and [imperative](https://nukak.org/docs/transactions-imperative) `transactions`.
-- [soft-delete](https://nukak.org/docs/entities-soft-delete), [virtual fields](https://nukak.org/docs/entities-virtual-fields), [repositories](https://nukak.org/docs/api-repository), `connection pooling`.
-- transparent support for [inheritance](https://nukak.org/docs/entities-advanced) between entities.
-- supports `Postgres`, `MySQL`, `MariaDB`, `SQLite`, `MongoDB`.
-
-### <a name="installation"></a> Installation
-
-1. Install the core package:
-
-```sh
-npm install @uql/core --save
-```
-
-or
-
-```sh
-yarn add @uql/core
-```
-
-2. Install one of the specific packages according to your database:
-
-| Database     | Package         |
-| ------------ | --------------- |
-| `MySQL`      | `@uql/mysql`    |
-| `PostgreSQL` | `@uql/postgres` |
-| `MariaDB`    | `@uql/maria`    |
-| `MongoDB`    | `@uql/mongo`    |
-| `SQLite`     | `@uql/sqlite`   |
-
-E.g. for `PostgreSQL`
-
-```sh
-npm install @uql/postgres --save
-```
-
-or with _yarn_
-
-```sh
-yarn add @uql/postgres
-```
-
-3. Additionally, your `tsconfig.json` may need the following flags:
-
-```json
-"target": "es2020",
-"experimentalDecorators": true,
-"emitDecoratorMetadata": true
-```
-
-### <a name="configuration"></a> Configuration
-
-A default querier-pool can be set in any of the bootstrap files of your app (e.g. in the `server.ts`).
-
-```ts
-import { setQuerierPool } from '@uql/core';
-import { PgQuerierPool } from '@uql/postgres';
-
-const querierPool = new PgQuerierPool(
-  {
-    host: 'localhost',
-    user: 'theUser',
-    password: 'thePassword',
-    database: 'theDatabase',
-  },
-  // a logger can optionally be passed so the SQL queries are logged
-  console.log
-);
-
-setQuerierPool(querierPool);
-```
-
-### <a name="definition-of-entities"></a> Definition of Entities
-
-Take any dump class (aka DTO) and annotate it with the decorators from `'@uql/core/entity'`.
-
-```ts
-import { v4 as uuidv4 } from 'uuid';
-import { Field, ManyToOne, Id, OneToMany, Entity, OneToOne, ManyToMany } from '@uql/core/entity';
-
-@Entity()
-export class Profile {
-  /**
-   * primary-key.
-   * the `onInsert` callback can be used to specify a custom mechanism for auto-generating
-   * the default value of a field when inserting a new record.
-   */
-  @Id({ onInsert: uuidv4 })
-  id?: string;
-  @Field()
-  picture?: string;
-  /**
-   * foreign-keys are really simple to specify.
-   */
-  @Field({ reference: () => User })
-  creatorId?: string;
-}
-
-@Entity()
-export class User {
-  @Id({ onInsert: uuidv4 })
-  id?: string;
-  @Field()
-  name?: string;
-  @Field()
-  email?: string;
-  @Field()
-  password?: string;
-  /**
-   * `mappedBy` can be a callback or a string (callback is useful for auto-refactoring).
-   */
-  @OneToOne({ entity: () => Profile, mappedBy: (profile) => profile.creatorId, cascade: true })
-  profile?: Profile;
-}
-
-@Entity()
-export class MeasureUnitCategory {
-  @Id({ onInsert: uuidv4 })
-  id?: string;
-  @Field()
-  name?: string;
-  @OneToMany({ entity: () => MeasureUnit, mappedBy: (measureUnit) => measureUnit.category })
-  measureUnits?: MeasureUnit[];
-}
-
-@Entity()
-export class MeasureUnit {
-  @Id({ onInsert: uuidv4 })
-  id?: string;
-  @Field()
-  name?: string;
-  @Field({ reference: () => MeasureUnitCategory })
-  categoryId?: string;
-  @ManyToOne({ cascade: 'persist' })
-  category?: MeasureUnitCategory;
-}
-```
-
-### <a name="query-data"></a> Query the data
-
-```ts
-import { getQuerier } from '@uql/core';
-import { User } from './entity';
-
-const querier = await getQuerier();
-
-const id = await this.querier.insertOne(User, {
-  email: 'lorem@example.com',
-  profile: { picture: 'ipsum.jpg' },
-});
-
-const users = await querier.findMany(User, {
-  $project: { id: true, email: true, profile: ['picture'] },
-  $filter: { email: { $iendsWith: '@google.com' } },
-  $sort: { createdAt: -1 },
-  $limit: 100,
-});
-
-await querier.release();
-```
-
----
-
-See more in https://nukak.org :high_brightness:

package/dialect/abstractSqlDialect.d.ts

@@ -1,30 +0,0 @@
-import { QueryFilter, Query, Scalar, QueryFilterFieldOperatorMap, QuerySort, QueryPager, FieldKey, QueryProject, Type, QueryCriteria, QueryOptions, QueryDialect, QueryFilterOptions, QueryComparisonOptions, QueryFilterMap, QuerySearch, QueryProjectOptions } from '../type';
-export declare abstract class AbstractSqlDialect implements QueryDialect {
-    readonly escapeIdChar: '`' | '"';
-    readonly beginTransactionCommand: string;
-    readonly escapeIdRegex: RegExp;
-    constructor(escapeIdChar: '`' | '"', beginTransactionCommand: string);
-    criteria<E>(entity: Type<E>, qm: Query<E>, opts?: QueryOptions): string;
-    projectFields<E>(entity: Type<E>, project: QueryProject<E>, opts?: QueryProjectOptions): string;
-    projectRelations<E>(entity: Type<E>, project?: QueryProject<E>, { prefix }?: {
-        prefix?: string;
-    }): {
-        fields: string;
-        tables: string;
-    };
-    select<E>(entity: Type<E>, qm: Query<E>, opts?: QueryOptions): string;
-    where<E>(entity: Type<E>, filter?: QueryFilter<E>, opts?: QueryFilterOptions): string;
-    compare<E, K extends keyof QueryFilterMap<E>>(entity: Type<E>, key: K, val: QueryFilterMap<E>[K], opts?: QueryComparisonOptions): string;
-    compareFieldOperator<E, K extends keyof QueryFilterFieldOperatorMap<E>>(entity: Type<E>, key: FieldKey<E>, op: K, val: QueryFilterFieldOperatorMap<E>[K], opts?: QueryOptions): string;
-    getComparisonKey<E>(entity: Type<E>, key: FieldKey<E>, { prefix }?: QueryOptions): Scalar;
-    group<E>(entity: Type<E>, fields: readonly FieldKey<E>[], opts?: QueryOptions): string;
-    sort<E>(entity: Type<E>, sort: QuerySort<E>, { prefix }?: QueryOptions): string;
-    pager(opts: QueryPager): string;
-    count<E>(entity: Type<E>, qm: QuerySearch<E>, opts?: QueryOptions): string;
-    find<E>(entity: Type<E>, qm: Query<E>, opts?: QueryOptions): string;
-    insert<E>(entity: Type<E>, payload: E | E[]): string;
-    update<E>(entity: Type<E>, qm: QueryCriteria<E>, payload: E, opts?: QueryOptions): string;
-    delete<E>(entity: Type<E>, qm: QueryCriteria<E>, opts?: QueryOptions): string;
-    escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
-    escape(value: any): Scalar;
-}