@tymber/common 0.0.1-alpha.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,54 @@
+export { Component, type Ctor, ComponentFactory, INJECT } from "./Component.js";
+export {
+  type InternalUserId,
+  type UserId,
+  type InternalGroupId,
+  type GroupId,
+  type Role,
+  type ConnectedUser,
+  type AdminUserId,
+  type Admin,
+  type Context,
+  emptyContext,
+} from "./Context.js";
+export { ConfigService } from "./ConfigService.js";
+export { DB, DuplicateKeyError } from "./DB.js";
+export { EventEmitter } from "./EventEmitter.js";
+export {
+  PubSubService,
+  NodeClusterPubSubService,
+  initPrimary,
+} from "./PubSubService.js";
+export { I18nService } from "./I18nService.js";
+export { Endpoint, AdminEndpoint } from "./Endpoint.js";
+export { type HttpContext } from "./HttpContext.js";
+export { App } from "./App.js";
+export {
+  type Module,
+  type AppInit,
+  ModuleDefinitions,
+  type Route,
+} from "./Module.js";
+export { View, AdminView } from "./View.js";
+export { Middleware } from "./Middleware.js";
+export { Repository, type Page, EntityNotFoundError } from "./Repository.js";
+export { TemplateService } from "./TemplateService.js";
+
+export { createCookie, parseCookieHeader } from "./contrib/cookie.js";
+
+export { AJV_INSTANCE } from "./utils/ajv.js";
+export { camelToSnakeCase } from "./utils/camelToSnakeCase.js";
+export { createDebug } from "./utils/createDebug.js";
+export { createTestApp, type BaseTestContext } from "./utils/createTestApp.js";
+export { escapeValue } from "./utils/escapeValue.js";
+export { FS } from "./utils/fs.js";
+export { isAdmin } from "./utils/isAdmin.js";
+export { isProduction } from "./utils/isProduction.js";
+export { randomId } from "./utils/randomId.js";
+export { randomUUID } from "./utils/randomUUID.js";
+export { snakeToCamelCase } from "./utils/snakeToCamelCase.js";
+export { sortBy } from "./utils/sortBy.js";
+export { sql, Statement } from "./utils/sql.js";
+export { toNodeHandler } from "./utils/toNodeHandler.js";
+export { type Brand } from "./utils/types.js";
+export { waitFor } from "./utils/waitFor.js";

package/src/utils/ajv.ts

@@ -0,0 +1,13 @@
+import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
+
+// reference: https://ajv.js.org/api.html
+
+export const AJV_INSTANCE = new Ajv({
+  useDefaults: true,
+  coerceTypes: true,
+  removeAdditional: true,
+});
+
+// @ts-expect-error FIXME
+addFormats(AJV_INSTANCE);

package/src/utils/camelToSnakeCase.ts

@@ -0,0 +1,3 @@
+export function camelToSnakeCase(str: string) {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}

package/src/utils/computeBaseUrl.ts

@@ -0,0 +1,46 @@
+function removeQuotes(str: string) {
+  if (str.startsWith('"') && str.endsWith('"')) {
+    return str.slice(1, -1);
+  } else {
+    return str;
+  }
+}
+
+function parseForwardedHeader(header: string) {
+  const parts = header.split(";").map((part) => part.trim());
+  const parsed = {} as Record<string, string>;
+
+  for (const part of parts) {
+    const [key, value] = part.split("=");
+
+    if (key && value) {
+      parsed[key.toLowerCase()] = removeQuotes(value);
+    }
+  }
+
+  return `${parsed.proto}://${parsed.host}`;
+}
+
+export function computeBaseUrl(headers: Headers) {
+  const forwardedHeader = headers.get("forwarded");
+
+  if (forwardedHeader) {
+    const baseUrl = parseForwardedHeader(forwardedHeader);
+    if (baseUrl) {
+      return baseUrl;
+    }
+  }
+
+  const forwardedProto = headers.get("x-forwarded-proto");
+  const forwardedHost = headers.get("x-forwarded-host");
+
+  if (forwardedProto && forwardedHost) {
+    const proto = forwardedProto.split(",");
+    const host = forwardedHost.split(",");
+    return `${proto[0]}://${host[0]}`;
+  }
+
+  const host = headers.get("host");
+
+  return `http://${host}`;
+}

