@dunx/create-app 0.4.0 → 0.5.0

package/templates/features/pictures/thumbnails.service.ts

@@ -0,0 +1,108 @@
+import { Logger } from '@dunx/core';
+import {
+  EncodableFormat,
+  type EncodedImage,
+  ImageFit,
+  Images,
+  ImagesOptions,
+} from '@dunx/infra/images';
+
+/**
+ * A 4x4 RGB gradient PNG - the only binary in the example, and small enough to
+ * read as a constant. Everything larger is derived from it at runtime by
+ * `Bun.Image` itself, so nothing is checked in and nothing is downloaded.
+ */
+const SEED_PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAIAAAAmkwkpAAAAKElEQVR42g3HMQEAAAzC' +
+  'MEzip3pqki1fktBgWEhKi2X9SEWZn9Hh2DgEahfxpRmu7gAAAABJRU5ErkJggg==';
+
+export interface RenderOptions {
+  readonly width: number;
+  readonly height?: number | undefined;
+  readonly fit: ImageFit;
+  readonly format: EncodableFormat;
+  readonly quality?: number | undefined;
+}
+
+export class Thumbnails {
+  constructor(
+    private readonly images: Images,
+    private readonly config: ImagesOptions,
+    private readonly logger: Logger,
+  ) {}
+
+  /** The 64x48 source every route below derives from, grown from the 4x4 seed. */
+  private async source(): Promise<Uint8Array> {
+    const seed = new Uint8Array(Buffer.from(SEED_PNG_BASE64, 'base64'));
+    const seeded = await this.images.load(seed);
+    return seeded
+      .resize(64, 48, { fit: ImageFit.FILL })
+      .to(EncodableFormat.PNG)
+      .toBytes();
+  }
+
+  async render(options: RenderOptions): Promise<EncodedImage> {
+    const pipeline = await this.images.load(await this.source());
+    const resized = pipeline.resize(options.width, options.height, {
+      fit: options.fit,
+    });
+    // A quality only means something to a lossy encoder, so it is only passed
+    // when one was asked for.
+    return options.quality === undefined
+      ? resized.to(options.format).encode()
+      : resized.to(options.format, { quality: options.quality }).encode();
+  }
+
+  async describe(
+    base64: string,
+  ): Promise<{ width: number; height: number; format: string }> {
+    const bytes = new Uint8Array(Buffer.from(base64, 'base64'));
+    const meta = await this.images.metadata(bytes);
+    return { width: meta.width, height: meta.height, format: meta.format };
+  }
+
+  async demonstrate(): Promise<void> {
+    const { images, logger } = this;
+    const seed = new Uint8Array(Buffer.from(SEED_PNG_BASE64, 'base64'));
+
+    const seeded = await images.load(seed);
+    const source = await seeded
+      .resize(64, 48, { fit: ImageFit.FILL })
+      .to(EncodableFormat.PNG)
+      .toBytes();
+    logger.info(
+      `quality=${this.config.quality}, generated a 64x48 source from the 4x4 seed ` +
+        `at runtime: ${source.byteLength} bytes, detected ${images.detect(source)}`,
+    );
+
+    // Content-based: the container comes from magic bytes, never a filename. And
+    // this is a header read, not a decode - a truncated file would still answer.
+    const meta = await images.metadata(source);
+    logger.info(`metadata -> ${meta.width}x${meta.height} ${meta.format}`);
+
+    const pipeline = await images.load(source);
+    const thumb = await pipeline
+      .resize(16, 16, { fit: ImageFit.INSIDE })
+      .encode();
+    logger.info(
+      `resize 16x16 inside -> ${thumb.width}x${thumb.height} ${thumb.format}, ` +
+        `${thumb.bytes.byteLength} bytes`,
+    );
+
+    const webp = await pipeline
+      .resize(32)
+      .to(EncodableFormat.WEBP, { quality: 70 })
+      .encode();
+    logger.info(
+      `convert 32px wide -> ${webp.width}x${webp.height} ${webp.mimeType}, ` +
+        `${webp.bytes.byteLength} bytes`,
+    );
+
+    // `Bun.Image` mutates and returns `this`; an ImagePipeline returns a new
+    // value from every operation, so the two resizes above did not collide.
+    const again = await pipeline.sourceMetadata();
+    logger.info(
+      `the pipeline is immutable: the source is still ${again.width}x${again.height} ${again.format}`,
+    );
+  }
+}

