@no-k/hermes 0.1.0

package/lib/catalog.mjs

@@ -0,0 +1,51 @@
+const itemNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function isSourcePath(value) {
+  return (
+    typeof value === "string" &&
+    value.endsWith(".ts") &&
+    !value.includes("\\") &&
+    !value.includes("\0") &&
+    !value.includes(":") &&
+    value.split("/").every((part) => part && part !== "." && part !== "..") &&
+    !/\.(test|spec|stories|config|d)\.ts$/.test(value)
+  );
+}
+
+export function validateCatalog(catalog) {
+  if (
+    catalog?.schemaVersion !== 1 ||
+    typeof catalog.version !== "string" ||
+    !Array.isArray(catalog.items) ||
+    catalog.items.length === 0
+  ) {
+    throw new Error("Invalid Hermes catalog.");
+  }
+  const names = new Set();
+  for (const item of catalog.items) {
+    if (
+      !item ||
+      typeof item.name !== "string" ||
+      !itemNamePattern.test(item.name) ||
+      names.has(item.name) ||
+      typeof item.description !== "string" ||
+      !Array.isArray(item.files) ||
+      item.files.length === 0 ||
+      !item.files.every(isSourcePath) ||
+      new Set(item.files).size !== item.files.length ||
+      (item.runtime !== undefined && !["node", "dom"].includes(item.runtime))
+    ) {
+      throw new Error("Invalid or duplicate Hermes item: " + item?.name);
+    }
+    for (const values of [item.dependencies, item.devDependencies ?? []]) {
+      if (
+        !Array.isArray(values) ||
+        !values.every((value) => typeof value === "string" && /^[^\s]+@[^\s]+$/.test(value))
+      ) {
+        throw new Error("Invalid dependencies for " + item.name);
+      }
+    }
+    names.add(item.name);
+  }
+  return catalog;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@no-k/hermes",
+  "version": "0.1.0",
+  "description": "Add individual TypeScript utilities to your project with the Hermes CLI.",
+  "license": "ISC",
+  "files": ["bin", "lib", "templates", "catalog.json", "README.md", "LICENSE"],
+  "keywords": ["cli", "typescript", "utilities"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/no-k/hermes.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": false
+  },
+  "scripts": {
+    "prepack": "pnpm --workspace-root run build:cli"
+  },
+  "type": "module",
+  "bin": {
+    "hermes": "./bin/hermes.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/algorithm/geometry/ccw/ccw.ts

@@ -0,0 +1,25 @@
+export type Point = {
+  x: number;
+  y: number;
+};
+
+export const ccw = (a: Point, b: Point, c: Point) => {
+  const cross = (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+
+  if (cross > 0) {
+    return 1;
+  }
+
+  if (cross < 0) {
+    return -1;
+  }
+
+  return 0;
+};
+
+export const distanceSquare = (a: Point, b: Point) => {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+
+  return dx * dx + dy * dy;
+};

package/templates/algorithm/geometry/ccw/index.ts

@@ -0,0 +1 @@
+export * from "./ccw";

package/templates/algorithm/geometry/convex-hull/convex-hull.ts

@@ -0,0 +1,43 @@
+import { type Point, ccw } from "../ccw/index";
+
+const comparePoint = (a: Point, b: Point) => {
+  if (a.x !== b.x) {
+    return a.x - b.x;
+  }
+
+  return a.y - b.y;
+};
+
+const samePoint = (a: Point, b: Point) => a.x === b.x && a.y === b.y;
+
+export const convexHull = (points: Point[]) => {
+  const sorted = [...points].sort(comparePoint).filter((point, index, values) => {
+    return index === 0 || !samePoint(point, values[index - 1]);
+  });
+
+  if (sorted.length <= 1) {
+    return sorted;
+  }
+
+  const lower: Point[] = [];
+  for (const point of sorted) {
+    while (lower.length >= 2 && ccw(lower[lower.length - 2], lower[lower.length - 1], point) <= 0) {
+      lower.pop();
+    }
+    lower.push(point);
+  }
+
+  const upper: Point[] = [];
+  for (let index = sorted.length - 1; index >= 0; index -= 1) {
+    const point = sorted[index];
+    while (upper.length >= 2 && ccw(upper[upper.length - 2], upper[upper.length - 1], point) <= 0) {
+      upper.pop();
+    }
+    upper.push(point);
+  }
+
+  lower.pop();
+  upper.pop();
+
+  return [...lower, ...upper];
+};

package/templates/algorithm/geometry/convex-hull/index.ts

@@ -0,0 +1 @@
+export * from "./convex-hull";

package/templates/algorithm/geometry/polygon-area/index.ts

@@ -0,0 +1 @@
+export * from "./polygon-area";

package/templates/algorithm/geometry/polygon-area/polygon-area.ts

@@ -0,0 +1,13 @@
+import type { Point } from "../ccw/index";
+
+export const polygonArea = (points: Point[]) => {
+  let doubledArea = 0;
+
+  for (let index = 0; index < points.length; index += 1) {
+    const current = points[index];
+    const next = points[(index + 1) % points.length];
+    doubledArea += current.x * next.y - current.y * next.x;
+  }
+
+  return Math.abs(doubledArea) / 2;
+};

package/templates/algorithm/graph/bellman-ford/bellman-ford.ts

@@ -0,0 +1,46 @@
+export type DirectedWeightedEdge<T> = {
+  from: T;
+  to: T;
+  weight: number;
+};
+
+export const bellmanFord = <T>(nodes: Iterable<T>, edges: DirectedWeightedEdge<T>[], start: T) => {
+  const distances = new Map<T, number>();
+
+  for (const node of nodes) {
+    distances.set(node, Number.POSITIVE_INFINITY);
+  }
+  distances.set(start, 0);
+
+  const nodeList = [...distances.keys()];
+
+  for (let count = 0; count < nodeList.length - 1; count += 1) {
+    let updated = false;
+
+    for (const edge of edges) {
+      const fromDistance = distances.get(edge.from) ?? Number.POSITIVE_INFINITY;
+      const toDistance = distances.get(edge.to) ?? Number.POSITIVE_INFINITY;
+
+      if (fromDistance !== Number.POSITIVE_INFINITY && fromDistance + edge.weight < toDistance) {
+        distances.set(edge.to, fromDistance + edge.weight);
+        updated = true;
+      }
+    }
+
+    if (!updated) {
+      break;
+    }
+  }
+
+  const hasNegativeCycle = edges.some((edge) => {
+    const fromDistance = distances.get(edge.from) ?? Number.POSITIVE_INFINITY;
+    const toDistance = distances.get(edge.to) ?? Number.POSITIVE_INFINITY;
+
+    return fromDistance !== Number.POSITIVE_INFINITY && fromDistance + edge.weight < toDistance;
+  });
+
+  return {
+    distances,
+    hasNegativeCycle,
+  };
+};

package/templates/algorithm/graph/bellman-ford/index.ts

@@ -0,0 +1 @@
+export * from "./bellman-ford";

package/templates/algorithm/graph/bfs/bfs.ts

@@ -0,0 +1,21 @@
+export const bfs = <T>(start: T, getNeighbors: (node: T) => Iterable<T>) => {
+  const visited = new Set<T>([start]);
+  const queue: T[] = [start];
+  const order: T[] = [];
+
+  for (let index = 0; index < queue.length; index += 1) {
+    const node = queue[index];
+    order.push(node);
+
+    for (const next of getNeighbors(node)) {
+      if (visited.has(next)) {
+        continue;
+      }
+
+      visited.add(next);
+      queue.push(next);
+    }
+  }
+
+  return order;
+};

package/templates/algorithm/graph/bfs/index.ts

@@ -0,0 +1 @@
+export * from "./bfs";

package/templates/algorithm/graph/dfs/dfs.ts

@@ -0,0 +1,22 @@
+export const dfs = <T>(start: T, getNeighbors: (node: T) => Iterable<T>) => {
+  const visited = new Set<T>();
+  const stack: T[] = [start];
+  const order: T[] = [];
+
+  while (stack.length) {
+    const node = stack.pop() as T;
+    if (visited.has(node)) {
+      continue;
+    }
+
+    visited.add(node);
+    order.push(node);
+
+    const neighbors = [...getNeighbors(node)];
+    for (let index = neighbors.length - 1; index >= 0; index -= 1) {
+      stack.push(neighbors[index]);
+    }
+  }
+
+  return order;
+};

package/templates/algorithm/graph/dfs/index.ts

@@ -0,0 +1 @@
+export * from "./dfs";

package/templates/algorithm/graph/dijkstra/dijkstra.ts

@@ -0,0 +1,37 @@
+import { PriorityQueue } from "../../../data-structure/priority-queue/index";
+
+export type WeightedEdge<T> = {
+  to: T;
+  weight: number;
+};
+
+export const dijkstra = <T>(start: T, getEdges: (node: T) => Iterable<WeightedEdge<T>>) => {
+  const distances = new Map<T, number>([[start, 0]]);
+  const queue = new PriorityQueue<{ node: T; distance: number }>({
+    compare: (a, b) => a.distance - b.distance,
+  });
+
+  queue.enqueue({ node: start, distance: 0 });
+
+  while (!queue.isEmpty()) {
+    const current = queue.dequeue() as { node: T; distance: number };
+
+    if (current.distance > (distances.get(current.node) as number)) {
+      continue;
+    }
+
+    for (const edge of getEdges(current.node)) {
+      const nextDistance = current.distance + edge.weight;
+      const previousDistance = distances.get(edge.to);
+
+      if (previousDistance !== undefined && previousDistance <= nextDistance) {
+        continue;
+      }
+
+      distances.set(edge.to, nextDistance);
+      queue.enqueue({ node: edge.to, distance: nextDistance });
+    }
+  }
+
+  return distances;
+};

package/templates/algorithm/graph/dijkstra/index.ts

@@ -0,0 +1 @@
+export * from "./dijkstra";

package/templates/algorithm/graph/floyd-warshall/floyd-warshall.ts

@@ -0,0 +1,17 @@
+export const floydWarshall = (matrix: number[][]) => {
+  const distance = matrix.map((row) => [...row]);
+  const size = distance.length;
+
+  for (let mid = 0; mid < size; mid += 1) {
+    for (let from = 0; from < size; from += 1) {
+      for (let to = 0; to < size; to += 1) {
+        const next = distance[from][mid] + distance[mid][to];
+        if (next < distance[from][to]) {
+          distance[from][to] = next;
+        }
+      }
+    }
+  }
+
+  return distance;
+};

package/templates/algorithm/graph/floyd-warshall/index.ts

@@ -0,0 +1 @@
+export * from "./floyd-warshall";

package/templates/algorithm/graph/kruskal/index.ts

@@ -0,0 +1 @@
+export * from "./kruskal";

package/templates/algorithm/graph/kruskal/kruskal.ts

@@ -0,0 +1,29 @@
+import { UnionFind } from "../../../data-structure/union-find/index";
+
+export type WeightedUndirectedEdge<T> = {
+  from: T;
+  to: T;
+  weight: number;
+};
+
+export const kruskal = <T>(nodes: Iterable<T>, edges: WeightedUndirectedEdge<T>[]) => {
+  const unionFind = new UnionFind(nodes);
+  const selected: WeightedUndirectedEdge<T>[] = [];
+  let totalWeight = 0;
+
+  const sortedEdges = [...edges].sort((a, b) => a.weight - b.weight);
+
+  for (const edge of sortedEdges) {
+    if (!unionFind.union(edge.from, edge.to)) {
+      continue;
+    }
+
+    selected.push(edge);
+    totalWeight += edge.weight;
+  }
+
+  return {
+    edges: selected,
+    totalWeight,
+  };
+};

package/templates/algorithm/graph/prim/index.ts

@@ -0,0 +1 @@
+export * from "./prim";

package/templates/algorithm/graph/prim/prim.ts

@@ -0,0 +1,44 @@
+import { PriorityQueue } from "../../../data-structure/priority-queue/index";
+import type { WeightedEdge } from "../dijkstra/index";
+
+type QueueItem<T> = {
+  from: T | null;
+  to: T;
+  weight: number;
+};
+
+export const prim = <T>(start: T, getEdges: (node: T) => Iterable<WeightedEdge<T>>) => {
+  const visited = new Set<T>();
+  const selected: Array<{ from: T; to: T; weight: number }> = [];
+  const queue = new PriorityQueue<QueueItem<T>>({
+    compare: (a, b) => a.weight - b.weight,
+  });
+  let totalWeight = 0;
+
+  queue.enqueue({ from: null, to: start, weight: 0 });
+
+  while (!queue.isEmpty()) {
+    const current = queue.dequeue() as QueueItem<T>;
+    if (visited.has(current.to)) {
+      continue;
+    }
+
+    visited.add(current.to);
+
+    if (current.from !== null) {
+      selected.push({ from: current.from, to: current.to, weight: current.weight });
+      totalWeight += current.weight;
+    }
+
+    for (const edge of getEdges(current.to)) {
+      if (!visited.has(edge.to)) {
+        queue.enqueue({ from: current.to, to: edge.to, weight: edge.weight });
+      }
+    }
+  }
+
+  return {
+    edges: selected,
+    totalWeight,
+  };
+};

package/templates/algorithm/graph/topology-sort/index.ts

@@ -0,0 +1 @@
+export * from "./topology-sort";

package/templates/algorithm/graph/topology-sort/topology-sort.ts

@@ -0,0 +1,31 @@
+export const topologicalSort = <T>(nodes: Iterable<T>, getNeighbors: (node: T) => Iterable<T>) => {
+  const visited = new Set<T>();
+  const visiting = new Set<T>();
+  const result: T[] = [];
+
+  const visit = (node: T) => {
+    if (visited.has(node)) {
+      return;
+    }
+
+    if (visiting.has(node)) {
+      throw new Error("cycle detected");
+    }
+
+    visiting.add(node);
+
+    for (const next of getNeighbors(node)) {
+      visit(next);
+    }
+
+    visiting.delete(node);
+    visited.add(node);
+    result.push(node);
+  };
+
+  for (const node of nodes) {
+    visit(node);
+  }
+
+  return result.reverse();
+};

package/templates/algorithm/search/binary-search/binary-search.ts

@@ -0,0 +1,74 @@
+const defaultCompare = <T>(value: T, target: T) => {
+  if (value < target) {
+    return -1;
+  }
+
+  if (value > target) {
+    return 1;
+  }
+
+  return 0;
+};
+
+export const lowerBound = <T>(values: T[], target: T, compare = defaultCompare<T>) => {
+  let left = 0;
+  let right = values.length;
+
+  while (left < right) {
+    const mid = Math.floor((left + right) / 2);
+
+    if (compare(values[mid], target) < 0) {
+      left = mid + 1;
+    } else {
+      right = mid;
+    }
+  }
+
+  return left;
+};
+
+export const upperBound = <T>(values: T[], target: T, compare = defaultCompare<T>) => {
+  let left = 0;
+  let right = values.length;
+
+  while (left < right) {
+    const mid = Math.floor((left + right) / 2);
+
+    if (compare(values[mid], target) <= 0) {
+      left = mid + 1;
+    } else {
+      right = mid;
+    }
+  }
+
+  return left;
+};
+
+export const binarySearch = <T>(values: T[], target: T, compare = defaultCompare<T>) => {
+  const index = lowerBound(values, target, compare);
+
+  if (index >= values.length || compare(values[index], target) !== 0) {
+    return -1;
+  }
+
+  return index;
+};
+
+export const binarySearchAnswer = (left: number, right: number, canUse: (value: number) => boolean) => {
+  let low = left;
+  let high = right;
+  let answer = right + 1;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+
+    if (canUse(mid)) {
+      answer = mid;
+      high = mid - 1;
+    } else {
+      low = mid + 1;
+    }
+  }
+
+  return answer;
+};

package/templates/algorithm/search/binary-search/index.ts

@@ -0,0 +1 @@
+export * from "./binary-search";

package/templates/algorithm/string/kmp/index.ts

@@ -0,0 +1 @@
+export * from "./kmp";

package/templates/algorithm/string/kmp/kmp.ts

@@ -0,0 +1,46 @@
+export const buildPrefixTable = (pattern: string) => {
+  const table = Array(pattern.length).fill(0);
+  let matched = 0;
+
+  for (let index = 1; index < pattern.length; index += 1) {
+    while (matched > 0 && pattern[index] !== pattern[matched]) {
+      matched = table[matched - 1];
+    }
+
+    if (pattern[index] === pattern[matched]) {
+      matched += 1;
+      table[index] = matched;
+    }
+  }
+
+  return table;
+};
+
+export const kmpSearch = (text: string, pattern: string) => {
+  if (!pattern.length) {
+    return Array.from({ length: text.length + 1 }, (_, index) => index);
+  }
+
+  const table = buildPrefixTable(pattern);
+  const result: number[] = [];
+  let matched = 0;
+
+  for (let index = 0; index < text.length; index += 1) {
+    while (matched > 0 && text[index] !== pattern[matched]) {
+      matched = table[matched - 1];
+    }
+
+    if (text[index] !== pattern[matched]) {
+      continue;
+    }
+
+    matched += 1;
+
+    if (matched === pattern.length) {
+      result.push(index - pattern.length + 1);
+      matched = table[matched - 1];
+    }
+  }
+
+  return result;
+};

package/templates/algorithm/string/z-algorithm/index.ts

@@ -0,0 +1 @@
+export * from "./z-algorithm";

package/templates/algorithm/string/z-algorithm/z-algorithm.ts

@@ -0,0 +1,41 @@
+export const buildZArray = (value: string) => {
+  const z = Array(value.length).fill(0);
+  let left = 0;
+  let right = 0;
+
+  for (let index = 1; index < value.length; index += 1) {
+    if (index <= right) {
+      z[index] = Math.min(right - index + 1, z[index - left]);
+    }
+
+    while (index + z[index] < value.length && value[z[index]] === value[index + z[index]]) {
+      z[index] += 1;
+    }
+
+    if (index + z[index] - 1 > right) {
+      left = index;
+      right = index + z[index] - 1;
+    }
+  }
+
+  return z;
+};
+
+export const zSearch = (text: string, pattern: string) => {
+  if (!pattern.length) {
+    return Array.from({ length: text.length + 1 }, (_, index) => index);
+  }
+
+  const separator = "\0";
+  const z = buildZArray(`${pattern}${separator}${text}`);
+  const result: number[] = [];
+  const offset = pattern.length + 1;
+
+  for (let index = offset; index < z.length; index += 1) {
+    if (z[index] >= pattern.length) {
+      result.push(index - offset);
+    }
+  }
+
+  return result;
+};