package/src/utils/computeContentType.ts

@@ -0,0 +1,17 @@
+const CONTENT_TYPES = new Map<string, string>([
+  ["html", "text/html"],
+  ["css", "text/css"],
+  ["js", "application/javascript"],
+  ["json", "application/json"],
+  ["png", "image/png"],
+  ["jpg", "image/jpeg"],
+  ["gif", "image/gif"],
+  ["svg", "image/svg+xml"],
+]);
+
+export function computeContentType(path: string) {
+  const i = path.lastIndexOf(".");
+  if (i === -1) return "application/octet-stream";
+  const extension = path.substring(i + 1);
+  return CONTENT_TYPES.get(extension) || "application/octet-stream";
+}

package/src/utils/createDebug.ts

@@ -0,0 +1,5 @@
+import { debuglog } from "node:util";
+
+export function createDebug(module: string) {
+  return debuglog(`tymber:${module}`);
+}

package/src/utils/createTestApp.ts

@@ -0,0 +1,84 @@
+import { DB } from "../DB.js";
+import { createServer, Server } from "node:http";
+import { type AddressInfo } from "node:net";
+import { type Module } from "../Module.js";
+import { App } from "../App.js";
+import { toNodeHandler } from "./toNodeHandler.js";
+
+const CLOSE_DELAY_MS = 200;
+
+export interface BaseTestContext {
+  baseUrl: string;
+  db: DB;
+  close: () => Promise<void>;
+}
+
+interface SharedTestContext {
+  httpServer: Server;
+  baseUrl: string;
+  db: DB;
+}
+
+let sharedTestContext: SharedTestContext | undefined;
+let closeTimer: NodeJS.Timeout | undefined;
+
+export async function createTestApp(
+  initDB: () => DB | Promise<DB>,
+  modules: Module[],
+): Promise<BaseTestContext> {
+  if (!sharedTestContext) {
+    const httpServer = createServer();
+
+    const [port, db] = await Promise.all([
+      startHttpServer(httpServer),
+      initDB(),
+    ]);
+    const baseUrl = `http://localhost:${port}`;
+
+    sharedTestContext = {
+      httpServer,
+      baseUrl,
+      db,
+    };
+  }
+
+  const { httpServer, baseUrl, db } = sharedTestContext;
+  const app = await App.create({
+    components: [db],
+    modules,
+  });
+
+  httpServer.removeAllListeners("request");
+  httpServer.on("request", toNodeHandler(app.fetch.bind(app)));
+
+  return {
+    baseUrl,
+    db,
+    async close() {
+      clearTimeout(closeTimer);
+
+      closeTimer = setTimeout(async () => {
+        if (sharedTestContext) {
+          const { httpServer } = sharedTestContext;
+          sharedTestContext = undefined;
+
+          await Promise.all([closeHttpServer(httpServer), app.close()]);
+        }
+      }, CLOSE_DELAY_MS);
+    },
+  };
+}
+
+function startHttpServer(httpServer: Server) {
+  return new Promise<number>((resolve) => {
+    httpServer.listen(0, () => {
+      resolve((httpServer.address() as AddressInfo).port);
+    });
+  });
+}
+
+function closeHttpServer(httpServer: Server) {
+  return new Promise<void>((resolve) => {
+    httpServer.close(() => resolve());
+  });
+}

package/src/utils/escapeValue.ts

@@ -0,0 +1,3 @@
+export function escapeValue(value: string) {
+  return value.replaceAll(/([~%_])/g, "~$1");
+}

package/src/utils/fs.ts

@@ -0,0 +1,15 @@
+import { join as nodeJoin } from "node:path";
+import { readdir, readFile as nodeReadFile } from "node:fs/promises";
+import { createReadStream as nodeCreateReadStream } from "node:fs";
+
+// group Node.js-specific methods
+export const FS = {
+  join: (...paths: string[]) => nodeJoin(...paths),
+  createReadStream: (path: string) => nodeCreateReadStream(path),
+  readFile: (path: string) => nodeReadFile(path, "utf8"),
+  readDirRecursively: (path: string) =>
+    readdir(path, {
+      encoding: "utf8",
+      recursive: true,
+    }),
+};