package/templates/features/storage/files.controller.ts

@@ -0,0 +1,130 @@
+import {
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  HttpStatusCode,
+  Put,
+  type Input,
+} from '@dunx/http';
+import { LocalStorage, PathTraversalError, Storage } from '@dunx/infra/files';
+import { z } from 'zod';
+
+/**
+ * The key is a query parameter rather than a path segment because keys contain
+ * slashes - `reports/q1.csv` is one key, not two segments. Traversal is rejected
+ * by `Storage` itself rather than by a pattern here, which is the behaviour worth
+ * seeing: try `?key=../../etc/passwd`.
+ */
+const FileKey = z
+  .object({ key: z.string().min(1).max(200) })
+  .meta({ id: 'FileKey', title: 'An object key inside the storage root' });
+
+const WriteFile = z
+  .object({ content: z.string().max(64 * 1024) })
+  .meta({ id: 'WriteFile', title: 'Text to store under the key' });
+
+const listFiles = {
+  query: z.object({
+    prefix: z.string().default(''),
+    glob: z.string().default('**/*'),
+  }),
+} as const;
+const objectKey = { query: FileKey } as const;
+const writeFile = { query: FileKey, body: WriteFile } as const;
+
+/**
+ * Injects `Storage`, never `LocalStorage` - swapping a disk for a bucket is one
+ * `forRoot` call in storage.module.ts and nothing here changes.
+ */
+@Controller('files')
+export class FilesController {
+  constructor(private readonly storage: Storage) {}
+
+  /** `list` is an AsyncIterable so a million objects page rather than accumulate. */
+  @Get('/', listFiles)
+  async list(
+    input: Input<typeof listFiles>,
+  ): Promise<{ root: string; keys: readonly string[] }> {
+    const keys: string[] = [];
+    for await (const entry of this.storage.list({
+      prefix: input.query.prefix,
+      glob: input.query.glob,
+    })) {
+      keys.push(entry.key);
+    }
+    // The contract cannot promise a root - narrowing to the backend is how you
+    // reach anything backend-specific.
+    const root =
+      this.storage instanceof LocalStorage ? this.storage.root : '(remote)';
+    return { root, keys: keys.sort() };
+  }
+
+  @Get('/object', objectKey)
+  async read(
+    input: Input<typeof objectKey>,
+  ): Promise<{ key: string; size: number; type: string; content: string }> {
+    const { key } = input.query;
+    await this.present(key);
+    const stat = await this.storage.stat(key);
+    return {
+      key,
+      size: stat.size,
+      type: stat.type,
+      content: await this.storage.read(key),
+    };
+  }
+
+  @Put('/object', writeFile)
+  async write(
+    input: Input<typeof writeFile>,
+  ): Promise<{ key: string; bytes: number }> {
+    const { key } = input.query;
+    try {
+      return { key, bytes: await this.storage.write(key, input.body.content) };
+    } catch (error) {
+      if (!(error instanceof PathTraversalError)) throw error;
+      throw new HttpError(HttpStatusCode.BAD_REQUEST, error.message);
+    }
+  }
+
+  @Delete('/object', objectKey)
+  async remove(input: Input<typeof objectKey>): Promise<{ deleted: boolean }> {
+    const { key } = input.query;
+    await this.present(key);
+    await this.storage.delete(key);
+    return { deleted: true };
+  }
+
+  /**
+   * Nothing signs bytes on a local disk, so this refuses with the backend's own
+   * message instead of handing back a URL that cannot work.
+   */
+  @Get('/presign', objectKey)
+  async presign(input: Input<typeof objectKey>): Promise<{ url: string }> {
+    const { key } = input.query;
+    await this.present(key);
+    try {
+      return { url: this.storage.presign(key) };
+    } catch (error) {
+      throw new HttpError(
+        HttpStatusCode.NOT_IMPLEMENTED,
+        (error as Error).message,
+      );
+    }
+  }
+
+  /**
+   * A traversal is a bad request, not a server fault - `Storage` rejects it
+   * before any syscall, and without this it would surface as a 500.
+   */
+  private async present(key: string): Promise<void> {
+    try {
+      if (await this.storage.exists(key)) return;
+    } catch (error) {
+      if (!(error instanceof PathTraversalError)) throw error;
+      throw new HttpError(HttpStatusCode.BAD_REQUEST, error.message);
+    }
+    throw new HttpError(HttpStatusCode.NOT_FOUND, `No object "${key}"`);
+  }
+}

