@tymber/common 0.0.1-alpha.0 → 0.1.0

package/src/Endpoint.ts

@@ -0,0 +1,118 @@
+import { type HttpContext } from "./HttpContext.js";
+import { type ErrorObject, type ValidateFunction } from "ajv";
+import { Handler } from "./Handler.js";
+import { AJV_INSTANCE } from "./utils/ajv.js";
+
+function formatErrors(
+  errors: ErrorObject<string, Record<string, any>, unknown>[],
+) {
+  return errors.map((error) => ({
+    keyword: error.keyword,
+    message: error.message,
+  }));
+}
+
+abstract class BaseEndpoint extends Handler {
+  protected pathParamsSchema?: unknown; // JSONSchemaType<Params>;
+  protected querySchema?: unknown; // JSONSchemaType<Query>;
+  protected payloadSchema?: unknown; // JSONSchemaType<Payload>;
+
+  private validatePathParams?: ValidateFunction;
+  private validateQuery?: ValidateFunction;
+  private validatePayload?: ValidateFunction;
+
+  override doHandle(ctx: HttpContext): Response | Promise<Response> {
+    const { pathParams, query, payload } = ctx;
+
+    if (this.pathParamsSchema && !this.validatePathParams) {
+      this.validatePathParams = AJV_INSTANCE.compile(this.pathParamsSchema);
+    }
+
+    if (this.validatePathParams && !this.validatePathParams(pathParams)) {
+      return this.badRequest("invalid path params", {
+        errors: formatErrors(this.validatePathParams.errors!),
+      });
+    }
+
+    if (this.querySchema && !this.validateQuery) {
+      this.validateQuery = AJV_INSTANCE.compile(this.querySchema);
+    }
+
+    if (this.validateQuery && !this.validateQuery(query)) {
+      return this.badRequest("invalid query params", {
+        errors: formatErrors(this.validateQuery.errors!),
+      });
+    }
+
+    if (this.payloadSchema && !this.validatePayload) {
+      this.validatePayload = AJV_INSTANCE.compile(this.payloadSchema);
+    }
+
+    if (this.validatePayload && !this.validatePayload(payload)) {
+      return this.badRequest("invalid payload", {
+        errors: formatErrors(this.validatePayload.errors!),
+      });
+    }
+
+    if (!this.hasPermission(ctx)) {
+      return Response.json(
+        {
+          message: "forbidden",
+        },
+        {
+          status: 403,
+        },
+      );
+    }
+
+    return this.handle(ctx);
+  }
+
+  protected badRequest(message: string, details?: any) {
+    return Response.json(
+      {
+        message,
+        ...details,
+      },
+      {
+        status: 400,
+      },
+    );
+  }
+}
+
+export abstract class Endpoint extends BaseEndpoint {
+  private _endpointBrand!: void; // nominal typing
+
+  override doHandle(ctx: HttpContext) {
+    if (!this.allowAnonymous && !ctx.user) {
+      return Response.json(
+        {
+          message: "unauthorized",
+        },
+        {
+          status: 401,
+        },
+      );
+    }
+    return super.doHandle(ctx);
+  }
+}
+
+export abstract class AdminEndpoint extends BaseEndpoint {
+  private _adminEndpointBrand!: void; // nominal typing
+
+  override doHandle(ctx: HttpContext) {
+    if (!this.allowAnonymous && !ctx.admin) {
+      return Response.json(
+        {
+          message: "unauthorized",
+        },
+        {
+          status: 401,
+        },
+      );
+    }
+    return super.doHandle(ctx);
+  }
+}

package/src/EventEmitter.ts

