create-projx 1.6.4 → 1.7.0

package/src/addons/orms/typeorm/fastify/src/modules/_base/auto-routes.ts

@@ -0,0 +1,239 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import type {
+  DeepPartial,
+  EntityTarget,
+  ObjectLiteral,
+  Repository,
+} from 'typeorm';
+import { dataSource } from '../../db/data-source.js';
+import { registerInRegistry } from './registry.js';
+import {
+  buildOrder,
+  buildPagination,
+  buildSearchWheres,
+  buildWhere,
+  parseRawQuery,
+} from './query-engine.js';
+
+export type BeforeCreateHook = (
+  request: FastifyRequest,
+  data: Record<string, unknown>,
+) => void | Promise<void>;
+export type AfterCreateHook = (
+  request: FastifyRequest,
+  record: Record<string, unknown>,
+) => void | Promise<void>;
+export type BeforeUpdateHook = (
+  request: FastifyRequest,
+  reply: FastifyReply,
+  data: Record<string, unknown>,
+) => void | Promise<void>;
+export type AfterUpdateHook = (
+  request: FastifyRequest,
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+) => void | Promise<void>;
+export type BeforeDeleteHook = (
+  request: FastifyRequest,
+  recordId: string,
+) => void | Promise<void>;
+
+export interface TypeormEntityConfig<T extends ObjectLiteral> {
+  name: string;
+  apiPrefix: string;
+  tag: string;
+  entity: EntityTarget<T>;
+  primaryKey?: string;
+  searchableFields?: string[];
+  readonly?: boolean;
+  bulkOperations?: boolean;
+  beforeCreate?: BeforeCreateHook;
+  afterCreate?: AfterCreateHook;
+  beforeUpdate?: BeforeUpdateHook;
+  afterUpdate?: AfterUpdateHook;
+  beforeDelete?: BeforeDeleteHook;
+}
+
+function columnNames<T extends ObjectLiteral>(
+  repo: Repository<T>,
+): Set<string> {
+  return new Set(repo.metadata.columns.map((c) => c.propertyName));
+}
+
+export function registerEntityRoutes<T extends ObjectLiteral>(
+  app: FastifyInstance,
+  config: TypeormEntityConfig<T>,
+): void {
+  registerInRegistry({ name: config.name, apiPrefix: config.apiPrefix });
+  const pk = config.primaryKey ?? 'id';
+
+  function repo(): Repository<T> {
+    return dataSource.getRepository(config.entity);
+  }
+
+  app.get('/', { schema: { tags: [config.tag] } }, async (request, reply) => {
+    const rawQs = request.url.split('?')[1] ?? '';
+    const query = parseRawQuery(rawQs);
+    const r = repo();
+    const cols = columnNames(r);
+    const filterWhere = buildWhere<T>(cols, query.filters);
+    const searchWheres = buildSearchWheres<T>(
+      config.searchableFields ?? [],
+      query.search,
+    );
+    const where =
+      searchWheres.length > 0
+        ? searchWheres.map((s) => ({ ...filterWhere, ...s }))
+        : filterWhere;
+    const order = buildOrder<T>(cols, query.order_by);
+    const [rows, count] = await r.findAndCount({
+      where,
+      order,
+      skip: (query.page - 1) * query.page_size,
+      take: query.page_size,
+    });
+    return reply.send({
+      data: rows,
+      pagination: buildPagination(query.page, query.page_size, count),
+    });
+  });
+
+  app.get(
+    '/:id',
+    { schema: { tags: [config.tag] } },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const r = repo();
+      const record = await r.findOne({ where: { [pk]: id } as never });
+      if (!record)
+        return reply
+          .status(404)
+          .send({ detail: 'Not found', request_id: request.id });
+      return reply.send(record);
+    },
+  );
+
+  if (config.readonly) return;
+
+  app.post('/', { schema: { tags: [config.tag] } }, async (request, reply) => {
+    const data = request.body as Record<string, unknown>;
+    await config.beforeCreate?.(request, data);
+    const r = repo();
+    const entity = r.create(data as DeepPartial<T>);
+    const record = (await r.save(entity)) as unknown as Record<string, unknown>;
+    if (config.afterCreate) {
+      try {
+        await config.afterCreate(request, record);
+      } catch (err) {
+        request.log.error(
+          {
+            err,
+            entity: config.name,
+            record_id: (record as { id?: string }).id,
+          },
+          'afterCreate hook failed (record persisted; hook is best-effort)',
+        );
+      }
+    }
+    return reply.status(201).send(record);
+  });
+
+  app.patch(
+    '/:id',
+    { schema: { tags: [config.tag] } },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const data = request.body as Record<string, unknown>;
+      if (!data || Object.keys(data).length === 0) {
+        return reply.status(400).send({
+          detail: 'Request body cannot be empty',
+          request_id: request.id,
+        });
+      }
+      if (config.beforeUpdate) {
+        await config.beforeUpdate(request, reply, data);
+        if (reply.sent) return;
+      }
+      const r = repo();
+      const existing = await r.findOne({ where: { [pk]: id } as never });
+      if (!existing)
+        return reply
+          .status(404)
+          .send({ detail: 'Not found', request_id: request.id });
+      const before = { ...(existing as Record<string, unknown>) };
+      Object.assign(existing, data);
+      const saved = (await r.save(existing)) as Record<string, unknown>;
+      if (config.afterUpdate) {
+        try {
+          await config.afterUpdate(request, before, saved);
+        } catch (err) {
+          request.log.error(
+            { err, entity: config.name, record_id: id },
+            'afterUpdate hook failed (record persisted; hook is best-effort)',
+          );
+        }
+      }
+      return reply.send(saved);
+    },
+  );
+
+  app.delete(
+    '/:id',
+    { schema: { tags: [config.tag] } },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      if (config.beforeDelete) await config.beforeDelete(request, id);
+      const r = repo();
+      const result = await r.delete({ [pk]: id } as never);
+      if (!result.affected) {
+        return reply
+          .status(404)
+          .send({ detail: 'Not found', request_id: request.id });
+      }
+      return reply.status(204).send();
+    },
+  );
+
+  if (!config.bulkOperations) return;
+
+  app.post(
+    '/bulk',
+    { schema: { tags: [config.tag] } },
+    async (request, reply) => {
+      const { items } = request.body as { items: Record<string, unknown>[] };
+      if (!Array.isArray(items) || items.length === 0) {
+        return reply.status(400).send({
+          detail: 'items must be a non-empty array',
+          request_id: request.id,
+        });
+      }
+      for (const item of items) {
+        await config.beforeCreate?.(request, item);
+      }
+      const r = repo();
+      const entities = r.create(items as DeepPartial<T>[]);
+      const rows = (await r.save(entities)) as unknown as Record<
+        string,
+        unknown
+      >[];
+      return reply.status(201).send({ data: rows, count: rows.length });
+    },
+  );
+
+  app.delete(
+    '/bulk',
+    { schema: { tags: [config.tag] } },
+    async (request, reply) => {
+      const { ids } = request.body as { ids: string[] };
+      if (!Array.isArray(ids) || ids.length === 0) {
+        return reply.status(400).send({
+          detail: 'ids must be a non-empty array',
+          request_id: request.id,
+        });
+      }
+      const r = repo();
+      await r.delete(ids as never);
+      return reply.status(204).send();
+    },
+  );
+}