package/templates/features/storage/storage.module.ts

@@ -0,0 +1,21 @@
+import { Module } from '@dunx/core';
+import { FilesModule, LocalStorageOptions } from '@dunx/infra/files';
+import { FilesController } from './files.controller.js';
+import { Uploads } from './uploads.service.js';
+import { Workspace } from './workspace.js';
+
+@Module({
+  imports: [
+    // The root has to exist before `LocalStorageOptions` names it, and creating
+    // it is async - which is the whole reason `forRootAsync` takes a factory that
+    // may await and may inject.
+    FilesModule.forRootAsync({
+      useFactory: async (workspace: Workspace) =>
+        new LocalStorageOptions(await workspace.create()),
+      inject: [Workspace],
+    }),
+  ],
+  controllers: [FilesController],
+  providers: [Workspace, Uploads],
+})
+export class StorageModule {}

package/templates/features/storage/uploads.service.ts

@@ -0,0 +1,66 @@
+import { Logger } from '@dunx/core';
+import { LocalStorage, Storage } from '@dunx/infra/files';
+
+const REPORT = 'reports/q1.csv';
+const ARCHIVE = 'reports/q2.csv';
+
+/**
+ * Injects `Storage`, never `LocalStorage` - swapping a disk for a bucket is then
+ * one `forRoot` call in storage.module.ts and nothing here changes.
+ */
+export class Uploads {
+  constructor(
+    private readonly storage: Storage,
+    private readonly logger: Logger,
+  ) {}
+
+  async demonstrate(): Promise<void> {
+    const { storage, logger } = this;
+
+    // The contract cannot promise a root - narrowing to the backend is how you
+    // reach anything backend-specific.
+    if (storage instanceof LocalStorage) {
+      logger.info(`root ${storage.root} (an OS temp dir, removed on shutdown)`);
+    }
+
+    const bytes = await storage.write(REPORT, 'quarter,amount\nQ1,100\n');
+    logger.info(`write  ${REPORT} -> ${bytes} bytes`);
+    await storage.write(ARCHIVE, 'quarter,amount\nQ2,140\n');
+
+    logger.info(
+      `read   ${REPORT} -> ${JSON.stringify(await storage.read(REPORT))}`,
+    );
+
+    const stat = await storage.stat(REPORT);
+    logger.info(`stat   ${REPORT} -> ${stat.size} bytes, ${stat.type}`);
+
+    // Bun.Glob, as an AsyncIterable so a million objects page rather than
+    // accumulate. Order is the filesystem's, hence the sort.
+    const keys: string[] = [];
+    for await (const entry of storage.list({
+      prefix: 'reports',
+      glob: '*.csv',
+    })) {
+      keys.push(entry.key);
+    }
+    logger.info(`glob   reports/*.csv -> ${JSON.stringify(keys.sort())}`);
+
+    await storage.delete(ARCHIVE);
+    logger.info(`delete ${ARCHIVE} -> exists=${await storage.exists(ARCHIVE)}`);
+
+    // Rejected before any syscall, not sanitised into something that "works".
+    try {
+      await storage.read('../../etc/passwd');
+    } catch (error) {
+      logger.info(`traversal rejected: ${(error as Error).message}`);
+    }
+
+    // Nothing signs bytes on a local disk, so this refuses instead of handing
+    // back a URL that cannot work.
+    try {
+      storage.presign(REPORT);
+    } catch (error) {
+      logger.info(`presign refused: ${(error as Error).message}`);
+    }
+  }
+}

package/templates/features/storage/workspace.ts