@@ -0,0 +1,32 @@
+import { createDebug } from "./utils/createDebug.js";
+
+const debug = createDebug("EventEmitter");
+
+type EventMap = Record<string, any>;
+type EventKey<T extends EventMap> = string & keyof T;
+type EventCallback<T> = (payload: T) => void;
+
+export class EventEmitter<Events extends EventMap> {
+  private listeners = new Map<
+    keyof Events,
+    Array<EventCallback<Events[keyof Events]>>
+  >();
+
+  on<K extends EventKey<Events>>(event: K, callback: EventCallback<Events[K]>) {
+    debug("subscribing to event %s", event);
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners
+      .get(event)!
+      .push(callback as EventCallback<Events[keyof Events]>);
+  }
+
+  emit<K extends EventKey<Events>>(event: K, payload: Events[K]) {
+    debug("emitting event %s", event);
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach((callback) => callback(payload));
+    }
+  }
+}

package/src/Handler.ts

@@ -0,0 +1,14 @@
+import { Component } from "./Component.js";
+import { type HttpContext } from "./HttpContext.js";
+
+export abstract class Handler extends Component {
+  protected allowAnonymous = false;
+
+  protected hasPermission(ctx: HttpContext) {
+    return true;
+  }
+
+  public abstract doHandle(ctx: HttpContext): Response | Promise<Response>;
+
+  protected abstract handle(ctx: HttpContext): Response | Promise<Response>;
+}

package/src/HttpContext.ts

@@ -0,0 +1,35 @@
+import { type Context } from "./Context.js";
+import { type HttpMethod } from "./Router.js";
+import { type Locale } from "./contrib/accept-language-parser.js";
+
+export interface HttpContext<Payload = any, PathParams = any, QueryParams = any>
+  extends Context {
+  method: HttpMethod;
+  payload: Payload;
+  path: string;
+  pathParams: PathParams;
+  query: QueryParams;
+  headers: Headers;
+  cookies: Record<string, string>;
+  abortSignal: AbortSignal;
+
+  locale: Locale;
+  responseHeaders: Headers;
+  sessionId?: string;
+  adminSessionId?: string;
+
+  render: (
+    view: string | string[],
+    data?: Record<string, any>,
+  ) => Promise<Response>;
+
+  redirect(path: string, type?: HttpRedirectCode): Response;
+}
+
+export enum HttpRedirectCode {
+  HTTP_301_MOVED_PERMANENTLY = 301,
+  HTTP_302_FOUND = 302,
+  HTTP_303_SEE_OTHER = 303,
+  HTTP_307_TEMPORARY_REDIRECT = 307,
+  HTTP_308_PERMANENT_REDIRECT = 308,
+}

package/src/I18nService.ts

@@ -0,0 +1,96 @@
+import { type Locale } from "./contrib/accept-language-parser.js";
+import { ModuleDefinitions } from "./Module.js";
+import { compileTemplate } from "./contrib/template.js";
+import { Component, INJECT } from "./Component.js";
+import type { Context } from "./Context.js";
+import { FS } from "./utils/fs.js";
+
+function flatten(obj: any) {
+  const output: Record<string, string> = {};
+
+  function flattenRecursively(curr: any, parentKey: string) {
+    if (typeof curr === "object" && curr !== null && !Array.isArray(curr)) {
+      for (const key in curr) {
+        flattenRecursively(curr[key], parentKey ? `${parentKey}.${key}` : key);
+      }
+    } else {
+      output[parentKey] = curr;
+    }
+  }
+
+  flattenRecursively(obj, "");
+  return output;
+}
+
+export abstract class I18nService extends Component {
+  public abstract availableLocales(): Locale[];
+  public abstract translate(
+    ctx: Context,
+    locale: Locale,
+    key: string,
+    ...args: any[]
+  ): string;
+}
+
+export class BaseI18nService extends I18nService {
+  static [INJECT] = [ModuleDefinitions];
+
+  private readonly translations = new Map<string, Map<string, string>>();
+
+  constructor(private readonly modules: ModuleDefinitions) {
+    super();
+  }
+
+  override init() {
+    return this.loadTranslations();
+  }
+
+  private async loadTranslations() {
+    try {
+      for (const module of this.modules.modules) {
+        if (!module.assetsDir) {
+          continue;
+        }
+        for (const filename of await FS.readDirRecursively(
+          FS.join(module.assetsDir, "i18n"),
+        )) {
+          if (!filename.endsWith(".json")) {
+            continue;
+          }
+          const content = await FS.readFile(
+            FS.join(module.assetsDir, "i18n", filename),
+          );
+          const locale = filename.slice(0, -5);
+          const values = JSON.parse(content);
+
+          let localizedTranslations = this.translations.get(locale);
+          if (!localizedTranslations) {
+            this.translations.set(locale, (localizedTranslations = new Map()));
+          }
+          const flatTranslations = flatten(values);
+          for (const [key, value] of Object.entries(flatTranslations)) {
+            localizedTranslations.set(key, value);
+          }
+        }
+      }
+    } catch (e) {}
+  }
+
+  override availableLocales() {
+    return Array.from(this.translations.keys()) as Locale[];
+  }
+
+  override translate(
+    _ctx: Context,
+    locale: Locale,
+    key: string,
+    ...args: any[]
+  ) {
+    const value = this.translations.get(locale)?.get(key);
+    if (value && value.includes("<%")) {
+      return compileTemplate(value)(args);
+    } else {
+      return value || "";
+    }
+  }
+}