package/src/addons/orms/typeorm/fastify/src/modules/_base/index.ts

@@ -0,0 +1,19 @@
+export { registerEntityRoutes } from './auto-routes.js';
+export type {
+  TypeormEntityConfig,
+  BeforeCreateHook,
+  AfterCreateHook,
+  BeforeUpdateHook,
+  AfterUpdateHook,
+  BeforeDeleteHook,
+} from './auto-routes.js';
+export { listEntities, registerInRegistry } from './registry.js';
+export type { RegisteredEntity } from './registry.js';
+export {
+  buildOrder,
+  buildPagination,
+  buildSearchWheres,
+  buildWhere,
+  parseRawQuery,
+} from './query-engine.js';
+export type { ParsedQuery, PaginationMeta } from './query-engine.js';

package/src/addons/orms/typeorm/fastify/tests/modules/app.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it, afterEach } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+import { buildApp } from '../../src/app.js';
+
+describe('Fastify TypeORM app', () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it('exposes empty generated metadata until entities are added', async () => {
+    app = await buildApp({ logger: false });
+    const res = await app.inject({ method: 'GET', url: '/api/v1/_meta' });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ entities: [], orm: 'typeorm' });
+  });
+});

package/src/addons/orms/typeorm/fastify/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vitest/config';
+import { config } from 'dotenv';
+
+config({ path: '.env.test' });
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: [
+        'src/server.ts',
+        'src/app.ts',
+        'src/config.ts',
+        'src/plugins/swagger.ts',
+      ],
+      thresholds: {
+        statements: 80,
+        branches: 80,
+        functions: 80,
+        lines: 80,
+      },
+    },
+    pool: 'forks',
+    testTimeout: 15000,
+    hookTimeout: 15000,
+  },
+});