@@ -0,0 +1,33 @@
+import { Logger } from '@dunx/core';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { OnShutdown } from '@dunx/core';
+
+/**
+ * Owns a scratch directory under the OS temp dir - never inside the repo - and
+ * removes it on shutdown, so two consecutive `bun start` runs cannot see each
+ * other's bytes.
+ *
+ * The storage factory injects this, so it is constructed *before* `Storage`, and
+ * reverse-order shutdown therefore removes the directory after everything that
+ * writes into it has drained.
+ */
+export class Workspace implements OnShutdown {
+  #root: string | undefined;
+
+  constructor(private readonly logger: Logger) {}
+
+  /** `mkdtemp`, so a concurrent run gets its own directory rather than sharing. */
+  async create(): Promise<string> {
+    this.#root ??= await mkdtemp(join(tmpdir(), 'dunx-full-'));
+    return this.#root;
+  }
+
+  async onShutdown(): Promise<void> {
+    if (this.#root === undefined) return;
+    await rm(this.#root, { recursive: true, force: true });
+    this.logger.info(`workspace removed: ${this.#root}`);
+    this.#root = undefined;
+  }
+}

package/templates/features/users/users.controller.ts

@@ -0,0 +1,47 @@
+import {
+  Controller,
+  Get,
+  HttpError,
+  HttpStatusCode,
+  Post,
+  type Input,
+} from '@dunx/http';
+import type { User } from './users.repository.js';
+import { createUser, listUsers, oneUser } from './users.schemas.js';
+import { UsersService } from './users.service.js';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly users: UsersService) {}
+
+  // `Input<typeof listUsers>` has to be written out - a standard method decorator
+  // can check a parameter's type but cannot contextually type an unannotated one.
+  // Every field type still comes from the schema, so nothing is declared twice.
+  @Get('/', listUsers)
+  list(input: Input<typeof listUsers>): Promise<readonly User[]> {
+    return this.users.findAll(input.query.limit, input.query.q);
+  }
+
+  @Get('/:id', oneUser)
+  async one(input: Input<typeof oneUser>): Promise<User> {
+    // Already a number: the params schema coerced it before this ran.
+    const user = await this.users.find(input.params.id);
+    if (user === null) {
+      throw new HttpError(
+        HttpStatusCode.NOT_FOUND,
+        `No user ${input.params.id}`,
+      );
+    }
+    return user;
+  }
+
+  // No req.json(), no Response.json(), no status - the body arrives validated and
+  // typed, and 201 is the POST default.
+  @Post('/', createUser)
+  create(input: Input<typeof createUser>): Promise<User> {
+    return this.users.create(
+      input.body.name,
+      input.body.tags.map((tag) => tag.label),
+    );
+  }
+}

package/templates/features/users/users.demo.ts

@@ -0,0 +1,62 @@
+import { Logger } from '@dunx/core';
+import { z } from 'zod';
+import { CreateUser } from './users.schemas.js';
+import { UsersService } from './users.service.js';
+
+const post = (url: string, body: unknown): Promise<Response> =>
+  fetch(new URL('api/users', url), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+const show = async (response: Response): Promise<string> =>
+  `${response.status} ${JSON.stringify(await response.json())}`;
+
+export class UsersDemo {
+  constructor(
+    private readonly users: UsersService,
+    private readonly logger: Logger,
+  ) {}
+
+  async demonstrate(url: string): Promise<void> {
+    const { logger } = this;
+    logger.info(await this.users.summary());
+
+    const listed = await fetch(new URL('api/users', url));
+    logger.info(`GET /api/users -> ${await show(listed)}`);
+
+    const paged = await fetch(new URL('api/users?limit=1&q=ad', url));
+    logger.info(
+      `GET /api/users?limit=1&q=ad -> ${await show(paged)} (query coerced by zod)`,
+    );
+
+    const one = await fetch(new URL('api/users/1', url));
+    logger.info(
+      `GET /api/users/1 -> ${await show(one)} (params.id coerced to a number)`,
+    );
+
+    const created = await post(url, {
+      name: 'linus',
+      tags: [{ label: 'kernel' }],
+    });
+    logger.info(`POST /api/users -> ${await show(created)}`);
+
+    // zod rejects, @dunx/http turns the issues into a 400 body.
+    const rejected = await post(url, { name: 42 });
+    logger.info(`POST /api/users {"name":42} -> ${await show(rejected)}`);
+
+    // A nested issue's path is flattened to dots - the same rendering OpenAPI
+    // clients expect.
+    const nested = await post(url, { name: 'ada', tags: [{ label: '' }] });
+    logger.info(
+      `POST /api/users {"tags":[{"label":""}]} -> ${await show(nested)}`,
+    );
+
+    // The zod-specific half, and the path OpenAPI generation will take: `id` from
+    // .meta() names the $defs entry, `title` lands inline.
+    logger.info(
+      `z.toJSONSchema(CreateUser) -> ${JSON.stringify(z.toJSONSchema(CreateUser))}`,
+    );
+  }
+}

package/templates/features/users/users.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@dunx/core';
+import { UsersController } from './users.controller.js';
+import { UsersDemo } from './users.demo.js';
+import { UsersRepository } from './users.repository.js';
+import { UsersService } from './users.service.js';
+
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService, UsersRepository, UsersDemo],
+})
+export class UsersModule {}

