typescript-express-router-split

Answer

Target layout. The 700-line api/routes/assets.ts (default-export Router) becomes a module directory. The original path is preserved by a shim, so every existing importer (import assets from ".../routes/assets.js") keeps resolving to the same file — zero importer changes.

api/routes/
├── assets.ts            # shim: re-export the built router
└── assets/
    ├── index.ts         # builds Router, registers 6 routes in original order
    ├── schemas.ts       # zod request/query validators
    ├── mime.ts          # allowed MIME set + extension helpers
    ├── response.ts      # HttpError + ok()/fail() response helpers
    ├── upload.ts        # multer config + module-load fs.mkdir side effect
    └── handlers.ts      # the 6 route handler functions

1. Shim — api/routes/assets.ts (the whole file, preserving the default-export contract):

export { default } from "./assets/index.js";

2. Router assembly — api/routes/assets/index.ts (6 routes, original order; static /types before parametric /:id):

import { Router } from "express";
import {
  createAsset,
  deleteAsset,
  getAsset,
  listAssetTypes,
  listAssets,
  updateAsset,
} from "./handlers.js";
import { upload } from "./upload.js";

const router = Router();

router.get("/", listAssets);                  // 1. GET  /         list
router.post("/", upload.single("file"), createAsset); // 2. POST /         create (multipart)
router.get("/types", listAssetTypes);         // 3. GET  /types     static — before /:id
router.get("/:id", getAsset);                 // 4. GET  /:id
router.patch("/:id", updateAsset);            // 5. PATCH /:id
router.delete("/:id", deleteAsset);           // 6. DELETE /:id

export default router;

3. Schemas — api/routes/assets/schemas.ts:

import { z } from "zod";

export const listQuerySchema = z.object({
  type: z.string().trim().optional(),
  limit: z.coerce.number().int().min(1).max(100).default(50),
  offset: z.coerce.number().int().min(0).default(0),
});

export const createAssetSchema = z.object({
  title: z.string().trim().min(1).max(200),
  description: z.string().trim().max(2000).optional(),
  tags: z.array(z.string().trim().min(1)).max(20).optional(),
});

export const updateAssetSchema = createAssetSchema.partial();

export const assetIdSchema = z.object({ id: z.string().uuid() });

4. MIME — api/routes/assets/mime.ts:

export const ALLOWED_MIME_TYPES = new Set([
  "image/jpeg", "image/png", "image/webp", "image/gif",
  "application/pdf", "text/plain",
]);

const EXT_TO_MIME: Record<string, string> = {
  ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png",
  ".webp": "image/webp", ".gif": "image/gif", ".pdf": "application/pdf",
  ".txt": "text/plain",
};

export function isAllowedMime(mime: string): boolean {
  return ALLOWED_MIME_TYPES.has(mime);
}

export function mimeFromExtension(ext: string): string | undefined {
  return EXT_TO_MIME[ext.toLowerCase()];
}

5. Response helpers — api/routes/assets/response.ts:

import type { Response } from "express";

export class HttpError extends Error {
  constructor(
    public readonly status: number,
    public readonly code: string,
    message?: string,
  ) {
    super(message ?? code);
    this.name = "HttpError";
  }
}

export function ok<T>(res: Response, data: T, status = 200): void {
  res.status(status).json({ ok: true, data });
}

export function fail(res: Response, error: unknown): void {
  if (error instanceof HttpError) {
    res.status(error.status).json({ ok: false, code: error.code, message: error.message });
    return;
  }
  console.error(error);
  res.status(500).json({ ok: false, code: "internal_error", message: "Internal server error" });
}

6. Upload — api/routes/assets/upload.ts — multer plus the module-load fs.mkdir side effect, preserved verbatim so the directory exists as soon as the module graph loads (same timing as the original file):

import { mkdirSync } from "node:fs";
import path from "node:path";
import multer from "multer";
import { randomUUID } from "node:crypto";
import { HttpError } from "./response.js";
import { isAllowedMime } from "./mime.js";

export const UPLOAD_DIR = path.resolve(process.cwd(), "storage", "assets");

// Module-load side effect (unchanged from original): ensure the upload
// directory exists before the first request, not lazily at request time.
mkdirSync(UPLOAD_DIR, { recursive: true });

const storage = multer.diskStorage({
  destination: (_req, _file, cb) => cb(null, UPLOAD_DIR),
  filename: (_req, file, cb) => cb(null, `${randomUUID()}${path.extname(file.originalname)}`),
});

export const upload = multer({
  storage,
  limits: { fileSize: 25 * 1024 * 1024 },
  fileFilter: (_req, file, cb) => {
    if (isAllowedMime(file.mimetype)) cb(null, true);
    else cb(new HttpError(415, "unsupported_media_type"));
  },
});

7. Handlers — api/routes/assets/handlers.ts:

import type { Request, Response } from "express";
import {
  createAsset as createAssetRecord,
  deleteAsset as deleteAssetRecord,
  getAsset as getAssetRecord,
  listAssetTypes as listAssetTypesRecord,
  listAssets as listAssetsRecord,
  updateAsset as updateAssetRecord,
} from "../../../lib/assets-store.js";          // ../../ → ../../../
import { assetIdSchema, createAssetSchema, listQuerySchema, updateAssetSchema } from "./schemas.js";
import { mimeFromExtension } from "./mime.js";
import { fail, HttpError, ok } from "./response.js";

export async function listAssets(req: Request, res: Response): Promise<void> {
  try {
    const query = listQuerySchema.parse(req.query);
    ok(res, await listAssetsRecord(query));
  } catch (error) {
    fail(res, error);
  }
}

export async function listAssetTypes(req: Request, res: Response): Promise<void> {
  try {
    ok(res, await listAssetTypesRecord());
  } catch (error) {
    fail(res, error);
  }
}

export async function createAsset(req: Request, res: Response): Promise<void> {
  try {
    if (!req.file) throw new HttpError(400, "missing_file");
    const body = createAssetSchema.parse(req.body);
    const record = await createAssetRecord({
      ...body,
      storedPath: req.file.path,
      size: req.file.size,
      mime: req.file.mimetype,
    });
    ok(res, record, 201);
  } catch (error) {
    fail(res, error);
  }
}

export async function getAsset(req: Request, res: Response): Promise<void> {
  try {
    const { id } = assetIdSchema.parse(req.params);
    ok(res, await getAssetRecord(id));
  } catch (error) {
    fail(res, error);
  }
}

export async function updateAsset(req: Request, res: Response): Promise<void> {
  try {
    const { id } = assetIdSchema.parse(req.params);
    const body = updateAssetSchema.parse(req.body);
    ok(res, await updateAssetRecord(id, body));
  } catch (error) {
    fail(res, error);
  }
}

export async function deleteAsset(req: Request, res: Response): Promise<void> {
  try {
    const { id } = assetIdSchema.parse(req.params);
    await deleteAssetRecord(id);
    res.status(204).end();
  } catch (error) {
    fail(res, error);
  }
}

Import-depth shift. Every intra-package relative import in the moved code steps one level deeper: from api/routes/assets.ts a lib import was ../../lib/assets-store.js; from api/routes/assets/handlers.ts it is ../../../lib/assets-store.js. The only outward-facing file is the shim, which imports nothing but ./assets/index.js, so no importer of the router needs to change.