package/src/addons/orms/typeorm/gen-entity/entity.ts

@@ -0,0 +1,21 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+@Entity({ name: '__TABLE_NAME__' })
+export class __ENTITY_PASCAL__ {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+__COLUMN_DECORATORS__
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt!: Date;
+
+  @UpdateDateColumn({ name: 'updated_at' })
+  updatedAt!: Date;
+}

package/src/addons/orms/typeorm/gen-entity/express-router.ts

@@ -0,0 +1,17 @@
+import type { Express } from 'express';
+import { __ENTITY_PASCAL__ } from '../../entities/__ENTITY_KEBAB__.js';
+import { registerEntityRoutes } from '../_base/index.js';
+
+export function register__ENTITY_PASCAL__Entity(app: Express): void {
+  app.use(
+    '/api/v1__API_PREFIX__',
+    registerEntityRoutes({
+      name: '__ENTITY_PASCAL__',
+      apiPrefix: '__API_PREFIX__',
+      tag: '__TAG__',
+      entity: __ENTITY_PASCAL__,
+      searchableFields: [__SEARCHABLE_FIELDS_ARRAY__],
+      bulkOperations: __BULK_OPERATIONS__,
+    }),
+  );
+}

package/src/addons/orms/typeorm/gen-entity/express-test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeAll, beforeEach, afterAll } from 'vitest';
+import request from 'supertest';
+import { buildApp } from '../src/app.js';
+import { __ENTITY_PASCAL__ } from '../src/entities/__ENTITY_KEBAB__.js';
+import { dataSource, closeDatabase } from '../src/db/data-source.js';
+
+const app = buildApp();
+
+describe('__ENTITY_PASCAL__ CRUD', () => {
+  beforeAll(async () => {
+    if (!dataSource.isInitialized) await dataSource.initialize();
+    await dataSource.synchronize(true);
+  });
+
+  beforeEach(async () => {
+    await dataSource.getRepository(__ENTITY_PASCAL__).clear();
+  });
+
+  afterAll(async () => {
+    await closeDatabase();
+  });
+
+  it('POST creates a record', async () => {
+    const res = await request(app).post('/api/v1__API_PREFIX__').send(__SAMPLE_PAYLOAD__);
+    expect(res.status).toBe(201);
+    expect(res.body).toMatchObject(__SAMPLE_PAYLOAD__);
+  });
+
+  it('GET / lists records with pagination', async () => {
+    await request(app).post('/api/v1__API_PREFIX__').send(__SAMPLE_PAYLOAD__);
+    const res = await request(app).get('/api/v1__API_PREFIX__');
+    expect(res.status).toBe(200);
+    expect(res.body.data).toHaveLength(1);
+    expect(res.body.pagination).toMatchObject({ current_page: 1, total_records: 1 });
+  });
+
+  it('GET /:id returns one record', async () => {
+    const created = await request(app).post('/api/v1__API_PREFIX__').send(__SAMPLE_PAYLOAD__);
+    const { id } = created.body as { id: string };
+    const res = await request(app).get(`/api/v1__API_PREFIX__/${id}`);
+    expect(res.status).toBe(200);
+  });
+
+  it('GET /:id returns 404 when not found', async () => {
+    const res = await request(app).get(
+      '/api/v1__API_PREFIX__/00000000-0000-0000-0000-000000000000',
+    );
+    expect(res.status).toBe(404);
+  });
+
+  it('PATCH /:id updates a record', async () => {
+    const created = await request(app).post('/api/v1__API_PREFIX__').send(__SAMPLE_PAYLOAD__);
+    const { id } = created.body as { id: string };
+    const res = await request(app).patch(`/api/v1__API_PREFIX__/${id}`).send(__UPDATE_PAYLOAD__);
+    expect(res.status).toBe(200);
+  });
+
+  it('DELETE /:id removes a record', async () => {
+    const created = await request(app).post('/api/v1__API_PREFIX__').send(__SAMPLE_PAYLOAD__);
+    const { id } = created.body as { id: string };
+    const del = await request(app).delete(`/api/v1__API_PREFIX__/${id}`);
+    expect(del.status).toBe(204);
+    const get = await request(app).get(`/api/v1__API_PREFIX__/${id}`);
+    expect(get.status).toBe(404);
+  });
+});