package/templates/features/users/users.repository.ts

@@ -0,0 +1,59 @@
+import { SyncDatabase } from '@dunx/infra/db';
+import { eq, like, sql } from 'drizzle-orm';
+import * as schema from '../database/schema.js';
+import { users, type User } from '../database/schema.js';
+
+// The row type comes from the table, so the controller and the service import one
+// definition rather than a hand-written copy of the columns.
+export type { User };
+
+export class UsersRepository {
+  /**
+   * `SyncDatabase` because `DatabaseModule` configured synchronous mode; it is
+   * drizzle's `BunSQLiteDatabase` with a name the container can tell apart.
+   * `@dunx/transform` records the bare type name - a real runtime class, so a usable
+   * token - and ignores the type argument, so the schema types survive injection.
+   *
+   * Every method below is `async` although bun-sqlite executes synchronously: the
+   * HTTP layer awaits them, and moving this table to the pooled backend then costs
+   * no signature change. `Ledger.transferSync` is what refusing that trade looks
+   * like.
+   */
+  constructor(private readonly db: SyncDatabase<typeof schema>) {}
+
+  async migrate(): Promise<void> {
+    this.db.run(sql`CREATE TABLE IF NOT EXISTS users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL UNIQUE
+    )`);
+  }
+
+  /** One statement for every name; `name` is UNIQUE, so a repeat boot is a no-op. */
+  async seed(names: readonly string[]): Promise<void> {
+    this.db
+      .insert(users)
+      .values(names.map((name) => ({ name })))
+      .onConflictDoNothing()
+      .run();
+  }
+
+  async findAll(limit: number, q?: string): Promise<readonly User[]> {
+    return this.db
+      .select()
+      .from(users)
+      .where(like(users.name, q === undefined ? '%' : `%${q}%`))
+      .orderBy(users.id)
+      .limit(limit)
+      .all();
+  }
+
+  /** `.get()` is `undefined` for no row; the controller's 404 turns on `null`. */
+  async find(id: number): Promise<User | null> {
+    return this.db.select().from(users).where(eq(users.id, id)).get() ?? null;
+  }
+
+  /** `.returning()`, so the id is the one the database wrote. */
+  async create(name: string): Promise<User> {
+    return this.db.insert(users).values({ name }).returning().get();
+  }
+}

package/templates/features/users/users.schemas.ts

