@uql/core 1.0.12 → 3.0.0

package/src/entity/decorator/definition.ts

@@ -0,0 +1,265 @@
+import 'reflect-metadata';
+import type {
+  EntityMeta,
+  EntityOptions,
+  FieldKey,
+  FieldOptions,
+  IdKey,
+  Key,
+  RelationKey,
+  RelationKeyMap,
+  RelationOptions,
+  Type,
+} from '../../type/index.js';
+import { getKeys, hasKeys, lowerFirst, upperFirst } from '../../util/index.js';
+
+const holder = globalThis;
+const metaKey = '@uql/core/entity/decorator';
+const metas: Map<Type<unknown>, EntityMeta<any>> = holder[metaKey] ?? new Map();
+holder[metaKey] = metas;
+
+export function defineField<E>(entity: Type<E>, key: string, opts: FieldOptions = {}): EntityMeta<E> {
+  const meta = ensureMeta(entity);
+  if (!opts.type) {
+    const type = inferType(entity, key);
+    opts = { ...opts, type };
+  }
+  meta.fields[key] = { ...meta.fields[key], ...{ name: key, ...opts } };
+  return meta;
+}
+
+export function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E> {
+  const meta = ensureMeta(entity);
+  const id = getIdKey(meta);
+  if (id) {
+    console.info(`Overriding ID property for '${entity.name}' from '${id}' to '${key}'`);
+    delete meta.fields[id];
+  }
+  return defineField(entity, key, { ...opts, isId: true });
+}
+
+export function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions<E>): EntityMeta<E> {
+  if (!opts.entity) {
+    const inferredType = inferEntityType(entity, key);
+    opts.entity = () => inferredType;
+  }
+  const meta = ensureMeta(entity);
+  meta.relations[key] = { ...meta.relations[key], ...opts };
+  return meta;
+}
+
+export function defineEntity<E>(entity: Type<E>, opts: EntityOptions = {}): EntityMeta<E> {
+  const meta = ensureMeta(entity);
+
+  if (!hasKeys(meta.fields)) {
+    throw TypeError(`'${entity.name}' must have fields`);
+  }
+
+  const onDeleteKeys = getKeys(meta.fields).filter((key) => meta.fields[key].onDelete) as FieldKey<E>[];
+
+  if (onDeleteKeys.length > 1) {
+    throw TypeError(`'${entity.name}' must have one field with 'onDelete' as maximum`);
+  }
+
+  if (opts.softDelete) {
+    if (!onDeleteKeys.length) {
+      throw TypeError(`'${entity.name}' must have one field with 'onDelete' to enable 'softDelete'`);
+    }
+    meta.softDelete = onDeleteKeys[0];
+  }
+
+  meta.name = opts.name ?? entity.name;
+  let proto: FunctionConstructor = Object.getPrototypeOf(entity.prototype);
+
+  while (proto.constructor !== Object) {
+    const parentMeta = ensureMeta(proto.constructor as Type<E>);
+    extendMeta(meta, parentMeta);
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  const id = getIdKey(meta);
+  if (!id) {
+    throw TypeError(`'${entity.name}' must have one field decorated with @Id`);
+  }
+  meta.id = id;
+
+  return meta;
+}
+
+export function getEntities(): Type<unknown>[] {
+  return [...metas.entries()].reduce((acc, [key, val]) => {
+    if (val.id) {
+      acc.push(key);
+    }
+    return acc;
+  }, []);
+}
+
+function ensureMeta<E>(entity: Type<E>): EntityMeta<E> {
+  let meta = metas.get(entity);
+  if (meta) {
+    return meta;
+  }
+  meta = { entity, fields: {}, relations: {} };
+  metas.set(entity, meta);
+  return meta;
+}
+
+export function getMeta<E>(entity: Type<E>): EntityMeta<E> {
+  const meta = metas.get(entity);
+  if (!meta) {
+    throw TypeError(`'${entity.name}' is not an entity`);
+  }
+  if (meta.processed) {
+    return meta;
+  }
+  meta.processed = true;
+  return fillRelations(meta);
+}
+
+function fillRelations<E>(meta: EntityMeta<E>): EntityMeta<E> {
+  for (const relKey in meta.relations) {
+    const relOpts = meta.relations[relKey as RelationKey<E>];
+
+    if (relOpts.references) {
+      // references were manually specified
+      continue;
+    }
+
+    if (relOpts.mappedBy) {
+      fillInverseSideRelations(relOpts);
+      continue;
+    }
+
+    const relEntity = relOpts.entity();
+    const relMeta = ensureMeta(relEntity);
+
+    if (relOpts.cardinality === 'mm') {
+      const idName = meta.fields[meta.id].name;
+      const relIdName = relMeta.fields[relMeta.id].name;
+      const source = lowerFirst(meta.name) + upperFirst(idName);
+      const target = lowerFirst(relMeta.name) + upperFirst(relIdName);
+      relOpts.references = [
+        { local: source, foreign: meta.id },
+        { local: target, foreign: relMeta.id },
+      ];
+    } else {
+      relOpts.references = [{ local: `${relKey}Id`, foreign: relMeta.id }];
+    }
+
+    if (relOpts.through) {
+      fillThroughRelations(relOpts.through());
+    }
+  }
+
+  return meta;
+}
+
+function fillInverseSideRelations<E>(relOpts: RelationOptions<E>): void {
+  const relEntity = relOpts.entity();
+  const relMeta = getMeta(relEntity);
+  relOpts.mappedBy = getMappedByRelationKey(relOpts);
+
+  if (relMeta.fields[relOpts.mappedBy as FieldKey<E>]) {
+    relOpts.references = [{ local: relMeta.id, foreign: relOpts.mappedBy }];
+    return;
+  }
+
+  const mappedByRelation = relMeta.relations[relOpts.mappedBy as RelationKey<E>];
+
+  if (relOpts.cardinality === 'm1' || relOpts.cardinality === 'mm') {
+    relOpts.references = mappedByRelation.references.slice().reverse();
+    relOpts.through = mappedByRelation.through;
+    return;
+  }
+
+  relOpts.references = mappedByRelation.references.map(({ local, foreign }) => ({
+    local: foreign,
+    foreign: local,
+  }));
+}
+
+function fillThroughRelations<E>(entity: Type<E>): void {
+  const meta = ensureMeta(entity);
+  meta.relations = getKeys(meta.fields).reduce((relations, key) => {
+    const { reference } = meta.fields[key as FieldKey<E>];
+    if (reference) {
+      const relEntity = reference();
+      const relMeta = ensureMeta(relEntity);
+      const relKey = key.slice(0, -relMeta.id.length);
+      const relOpts: RelationOptions = {
+        entity: reference,
+        cardinality: 'm1',
+        references: [{ local: key, foreign: relMeta.id }],
+      };
+      relations[relKey] = relOpts;
+    }
+    return relations;
+  }, {});
+}
+
+function getMappedByRelationKey<E>(relOpts: RelationOptions<E>): Key<E> {
+  if (typeof relOpts.mappedBy === 'function') {
+    const relEntity = relOpts.entity();
+    const relMeta = ensureMeta(relEntity);
+    const keyMap = getRelationKeyMap(relMeta);
+    return relOpts.mappedBy(keyMap);
+  }
+  return relOpts.mappedBy;
+}
+
+function getRelationKeyMap<E>(meta: EntityMeta<E>): RelationKeyMap<E> {
+  return getKeys(meta.fields)
+    .concat(getKeys(meta.relations))
+    .reduce(
+      (acc, key) => {
+        acc[key] = key;
+        return acc;
+      },
+      {} as RelationKeyMap<E>,
+    );
+}
+
+function getIdKey<E>(meta: EntityMeta<E>): IdKey<E> {
+  const id = getKeys(meta.fields).find((key) => meta.fields[key]?.isId);
+  return id as IdKey<E>;
+}
+
+function extendMeta<E>(target: EntityMeta<E>, source: EntityMeta<E>): void {
+  const sourceFields = { ...source.fields };
+  const targetId = getIdKey(target);
+  if (targetId) {
+    const sourceId = getIdKey(source);
+    if (sourceId) {
+      delete sourceFields[sourceId];
+    }
+  }
+  target.fields = { ...sourceFields, ...target.fields };
+  target.relations = { ...source.relations, ...target.relations };
+}
+
+function inferType<E>(entity: Type<E>, key: string): any {
+  return Reflect.getMetadata('design:type', entity.prototype, key);
+}
+
+function inferEntityType<E>(entity: Type<E>, key: string): Type<any> {
+  const inferredType = inferType(entity, key);
+  const isValidType = isValidEntityType(inferredType);
+  if (!isValidType) {
+    console.log('****', entity, key, inferredType);
+    throw TypeError(`'${entity.name}.${key}' type was auto-inferred with invalid type '${inferredType?.name}'`);
+  }
+  return inferredType;
+}
+
+export function isValidEntityType(type: unknown): type is Type<unknown> {
+  return (
+    typeof type === 'function' &&
+    type !== Boolean &&
+    type !== String &&
+    type !== Number &&
+    type !== BigInt &&
+    type !== Date &&
+    type !== Symbol
+  );
+}

package/src/entity/decorator/entity.ts

@@ -0,0 +1,8 @@
+import type { EntityOptions, Type } from '../../type/index.js';
+import { defineEntity } from './definition.js';
+
+export function Entity<E>(opts?: EntityOptions) {
+  return (entity: Type<E>): void => {
+    defineEntity(entity, opts);
+  };
+}

package/src/entity/decorator/field.ts

@@ -0,0 +1,9 @@
+import type { FieldOptions, Type } from '../../type/index.js';
+import { defineField } from './definition.js';
+
+export function Field<E>(opts?: FieldOptions) {
+  return (target: object, key: string): void => {
+    const entity = target.constructor as Type<E>;
+    defineField(entity, key, opts);
+  };
+}

package/src/entity/decorator/id.ts

@@ -0,0 +1,9 @@
+import type { FieldOptions, Type } from '../../type/index.js';
+import { defineId } from './definition.js';
+
+export function Id<E>(opts?: Omit<FieldOptions, 'isId'>) {
+  return (target: object, key: string): void => {
+    const entity = target.constructor as Type<E>;
+    defineId(entity, key, opts);
+  };
+}

package/src/entity/decorator/index.ts

@@ -0,0 +1,5 @@
+export { getEntities, getMeta } from './definition.js';
+export * from './entity.js';
+export * from './field.js';
+export * from './id.js';
+export * from './relation.js';

package/src/entity/decorator/relation.spec.ts

@@ -0,0 +1,41 @@
+import { expect, it } from 'bun:test';
+import { ManyToOne } from './relation.js';
+
+it('invalid auto-inferred type', () => {
+  expect(() => {
+    class SomeEntity {
+      @ManyToOne()
+      idTwo: number;
+    }
+  }).toThrow(`'SomeEntity.idTwo' type was auto-inferred with invalid type 'Number'`);
+  expect(() => {
+    class SomeEntity {
+      @ManyToOne()
+      idTwo: string;
+    }
+  }).toThrow(`'SomeEntity.idTwo' type was auto-inferred with invalid type 'String'`);
+  expect(() => {
+    class SomeEntity {
+      @ManyToOne()
+      idTwo: boolean;
+    }
+  }).toThrow(`'SomeEntity.idTwo' type was auto-inferred with invalid type 'Boolean'`);
+  expect(() => {
+    class SomeEntity {
+      @ManyToOne()
+      idTwo: object;
+    }
+  }).not.toThrow();
+  expect(() => {
+    class SomeEntity {
+      @ManyToOne()
+      idTwo: null;
+    }
+  }).toThrow(`'SomeEntity.idTwo' type was auto-inferred with invalid type 'undefined'`);
+  expect(() => {
+    class SomeEntity {
+      @ManyToOne()
+      idTwo: undefined;
+    }
+  }).toThrow(`'SomeEntity.idTwo' type was auto-inferred with invalid type 'undefined'`);
+});

package/src/entity/decorator/relation.ts

@@ -0,0 +1,34 @@
+import type {
+  RelationManyToManyOptions,
+  RelationManyToOneOptions,
+  RelationOneToManyOptions,
+  RelationOneToOneOptions,
+  RelationOptions,
+  Type,
+} from '../../type/index.js';
+import { defineRelation } from './definition.js';
+
+function Relation<E>(opts: RelationOptions<E>) {
+  return (target: object, key: string) => {
+    const entity = target.constructor as Type<E>;
+    defineRelation(entity, key, opts);
+  };
+}
+
+type RelationReturn = ReturnType<typeof Relation>;
+
+export function OneToOne<E>(opts?: RelationOneToOneOptions<E>): RelationReturn {
+  return Relation({ cardinality: '11', ...opts });
+}
+
+export function ManyToOne<E>(opts?: RelationManyToOneOptions<E>): RelationReturn {
+  return Relation({ cardinality: 'm1', ...opts });
+}
+
+export function OneToMany<E>(opts: RelationOneToManyOptions<E>): RelationReturn {
+  return Relation({ cardinality: '1m', ...opts });
+}
+
+export function ManyToMany<E>(opts: RelationManyToManyOptions<E>): RelationReturn {
+  return Relation({ cardinality: 'mm', ...opts });
+}

package/src/entity/index.ts

@@ -0,0 +1 @@
+export * from './decorator/index.js';

package/src/express/@types/express.d.ts

@@ -0,0 +1,8 @@
+import 'express';
+import type { Query } from '../../type/query.js';
+
+declare module 'express' {
+  export interface Request {
+    query?: Query;
+  }
+}

package/src/express/@types/index.d.ts

@@ -0,0 +1 @@
+import './express';

package/src/express/index.ts

@@ -0,0 +1,2 @@
+export * from './querierMiddleware.js';
+export * from './query.util.js';

package/src/express/querierMiddleware.ts

@@ -0,0 +1,217 @@
+import { Router as expressRouter, type Request, type Router } from 'express';
+import { getEntities, getMeta } from '../entity/index.js';
+import { getQuerier } from '../index.js';
+import type { EntityMeta, IdValue, Query, Type } from '../type/index.js';
+import { kebabCase } from '../util/index.js';
+import { parseQuery } from './query.util.js';
+
+export function querierMiddleware(opts: MiddlewareOptions = {}): Router {
+  const router = expressRouter();
+
+  const { include, exclude, ...extra } = opts;
+
+  let entities = include ?? getEntities();
+
+  if (exclude) {
+    entities = entities.filter((entity) => !opts.exclude.includes(entity));
+  }
+
+  if (!entities.length) {
+    throw new TypeError('no entities for the uql express middleware');
+  }
+
+  for (const entity of entities) {
+    const path = kebabCase(entity.name);
+    const subRouter = buildQuerierRouter(entity, extra);
+    router.use('/' + path, subRouter);
+  }
+
+  return router;
+}
+
+export function buildQuerierRouter<E>(entity: Type<E>, opts: ExtraOptions): Router {
+  const meta = getMeta(entity);
+  const router = expressRouter();
+
+  router.use((req, res, next) => {
+    pre(req, meta, opts);
+    next();
+  });
+
+  router.get('/one', async (req, res, next) => {
+    const q = req.query as Query<E>;
+    const querier = await getQuerier();
+    try {
+      const data = await querier.findOne(entity, q);
+      res.json({ data, count: data ? 1 : 0 });
+    } catch (err: any) {
+      next(err);
+    }
+  });
+
+  router.get('/:id', async (req, res, next) => {
+    const id = req.params.id as IdValue<E>;
+    const q = req.query as Query<E>;
+    q.$where ??= {};
+    if (Array.isArray(q.$where)) {
+      q.$where.push(id);
+    } else {
+      q.$where[meta.id as string] = id;
+    }
+    const querier = await getQuerier();
+    try {
+      const data = await querier.findOne(entity, q);
+      res.json({ data, count: data ? 1 : 0 });
+    } catch (err: any) {
+      next(err);
+    }
+  });
+
+  router.get('/', async (req, res, next) => {
+    const q = req.query as Query<E>;
+    const querier = await getQuerier();
+    try {
+      const findManyPromise = querier.findMany(entity, q);
+      const countPromise = req.query.count ? querier.count(entity, q) : undefined;
+      const [data, count] = await Promise.all([findManyPromise, countPromise]);
+      res.json({ data, count });
+    } catch (err: any) {
+      next(err);
+    }
+  });
+
+  router.get('/count', async (req, res, next) => {
+    const q = req.query as Query<E>;
+    const querier = await getQuerier();
+    try {
+      const count = await querier.count(entity, q);
+      res.json({ data: count, count });
+    } catch (err: any) {
+      next(err);
+    }
+  });
+
+  router.post('/', async (req, res, next) => {
+    const payload = req.body as E;
+    const querier = await getQuerier();
+    try {
+      await querier.beginTransaction();
+      const id = await querier.insertOne(entity, payload);
+      await querier.commitTransaction();
+      res.json({ data: id, count: id ? 1 : 0 });
+    } catch (err: any) {
+      await querier.rollbackTransaction();
+      next(err);
+    } finally {
+      await querier.release();
+    }
+  });
+
+  router.patch('/:id', async (req, res, next) => {
+    const payload = req.body as E;
+    const id = req.params.id as IdValue<E>;
+    const q = req.query as Query<E>;
+    q.$where ??= {};
+    if (Array.isArray(q.$where)) {
+      q.$where.push(id);
+    } else {
+      q.$where[meta.id as string] = id;
+    }
+    const querier = await getQuerier();
+    try {
+      await querier.beginTransaction();
+      const count = await querier.updateMany(entity, q, payload);
+      await querier.commitTransaction();
+      res.json({ data: req.params.id, count });
+    } catch (err: any) {
+      await querier.rollbackTransaction();
+      next(err);
+    } finally {
+      await querier.release();
+    }
+  });
+
+  router.delete('/:id', async (req, res, next) => {
+    const id = req.params.id as IdValue<E>;
+    const q = req.query as Query<E>;
+    q.$where ??= {};
+    if (Array.isArray(q.$where)) {
+      q.$where.push(id);
+    } else {
+      q.$where[meta.id as string] = id;
+    }
+    const querier = await getQuerier();
+    try {
+      await querier.beginTransaction();
+      const count = await querier.deleteMany(entity, q, {
+        softDelete: !!req.query.softDelete,
+      });
+      await querier.commitTransaction();
+      res.json({ data: req.params.id, count });
+    } catch (err: any) {
+      await querier.rollbackTransaction();
+      next(err);
+    } finally {
+      await querier.release();
+    }
+  });
+
+  router.delete('/', async (req, res, next) => {
+    const q = req.query as Query<E>;
+    const querier = await getQuerier();
+    let ids: IdValue<E>[] = [];
+    let count = 0;
+    try {
+      await querier.beginTransaction();
+      const founds = await querier.findMany(entity, q);
+      if (founds.length) {
+        ids = founds.map((found) => found[meta.id]);
+        count = await querier.deleteMany(entity, { $where: ids }, { softDelete: !!req.query.softDelete });
+      }
+      await querier.commitTransaction();
+      res.json({ data: ids, count });
+    } catch (err: any) {
+      await querier.rollbackTransaction();
+      next(err);
+    } finally {
+      await querier.release();
+    }
+  });
+
+  return router;
+}
+
+function pre(req: Request, meta: EntityMeta<any>, extra: ExtraOptions) {
+  const method = req.method;
+  parseQuery(req);
+  extra.pre?.(req, meta);
+  if (method === 'POST' || method === 'PATCH' || method === 'PUT') {
+    extra.preSave?.(req, meta);
+  } else if (method === 'GET' || method === 'DELETE') {
+    extra.preFilter?.(req, meta);
+  }
+}
+
+type ExtraOptions = {
+  /**
+   * Allow augment any kind of request before it runs
+   */
+  readonly pre?: Pre;
+  /**
+   * Allow augment a saving request (POST, PATCH, PUT) before it runs
+   */
+  readonly preSave?: PreSave;
+  /**
+   * Allow augment a filtering request (GET, PUT, DELETE) before it runs
+   */
+  readonly preFilter?: PreFilter;
+};
+
+type MiddlewareOptions = {
+  readonly include?: Type<unknown>[];
+  readonly exclude?: Type<unknown>[];
+} & ExtraOptions;
+
+type Pre = <E = unknown>(req: Request, meta: EntityMeta<E>) => void;
+type PreSave = <E = unknown>(req: Request, meta: EntityMeta<E>) => void;
+type PreFilter = <E = unknown>(req: Request, meta: EntityMeta<E>) => void;

package/src/express/query.util.spec.ts

@@ -0,0 +1,40 @@
+import { expect, it } from 'bun:test';
+import type { Request } from 'express';
+import type { Item } from '../test/index.js';
+import type { Query, QueryStringified } from '../type/index.js';
+import { parseQuery } from './query.util.js';
+
+it('parseQuery -- empty', () => {
+  const req1 = {} as Request;
+  parseQuery(req1);
+  expect(req1).toMatchObject({ query: { $where: {} } });
+  const req2 = { query: undefined as object } as Request;
+  parseQuery(req2);
+  expect(req2).toMatchObject({ query: { $where: {} } });
+});
+
+it('parseQuery stringified', () => {
+  const queryStr = {
+    $select:
+      '{ "id": true, "name": true, "measureUnit": {"$select":{"id":true, "name":true}}, "tax": {"$select":{"id":true, "name":true}} }',
+    $where: '{ "name": "lorem", "companyId": 40 }',
+    $sort: '{ "name": -1, "companyId": 1 }',
+    $skip: '200',
+    $limit: '100',
+  } satisfies QueryStringified;
+  const query = {
+    $select: {
+      id: true,
+      name: true,
+      measureUnit: { $select: { id: true, name: true } },
+      tax: { $select: { id: true, name: true } },
+    },
+    $where: { name: 'lorem', companyId: 40 },
+    $sort: { name: -1, companyId: 1 },
+    $skip: 200,
+    $limit: 100,
+  } satisfies Query<Item>;
+  const req = { query: queryStr } as unknown as Request;
+  parseQuery(req);
+  expect(req).toMatchObject({ query });
+});

package/src/express/query.util.ts

@@ -0,0 +1,21 @@
+import type { Request } from 'express';
+import type { Query, QueryStringified } from '../type/index.js';
+
+export function parseQuery(req: Request) {
+  req.query ??= {};
+  const qmsSrc: QueryStringified = req.query;
+  const qm = qmsSrc as unknown as Query<unknown>;
+  if (qmsSrc.$select) {
+    qm.$select = JSON.parse(qmsSrc.$select);
+  }
+  qm.$where = qmsSrc.$where ? JSON.parse(qmsSrc.$where) : {};
+  if (qmsSrc.$sort) {
+    qm.$sort = JSON.parse(qmsSrc.$sort);
+  }
+  if (qmsSrc.$skip) {
+    qm.$skip = Number(qmsSrc.$skip);
+  }
+  if (qmsSrc.$limit) {
+    qm.$limit = Number(qmsSrc.$limit);
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './dialect/index.js';
+export * from './entity/index.js';
+export * from './migrate/index.js';
+export * from './namingStrategy/index.js';
+export * from './options.js';
+export * from './querier/index.js';
+export * from './repository/index.js';
+export * from './type/index.js';
+export * from './util/index.js';

package/src/maria/index.ts

@@ -0,0 +1,3 @@
+export * from './mariaDialect.js';
+export * from './mariadbQuerier.js';
+export * from './mariadbQuerierPool.js';