package/src/Middleware.ts

@@ -0,0 +1,10 @@
+import type { HttpContext } from "./HttpContext.js";
+import { Component } from "./Component.js";
+
+export abstract class Middleware extends Component {
+  private _middlewareBrand!: void; // nominal typing
+
+  public abstract handle(
+    ctx: HttpContext,
+  ): void | Response | Promise<void | Response>;
+}

package/src/Module.ts

@@ -0,0 +1,60 @@
+import { Component, type Ctor } from "./Component.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 { type Handler } from "./Handler.js";
+
+export interface AdminSidebarItem {
+  label: string;
+  icon: string;
+  path: string;
+}
+
+export interface Module {
+  name: string;
+  version: string;
+  assetsDir?: string;
+  adminSidebarItems?: AdminSidebarItem[];
+
+  init(app: AppInit): void;
+}
+
+export interface AppInit {
+  component<T extends Component>(ctor: Ctor<T>): void;
+  endpoint(method: HttpMethod, path: string, ctor: Ctor<Endpoint>): void;
+  view(path: string, ctor: Ctor<View>): void;
+  adminEndpoint(
+    method: HttpMethod,
+    path: string,
+    ctor: Ctor<AdminEndpoint>,
+  ): void;
+  adminView(path: string, ctor: Ctor<AdminView>): void;
+  middleware(ctor: Ctor<Middleware>): void;
+}
+
+export interface Route {
+  method: HttpMethod;
+  path: string;
+  handlerName: string;
+  handler: Handler;
+}
+
+export interface ModuleDefinition {
+  name: string;
+  version: string;
+  assetsDir?: string;
+  adminSidebarItems?: AdminSidebarItem[];
+
+  endpoints: Route[];
+  views: Route[];
+  adminEndpoints: Route[];
+  adminViews: Route[];
+  middlewares: Middleware[];
+}
+
+export class ModuleDefinitions extends Component {
+  constructor(public readonly modules: ModuleDefinition[]) {
+    super();
+  }
+}

package/src/PubSubService.ts