package/src/utils/isAdmin.ts

@@ -0,0 +1,5 @@
+import { type HttpContext } from "../HttpContext.js";
+
+export function isAdmin(ctx: HttpContext) {
+  return ctx.admin !== undefined;
+}

package/src/utils/isProduction.ts

@@ -0,0 +1,2 @@
+export const isProduction =
+  process.env.NODE_ENV === "production" || process.env.ENV === "production";

package/src/utils/loadModules.ts

@@ -0,0 +1,105 @@
+import { Component, ComponentFactory, type Ctor } from "../Component.js";
+import type { Module, ModuleDefinition } from "../Module.js";
+import { type HttpMethod } from "../Router.js";
+import { AdminEndpoint, Endpoint } from "../Endpoint.js";
+import { AdminView, View } from "../View.js";
+import { Middleware } from "../Middleware.js";
+import { createDebug } from "./createDebug.js";
+
+const debug = createDebug("loadModules");
+
+export async function loadModules(
+  componentFactory: ComponentFactory,
+  modules: Module[],
+) {
+  const moduleDefinitions = [];
+
+  for (const module of modules) {
+    const moduleDefinition: ModuleDefinition = {
+      name: module.name,
+      version: module.version,
+      assetsDir: module.assetsDir,
+      adminSidebarItems: module.adminSidebarItems,
+
+      endpoints: [],
+      views: [],
+      adminEndpoints: [],
+      adminViews: [],
+      middlewares: [],
+    };
+
+    const appInit = {
+      component<T extends Component>(ctor: Ctor<T>) {
+        debug("adding component %s", ctor.name);
+        componentFactory.register(ctor);
+      },
+
+      endpoint: (method: HttpMethod, path: string, ctor: Ctor<Endpoint>) => {
+        debug("adding endpoint %s %s", method, path);
+        componentFactory.register(ctor, (handler) => {
+          moduleDefinition.endpoints.push({
+            method,
+            path,
+            handlerName: ctor.name,
+            handler,
+          });
+        });
+      },
+
+      view: (path: string, ctor: Ctor<View>) => {
+        debug("adding view %s", path);
+        componentFactory.register(ctor, (handler) => {
+          moduleDefinition.views.push({
+            method: "GET",
+            path,
+            handlerName: ctor.name,
+            handler,
+          });
+        });
+      },
+
+      adminEndpoint: (
+        method: HttpMethod,
+        path: string,
+        ctor: Ctor<AdminEndpoint>,
+      ) => {
+        debug("adding admin endpoint %s %s", method, path);
+        componentFactory.register(ctor, (handler) => {
+          moduleDefinition.adminEndpoints.push({
+            method,
+            path,
+            handlerName: ctor.name,
+            handler,
+          });
+        });
+      },
+
+      adminView: (path: string, ctor: Ctor<AdminView>) => {
+        debug("adding admin view %s", path);
+        componentFactory.register(ctor, (handler) => {
+          moduleDefinition.adminViews.push({
+            method: "GET",
+            path,
+            handlerName: ctor.name,
+            handler,
+          });
+        });
+      },
+
+      middleware: (ctor: Ctor<Middleware>) => {
+        debug("adding middleware %s", ctor.name);
+
+        componentFactory.register(ctor, (instance) => {
+          moduleDefinition.middlewares.push(instance);
+        });
+      },
+    };
+
+    debug("loading module %s", module.name);
+    module.init(appInit);
+
+    moduleDefinitions.push(moduleDefinition);
+  }
+
+  return moduleDefinitions;
+}

package/src/utils/randomId.ts

@@ -0,0 +1,5 @@
+import { randomBytes } from "node:crypto";
+
+export function randomId() {
+  return randomBytes(8).toString("hex");
+}

package/src/utils/randomUUID.ts