@@ -0,0 +1,68 @@
+import type { RouteSchemas } from '@dunx/http';
+import { z } from 'zod';
+
+/**
+ * Real zod, dropped straight into a route's options: `z.object()` already carries
+ * `~standard` (vendor `zod`, version 1), which is the entire contract
+ * `@dunx/http` validates against - so nothing adapts anything, and the framework
+ * still depends on no validator.
+ *
+ * `.meta({ id })` names the definition zod emits under `$defs`, which is the slot
+ * OpenAPI calls `components/schemas`. `.meta({ title })` lands inline. See
+ * `UsersDemo` for the generated document.
+ */
+export const Tag = z
+  .object({ label: z.string().min(1) })
+  .meta({ id: 'Tag', title: 'A label attached to a user' });
+
+export const CreateUser = z
+  .object({
+    name: z.string().min(1).max(40),
+    tags: z.array(Tag).default([]),
+  })
+  .meta({ id: 'CreateUser', title: 'Create a user' });
+
+/** Path params arrive as strings; `z.coerce` is where `:id` becomes a number. */
+export const UserIndex = z
+  .object({ id: z.coerce.number().int().min(1) })
+  .meta({ id: 'UserIndex', title: 'A user id in the path' });
+
+export const ListUsers = z
+  .object({
+    q: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(50).default(10),
+  })
+  .meta({ id: 'ListUsers', title: 'Filter and page the user list' });
+
+/**
+ * The response side. Same Standard Schema contract as a request, so it hoists into
+ * `components/schemas` the same way - but it is **never validated**: it documents
+ * what comes back, and the handler's return type is what checks it.
+ */
+export const User = z
+  .object({
+    id: z.number().int(),
+    name: z.string(),
+    tags: z.array(z.string()),
+  })
+  .meta({ id: 'User', title: 'A stored user' });
+
+export const NotFound = z
+  .object({ error: z.string(), status: z.literal(404) })
+  .meta({ id: 'NotFound', title: 'Nothing at that id' });
+
+// Declaring a schema is what makes the matching `input` field exist, get parsed
+// and get validated. `satisfies` keeps the literal types `Input<>` reads.
+export const listUsers = {
+  query: ListUsers,
+  response: { 200: z.array(User) },
+} as const satisfies RouteSchemas;
+export const oneUser = {
+  params: UserIndex,
+  response: { 200: User, 404: NotFound },
+} as const satisfies RouteSchemas;
+// No status: POST defaults to 201, every other verb to 200.
+export const createUser = {
+  body: CreateUser,
+  response: { 201: User },
+} as const satisfies RouteSchemas;

package/templates/features/users/users.service.ts

@@ -0,0 +1,46 @@
+import { Logger } from '@dunx/core';
+import type { OnInit, OnShutdown } from '@dunx/core';
+import { AppConfigService } from '../config.js';
+import { UsersRepository, type User } from './users.repository.js';
+
+export class UsersService implements OnInit, OnShutdown {
+  // `ConfigService<AppConfig>` injects because the transform records the bare
+  // name of a generic annotation - the type argument costs nothing at runtime.
+  constructor(
+    private readonly repository: UsersRepository,
+    private readonly logger: Logger,
+    private readonly config: AppConfigService,
+  ) {}
+
+  /** `onInit` is awaited, so the schema exists before the first request arrives. */
+  async onInit(): Promise<void> {
+    await this.repository.migrate();
+    await this.repository.seed(this.config.get('seedUsers'));
+    this.logger.info(`${this.config.get('appName')}: users ready`);
+  }
+
+  onShutdown(): void {
+    this.logger.info('users draining');
+  }
+
+  findAll(limit: number, q?: string): Promise<readonly User[]> {
+    return this.repository.findAll(limit, q);
+  }
+
+  find(id: number): Promise<User | null> {
+    return this.repository.find(id);
+  }
+
+  create(name: string, tags: readonly string[]): Promise<User> {
+    const labels = tags.length === 0 ? '' : ` [${tags.join(', ')}]`;
+    this.logger.info(
+      `${this.config.get('appName')}: creating ${name}${labels}`,
+    );
+    return this.repository.create(name);
+  }
+
+  async summary(): Promise<string> {
+    const users = await this.repository.findAll(50);
+    return `${users.length} users: ${users.map((user) => user.name).join(', ')}`;
+  }
+}

package/templates/minimal/_bunfig.toml

@@ -0,0 +1,7 @@
+# The one line that makes constructor injection work. The compiler plugin records
+# each class's constructor parameter types so the container can resolve them.
+# Without it, providers are built with no arguments and boot fails saying so.
+preload = ["@dunx/transform/preload"]
+
+[test]
+preload = ["@dunx/transform/preload"]