@@ -0,0 +1,77 @@
+import { Component } from "./Component.js";
+import { createDebug } from "./utils/createDebug.js";
+import type { Context } from "./Context.js";
+import { EventEmitter } from "./EventEmitter.js";
+import cluster from "node:cluster";
+import { randomId } from "./utils/randomId.js";
+
+const debug = createDebug("PubSubService");
+
+interface Message {
+  from: string;
+  type: string;
+  payload?: any;
+}
+
+export class PubSubService extends Component {
+  protected readonly id = randomId();
+  private eventEmitter = new EventEmitter();
+
+  public publish(_ctx: Context, _type: string, _payload?: any) {
+    // noop
+  }
+
+  public subscribe<T>(type: string, handler: (payload: T) => void): void {
+    this.eventEmitter.on(type, handler);
+  }
+
+  protected onMessage(message: Message) {
+    if (message.from === this.id) {
+      debug("ignore message from self");
+      return;
+    }
+    debug("received message %s", message.type);
+    this.eventEmitter.emit(message.type, message.payload);
+  }
+}
+
+function ignoreError() {}
+
+export class NodeClusterPubSubService extends PubSubService {
+  constructor() {
+    super();
+    if (!cluster.isWorker) {
+      throw "not worker";
+    }
+    process.on("message", (message: Message) => this.onMessage(message));
+  }
+
+  override publish(_ctx: Context, type: string, payload?: any) {
+    if (typeof process.send !== "function") {
+      return;
+    }
+    debug("sending message %s", type);
+    const message = {
+      from: this.id,
+      type,
+      payload,
+    } as Message;
+    process.send(message, undefined, {}, ignoreError);
+  }
+}
+
+export function initPrimary() {
+  if (!cluster.isPrimary) {
+    throw "not primary";
+  }
+
+  cluster.on("message", (worker, message) => {
+    const emitterId = String(worker.id);
+    debug("forwarding message %s to other workers", message.type);
+    for (const workerId in cluster.workers) {
+      if (workerId !== emitterId) {
+        cluster.workers[workerId]?.send(message, ignoreError);
+      }
+    }
+  });
+}

package/src/Repository.ts

@@ -0,0 +1,158 @@
+import { camelToSnakeCase } from "./utils/camelToSnakeCase.js";
+import { snakeToCamelCase } from "./utils/snakeToCamelCase.js";
+import { Component, INJECT } from "./Component.js";
+import { DB } from "./DB.js";
+import type { Context } from "./Context.js";
+import { sql, Statement } from "./utils/sql.js";
+
+export class EntityNotFoundError extends Error {}
+
+export abstract class Repository<
+  ID,
+  T extends Record<string, any>,
+> extends Component {
+  static [INJECT] = [DB];
+
+  protected abstract tableName: string;
+  protected idField: string | string[] = "id";
+  protected dateFields: string[] = [];
+
+  constructor(protected readonly db: DB) {
+    super();
+  }
+
+  public findById(ctx: Context, id: ID) {
+    const query = sql.select().from(this.tableName).where(this.idClause(id));
+
+    return this.one(ctx, query);
+  }
+
+  async deleteById(ctx: Context, id: ID) {
+    const query = sql.deleteFrom(this.tableName).where(this.idClause(id));
+
+    const res = await this.db.run(ctx, query);
+
+    if (res.affectedRows !== 1) {
+      throw new EntityNotFoundError();
+    }
+  }
+
+  private idClause(id: ID) {
+    if (Array.isArray(this.idField)) {
+      return this.idField.reduce((acc, k) => {
+        // @ts-expect-error
+        acc[camelToSnakeCase(k)] = id[k];
+        return acc;
+      }, {});
+    } else {
+      return {
+        [camelToSnakeCase(this.idField)]: id,
+      };
+    }
+  }
+
+  public async save(ctx: Context, entity: Partial<T>) {
+    const idFields = Array.isArray(this.idField)
+      ? this.idField
+      : [this.idField];
+    const isIDSpecified = idFields.every(
+      (idField) => entity[idField] !== undefined,
+    );
+
+    if (isIDSpecified) {
+      const idClause: Record<string, any> = {};
+      idFields.forEach((idField) => {
+        idClause[camelToSnakeCase(idField)] = entity[idField];
+      });
+
+      this.onBeforeUpdate(ctx, entity);
+
+      const { affectedRows } = await this.db.run(
+        ctx,
+        sql.update(this.tableName).set(this.toRow(entity)).where(idClause),
+      );
+
+      if (affectedRows > 1) {
+        throw "unexpected number of updated rows";
+      } else if (affectedRows === 1) {
+        return entity as T;
+      }
+    }
+
+    this.onBeforeInsert(ctx, entity);
+
+    const rows = await this.db.query(
+      ctx,
+      sql
+        .insert()
+        .into(this.tableName)
+        .values([this.toRow(entity)])
+        .returning(idFields.map((idField) => camelToSnakeCase(idField))),
+    );
+
+    if (rows.length !== 1) {
+      throw "unexpected number of inserted rows";
+    }
+
+    Object.assign(entity, this.toEntity(rows[0]));
+
+    return entity as T;
+  }
+
+  public startTransaction(ctx: Context, fn: () => Promise<void>) {
+    return this.db.startTransaction(ctx, fn);
+  }
+
+  protected async one(ctx: Context, query: Statement) {
+    const rows = await this.db.query(ctx, query);
+
+    return rows.length === 1 ? this.toEntity(rows[0]) : undefined;
+  }
+
+  protected async all(ctx: Context, query: Statement) {
+    const rows = await this.db.query(ctx, query);
+
+    return rows.map((row) => this.toEntity(row));
+  }
+
+  protected async count(ctx: Context, countQuery: Statement) {
+    const rows = await this.db.query(ctx, countQuery);
+    return parseInt(rows[0].count, 10);
+  }
+
+  protected toRow(entity: Partial<T>) {
+    const row: Record<string, any> = {};
+
+    Object.keys(entity).forEach((key) => {
+      row[camelToSnakeCase(key)] = entity[key];
+    });
+
+    return row;
+  }
+
+  protected toEntity(row: Record<string, any>) {
+    const entity: Record<string, any> = {};
+
+    Object.keys(row).forEach((key) => {
+      const fieldName = snakeToCamelCase(key);
+      let fieldValue = row[key];
+
+      if (
+        this.dateFields.includes(fieldName) &&
+        typeof fieldValue === "number"
+      ) {
+        fieldValue = new Date(fieldValue);
+      }
+      entity[fieldName] = fieldValue;
+    });
+
+    return entity as T;
+  }
+
+  protected onBeforeInsert(ctx: Context, entity: Partial<T>) {}
+  protected onBeforeUpdate(ctx: Context, entity: Partial<T>) {}
+}
+
+export interface Page<T> {
+  items: T[];
+}