@@ -0,0 +1,5 @@
+import { randomUUID as nodeRandomUUID } from "node:crypto";
+
+export function randomUUID() {
+  return nodeRandomUUID();
+}

package/src/utils/runMigrations.ts

@@ -0,0 +1,122 @@
+import type { ModuleDefinition } from "../Module.js";
+import { sortBy } from "./sortBy.js";
+import { createDebug } from "./createDebug.js";
+import type { DB } from "../DB.js";
+import { emptyContext } from "../Context.js";
+import { FS } from "./fs.js";
+import { sql } from "./sql.js";
+
+const debug = createDebug("runMigrations");
+
+// example: 0001-create-users-table.sql
+const MIGRATION_REGEX = /^(\d+)-(.*)\.sql$/;
+
+interface Migration {
+  module: string;
+  id: number;
+  name: string;
+  sql: string;
+}
+
+export async function runMigrations(db: DB, modules: ModuleDefinition[]) {
+  const ctx = emptyContext();
+
+  debug("creating migrations table");
+  await db.createMigrationsTable(ctx);
+
+  for (const module of modules) {
+    if (!module.assetsDir) {
+      continue;
+    }
+
+    const migrationFiles: Migration[] = [];
+
+    for (const { filename, absolutePath } of await readMigrationFiles(
+      db,
+      module,
+    )) {
+      let match = MIGRATION_REGEX.exec(filename);
+      if (match) {
+        migrationFiles.push({
+          module: module.name,
+          id: parseInt(match[1], 10),
+          name: match[2],
+          sql: await FS.readFile(absolutePath),
+        });
+      }
+    }
+
+    sortBy(migrationFiles, "id");
+
+    for (const migration of migrationFiles) {
+      await db.startTransaction(ctx, async () => {
+        const result = await db.query(
+          ctx,
+          sql.select().from("t_migrations").where({
+            id: migration.id,
+            module: migration.module,
+          }),
+        );
+
+        if (result.length === 1) {
+          debug(
+            "migration #%d of module %s already applied",
+            migration.id,
+            migration.module,
+          );
+          return;
+        }
+
+        debug(
+          "applying migration #%d of module %s",
+          migration.id,
+          migration.module,
+        );
+        await db.exec(ctx, sql.rawStatement(migration.sql));
+
+        await db.run(
+          ctx,
+          sql
+            .insert()
+            .into("t_migrations")
+            .values([
+              {
+                module: migration.module,
+                id: migration.id,
+                name: migration.name,
+                run_at: new Date(),
+              },
+            ]),
+        );
+      });
+    }
+  }
+}
+
+async function readMigrationFiles(db: DB, module: ModuleDefinition) {
+  const assetsDir = module.assetsDir;
+  if (!assetsDir) {
+    return [];
+  }
+  try {
+    const dbSpecificPath = FS.join(assetsDir, "migrations", db.name);
+    debug("reading files from %s", dbSpecificPath);
+    const filenames = await FS.readDirRecursively(dbSpecificPath);
+    return filenames.map((filename) => ({
+      filename,
+      absolutePath: FS.join(assetsDir, "migrations", db.name, filename),
+    }));
+  } catch (e) {
+    try {
+      const commonPath = FS.join(assetsDir, "migrations");
+      debug("reading files from %s", commonPath);
+      const filenames = await FS.readDirRecursively(commonPath);
+      return filenames.map((filename) => ({
+        filename,
+        absolutePath: FS.join(assetsDir, "migrations", filename),
+      }));
+    } catch (e) {
+      return [];
+    }
+  }
+}

package/src/utils/snakeToCamelCase.ts

@@ -0,0 +1,3 @@
+export function snakeToCamelCase(str: string) {
+  return str.replace(/_([a-z])/g, (letter) => letter[1].toUpperCase());
+}

package/src/utils/sortBy.ts

@@ -0,0 +1,8 @@
+export function sortBy<T>(array: T[], field: keyof T, field2?: keyof T): T[] {
+  return array.sort((a, b) => {
+    if (a[field] === b[field] && field2) {
+      return a[field2] < b[field2] ? -1 : 1;
+    }
+    return a[field] < b[field] ? -1 : 1;
+  });
+}