package/src/addons/orms/typeorm/gen-entity/fastify-router.ts

@@ -0,0 +1,19 @@
+import type { FastifyInstance } from 'fastify';
+import { __ENTITY_PASCAL__ } from '../../entities/__ENTITY_KEBAB__.js';
+import { registerEntityRoutes } from '../_base/index.js';
+
+export async function register__ENTITY_PASCAL__Entity(app: FastifyInstance): Promise<void> {
+  await app.register(
+    async (instance) => {
+      registerEntityRoutes(instance, {
+        name: '__ENTITY_PASCAL__',
+        apiPrefix: '__API_PREFIX__',
+        tag: '__TAG__',
+        entity: __ENTITY_PASCAL__,
+        searchableFields: [__SEARCHABLE_FIELDS_ARRAY__],
+        bulkOperations: __BULK_OPERATIONS__,
+      });
+    },
+    { prefix: '/api/v1__API_PREFIX__' },
+  );
+}

package/src/addons/orms/typeorm/gen-entity/fastify-test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeAll, beforeEach, afterAll } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+import { buildApp } from '../../src/app.js';
+import { __ENTITY_PASCAL__ } from '../../src/entities/__ENTITY_KEBAB__.js';
+import { dataSource } from '../../src/db/data-source.js';
+
+describe('__ENTITY_PASCAL__ CRUD', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await buildApp({ logger: false });
+    await dataSource.synchronize(true);
+    await app.ready();
+  });
+
+  beforeEach(async () => {
+    await dataSource.getRepository(__ENTITY_PASCAL__).clear();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('POST creates a record', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1__API_PREFIX__',
+      payload: __SAMPLE_PAYLOAD__,
+    });
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject(__SAMPLE_PAYLOAD__);
+  });
+
+  it('GET / lists records with pagination', async () => {
+    await app.inject({ method: 'POST', url: '/api/v1__API_PREFIX__', payload: __SAMPLE_PAYLOAD__ });
+    const res = await app.inject({ method: 'GET', url: '/api/v1__API_PREFIX__' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data).toHaveLength(1);
+    expect(body.pagination).toMatchObject({ current_page: 1, total_records: 1 });
+  });
+
+  it('GET /:id returns one record', async () => {
+    const created = await app.inject({
+      method: 'POST',
+      url: '/api/v1__API_PREFIX__',
+      payload: __SAMPLE_PAYLOAD__,
+    });
+    const { id } = created.json() as { id: string };
+    const res = await app.inject({ method: 'GET', url: `/api/v1__API_PREFIX__/${id}` });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('GET /:id returns 404 when not found', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/v1__API_PREFIX__/00000000-0000-0000-0000-000000000000',
+    });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('PATCH /:id updates a record', async () => {
+    const created = await app.inject({
+      method: 'POST',
+      url: '/api/v1__API_PREFIX__',
+      payload: __SAMPLE_PAYLOAD__,
+    });
+    const { id } = created.json() as { id: string };
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/api/v1__API_PREFIX__/${id}`,
+      payload: __UPDATE_PAYLOAD__,
+    });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('DELETE /:id removes a record', async () => {
+    const created = await app.inject({
+      method: 'POST',
+      url: '/api/v1__API_PREFIX__',
+      payload: __SAMPLE_PAYLOAD__,
+    });
+    const { id } = created.json() as { id: string };
+    const del = await app.inject({ method: 'DELETE', url: `/api/v1__API_PREFIX__/${id}` });
+    expect(del.statusCode).toBe(204);
+    const get = await app.inject({ method: 'GET', url: `/api/v1__API_PREFIX__/${id}` });
+    expect(get.statusCode).toBe(404);
+  });
+});

package/src/addons/orms/typeorm/manifest.json

@@ -0,0 +1,53 @@
+{
+  "name": "typeorm",
+  "displayName": "TypeORM",
+  "frameworks": ["fastify", "express"],
+  "removeFromBase": [
+    "prisma",
+    "src/plugins/prisma.ts",
+    "src/prisma.ts",
+    "src/lib/service-config.ts",
+    "src/modules/_base",
+    "src/modules/audit-logs",
+    "tsconfig.json",
+    "tests/modules/audit-logs.test.ts",
+    "tests/modules/audit-middleware.test.ts",
+    "tests/modules/auto-routes.test.ts",
+    "tests/modules/entity-validation.test.ts",
+    "tests/modules/expand.test.ts",
+    "tests/modules/field-privacy.test.ts",
+    "tests/modules/meta.test.ts",
+    "tests/modules/query-engine.test.ts",
+    "tests/modules/repository.test.ts",
+    "tests/modules/service.test.ts",
+    "tests/helpers/crud-test-base.ts",
+    "tests/helpers/crud-test-base.test.ts",
+    "tests/helpers/migration-checksum.ts",
+    "tests/helpers/migration-checksum.test.ts",
+    "tests/global-setup.ts",
+    "tests"
+  ],
+  "packageOverrides": {
+    "descriptionReplace": { "from": "Prisma", "to": "TypeORM" },
+    "removeDependencies": ["@prisma/client"],
+    "removeDevDependencies": ["prisma"],
+    "addDependencies": {
+      "typeorm": "^0.3.20",
+      "reflect-metadata": "^0.2.2",
+      "pg": "^8.16.3"
+    },
+    "addDevDependencies": {
+      "@types/pg": "^8.15.5"
+    },
+    "removeScriptPrefixes": ["prisma:"],
+    "addScripts": {
+      "db:sync": "tsx scripts/db-sync.ts",
+      "db:migrate:generate": "typeorm-ts-node-esm migration:generate -d src/db/data-source.ts",
+      "db:migrate": "typeorm-ts-node-esm migration:run -d src/db/data-source.ts"
+    }
+  },
+  "dockerfile": {
+    "extraConfigFiles": [],
+    "migrateCommand": "tsx scripts/db-sync.ts"
+  }
+}

package/src/addons/orms/typeorm/shared/scripts/db-sync.ts

@@ -0,0 +1,14 @@
+import 'reflect-metadata';
+import { dataSource } from '../src/db/data-source.js';
+
+async function main(): Promise<void> {
+  await dataSource.initialize();
+  await dataSource.synchronize();
+  console.log('TypeORM schema synced.');
+  await dataSource.destroy();
+}
+
+main().catch((err: unknown) => {
+  console.error('db-sync failed:', err);
+  process.exit(1);
+});

package/src/addons/orms/typeorm/shared/src/db/data-source.ts

@@ -0,0 +1,21 @@
+import 'reflect-metadata';
+import { DataSource } from 'typeorm';
+import { config } from '../config.js';
+import { entities } from '../entities/index.js';
+
+export const dataSource = new DataSource({
+  type: 'postgres',
+  url: config.DATABASE_URL,
+  entities,
+  synchronize: false,
+  logging: false,
+});
+
+export async function checkDatabase(): Promise<void> {
+  if (!dataSource.isInitialized) await dataSource.initialize();
+  await dataSource.query('SELECT 1');
+}
+
+export async function closeDatabase(): Promise<void> {
+  if (dataSource.isInitialized) await dataSource.destroy();
+}

package/src/addons/orms/typeorm/shared/src/entities/index.ts

@@ -0,0 +1,8 @@
+// Aggregator for all TypeORM entity classes. The DataSource registers these
+// in `../db/data-source.ts`. `gen entity` appends new imports + entries below the anchors.
+
+// projx-anchor: model-imports
+
+export const entities = [
+  // projx-anchor: model-exports
+];