package/src/Router.ts

@@ -0,0 +1,77 @@
+import { Handler } from "./Handler.js";
+
+export type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "DELETE"
+  | "PATCH"
+  | "OPTIONS"
+  | "HEAD";
+
+type RouteMatcher = (path: string) => Record<string, string> | undefined;
+
+type Route = {
+  path: string;
+  matcher: RouteMatcher;
+  handlers: Map<HttpMethod, Handler>;
+};
+
+function createMatcher(path: string): RouteMatcher {
+  if (!path.includes(":")) {
+    return (p: string) => {
+      return p === path ? {} : undefined;
+    };
+  }
+  const pathParams: string[] = [];
+  const regex = new RegExp(
+    "^" +
+      path.replace(/:(\w+)/g, (pathParam) => {
+        pathParams.push(pathParam.substring(1));
+        return "([\\w-_]+)";
+      }) +
+      "$",
+  );
+
+  return (path: string) => {
+    const match = regex.exec(path);
+    if (!match) {
+      return;
+    }
+    const params: Record<string, string> = {};
+    for (let i = 0; i < pathParams.length; i++) {
+      params[pathParams[i]] = match[i + 1];
+    }
+    return params;
+  };
+}
+
+export class Router {
+  private routes: Route[] = [];
+
+  public registerRoute(method: HttpMethod, path: string, handler: Handler) {
+    for (const route of this.routes) {
+      if (route.path === path) {
+        route.handlers.set(method, handler);
+        return;
+      }
+    }
+    this.routes.push({
+      path,
+      matcher: createMatcher(path),
+      handlers: new Map([[method, handler]]),
+    });
+  }
+
+  public findRoute(method: HttpMethod, path: string) {
+    for (const route of this.routes) {
+      const pathParams = route.matcher(path);
+      if (pathParams !== undefined && route.handlers.has(method)) {
+        return {
+          handler: route.handlers.get(method)!,
+          pathParams,
+        };
+      }
+    }
+  }
+}