@no-k/hermes 0.1.0

package/templates/string/mask/mask.ts

@@ -0,0 +1,30 @@
+export interface MaskOptions {
+  /** 앞에서 그대로 남길 글자 수. 기본 1. */
+  start?: number;
+  /** 뒤에서 그대로 남길 글자 수. 기본 1. */
+  end?: number;
+  /** 가운데를 가릴 문자. 기본 "*". */
+  char?: string;
+}
+
+// 앞 start글자와 뒤 end글자만 남기고 가운데를 char로 가린다. 입력은 변형하지 않는다.
+// start + end가 길이 이상이면 가릴 가운데가 없으므로 원문을 그대로 반환한다.
+//
+// 길이 계산과 슬라이싱을 코드포인트 단위(`[...str]`)로 한다. str.length나 slice는
+// 서로게이트 쌍(이모지 등)을 반쪽으로 세거나 쪼개므로, 사용자가 보는 "글자 수"와
+// 어긋난다. 가운데 한 글자당 char 하나로 치환한다 (남는 글자 수만큼 char 반복).
+export const mask = (str: string, options: MaskOptions = {}): string => {
+  const { start = 1, end = 1, char = "*" } = options;
+
+  const chars = [...str];
+  const hiddenCount = chars.length - start - end;
+
+  if (hiddenCount <= 0) {
+    return str;
+  }
+
+  const head = chars.slice(0, start).join("");
+  const tail = chars.slice(chars.length - end).join("");
+
+  return head + char.repeat(hiddenCount) + tail;
+};

package/templates/string/pad/index.ts

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

package/templates/string/pad/pad.ts

@@ -0,0 +1,17 @@
+// 양쪽을 char로 균등하게 채워 가운데 정렬한다. length 이하면 그대로 둔다.
+// 채울 총량을 좌우로 나누되, 홀수 잔여는 오른쪽에 더한다 (왼쪽 floor, 오른쪽 ceil).
+// char가 여러 글자여도 되도록 padStart/padEnd로 채운 뒤 정확한 길이로 자른다.
+// String.prototype.padStart/padEnd는 char가 빈 문자열이면 아무것도 채우지 않으므로
+// 그 경우 원본이 그대로 반환된다.
+export const pad = (str: string, length: number, char = " "): string => {
+  if (str.length >= length) {
+    return str;
+  }
+
+  const total = length - str.length;
+  const left = Math.floor(total / 2);
+
+  // 왼쪽을 left만큼 채운 길이까지 padStart, 그 결과를 다시 length까지 padEnd.
+  // 남은 오른쪽(ceil)은 length - (str.length + left)로 자동 결정된다.
+  return str.padStart(str.length + left, char).padEnd(length, char);
+};

package/templates/string/random-string/index.ts

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

package/templates/string/random-string/random-string.ts

@@ -0,0 +1,20 @@
+// alphabet에서 length 글자를 런타임 난수로 뽑아 문자열을 만든다.
+// 기본 alphabet은 영숫자(A-Z, a-z, 0-9). length <= 0이면 빈 문자열을 반환한다.
+//
+// 매번 새 문자열을 만들어 반환하며 인자는 변형하지 않는다. 난수원은 Math.random이라
+// 암호학적으로 안전하지 않다 (식별자/토큰용 가벼운 무작위 문자열 생성 용도).
+const DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+export const randomString = (length: number, alphabet: string = DEFAULT_ALPHABET): string => {
+  if (length <= 0 || alphabet.length === 0) {
+    return "";
+  }
+
+  let result = "";
+  for (let index = 0; index < length; index += 1) {
+    const pick = Math.floor(Math.random() * alphabet.length);
+    result += alphabet[pick];
+  }
+
+  return result;
+};

package/templates/string/reverse/index.ts

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

package/templates/string/reverse/reverse.ts

@@ -0,0 +1,6 @@
+// 문자 순서를 뒤집어 새 문자열을 반환한다. 입력은 변형하지 않는다.
+// `str.split("")`은 서로게이트 쌍(이모지 등)을 반쪽으로 쪼개 깨뜨리므로,
+// 코드포인트 단위로 도는 문자열 이터레이터(`[...str]`)로 안전하게 뒤집는다.
+export const reverse = (str: string): string => {
+  return [...str].reverse().join("");
+};

package/templates/string/slugify/index.ts

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

package/templates/string/slugify/slugify.ts

@@ -0,0 +1,11 @@
+// URL/식별자용 슬러그를 만든다. 소문자로 내린 뒤 ASCII 영숫자가 아닌 문자가
+// 이어진 구간을 "-" 하나로 합치고, 양끝의 "-"는 제거한다. 입력은 변형하지 않는다.
+//
+// `[^a-z0-9]+` 한 번의 치환으로 구분자 런을 단일 "-"로 접고, 다시 양끝 "-"만
+// 잘라낸다. ASCII 기준이라 비ASCII 글자(한글 등)는 영숫자가 아니므로 구분자로 취급된다.
+export const slugify = (str: string): string => {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+};

package/templates/string/strip-tags/index.ts

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

package/templates/string/strip-tags/strip-tags.ts

@@ -0,0 +1,8 @@
+// `<tag>`, `</tag>`, `<tag attr>` 같은 HTML 태그만 제거하고 사이 텍스트는 남긴다.
+// 입력은 변형하지 않고 새 문자열을 반환한다.
+//
+// `<\/?[a-zA-Z][^>]*>` — `<` 또는 `</` 뒤에 글자로 시작하는 것만 태그로 본다.
+// 덕분에 "1 < 2 and 3 > 2" 처럼 글자가 아닌 게 따라오는 단독 부등호는 그대로 남는다.
+export const stripTags = (str: string): string => {
+  return str.replace(/<\/?[a-zA-Z][^>]*>/g, "");
+};

package/templates/string/template/index.ts

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

package/templates/string/template/template.ts

@@ -0,0 +1,14 @@
+// str 안의 `{key}` 자리표시자를 data[key] 값으로 치환한다.
+// data에 없는 key의 `{key}`는 그대로 둔다 (입력은 변형하지 않고 새 문자열을 반환).
+//
+// 정규식 `/\{(\w+)\}/g`로 한 번 훑으며 매칭만 교체한다. key는 영숫자/언더스코어(\w)만
+// 받으므로 `{` 만 있고 닫히지 않은 텍스트나 `{ key }` 같은 공백 포함 형태는 매칭되지 않아
+// 원문이 보존된다. 값이 number면 String()으로 문자열화한다.
+const PLACEHOLDER = /\{(\w+)\}/g;
+
+export const template = (str: string, data: Record<string, string | number>): string => {
+  return str.replace(PLACEHOLDER, (match, key: string) => {
+    const value = data[key];
+    return value === undefined ? match : String(value);
+  });
+};

package/templates/string/truncate/index.ts

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

package/templates/string/truncate/truncate.ts

@@ -0,0 +1,17 @@
+// 문자열이 length 이하면 그대로 두고, 초과하면 뒤를 잘라 suffix를 붙인다.
+// 핵심은 "결과 전체 길이"가 length가 되도록 맞추는 것이다. 그래서 잘라낼
+// 본문 길이는 length - suffix.length가 된다 (suffix 자리를 미리 비워 둔다).
+// length가 suffix보다 짧은 극단(예: length 1, suffix "…")에서는 본문이 음수로
+// 가지 않게 막고, suffix 자체를 length까지만 잘라 돌려준다.
+export const truncate = (str: string, length: number, suffix = "…"): string => {
+  if (str.length <= length) {
+    return str;
+  }
+
+  // suffix가 length를 다 차지하거나 넘으면 본문이 들어갈 자리가 없다.
+  if (suffix.length >= length) {
+    return suffix.slice(0, length);
+  }
+
+  return str.slice(0, length - suffix.length) + suffix;
+};

package/templates/string/truncate-middle/index.ts

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

package/templates/string/truncate-middle/truncate-middle.ts

@@ -0,0 +1,25 @@
+// 가운데를 잘라 양끝을 보존한다. 긴 파일명/경로를 "long…name.txt"처럼
+// 줄일 때 쓴다. length 이하면 그대로 둔다.
+// 결과 전체 길이가 length가 되도록 suffix 자리를 먼저 빼고, 남은 길이를
+// 앞쪽(head)과 뒤쪽(tail)에 나눠 준다. 홀수 잔여는 head에 더해 앞을 더 보존한다.
+// length가 suffix 이하인 극단에서는 본문 자리가 없으므로 suffix를 length까지만
+// 잘라 돌려준다.
+export const truncateMiddle = (str: string, length: number, suffix = "…"): string => {
+  if (str.length <= length) {
+    return str;
+  }
+
+  if (suffix.length >= length) {
+    return suffix.slice(0, length);
+  }
+
+  const visible = length - suffix.length;
+  const headLength = Math.ceil(visible / 2);
+  const tailLength = visible - headLength;
+
+  const head = str.slice(0, headLength);
+  // tailLength가 0이면 빈 문자열이어야 한다. slice(-0)은 전체를 반환하므로 분기한다.
+  const tail = tailLength === 0 ? "" : str.slice(-tailLength);
+
+  return head + suffix + tail;
+};

package/templates/string/uuid/index.ts

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

package/templates/string/uuid/uuid.ts

@@ -0,0 +1,9 @@
+// Node 18 이하라면
+import { randomUUID } from "node:crypto";
+
+export const uuid = () => {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return randomUUID();
+};

package/templates/tailwindcss/class-variant/class-variant.ts

@@ -0,0 +1,35 @@
+import { type VariantProps, createTV } from "tailwind-variants";
+import { type TWMergeConfig, twMergeConfig as defaultTwMergeConfig } from "../tw-merge-config/index";
+
+export type { VariantProps };
+
+export type ClassVariant = ReturnType<typeof createTV>;
+
+/**
+ * 지정한 tailwind-merge 설정을 사용하는 variant 기반 className 빌더를 만든다.
+ */
+export const createClassVariant = (twMergeConfig: TWMergeConfig = defaultTwMergeConfig): ClassVariant =>
+  createTV({ twMergeConfig });
+
+/**
+ * `tailwind-variants`의 `tv`를 감싸 variant 기반 className 빌더를 만든다.
+ *
+ * `cn`과 동일한 {@link twMergeConfig}를 공유하므로 variant 병합 시에도 같은
+ * Tailwind 충돌 규칙이 적용된다. 컴포넌트의 variant prop 타입은 `VariantProps`로
+ * 추론할 수 있다.
+ *
+ * @example
+ * const button = classVariant({
+ *   base: "rounded font-medium",
+ *   variants: {
+ *     intent: { primary: "bg-blue-500 text-white", ghost: "bg-transparent" },
+ *     size: { sm: "px-2 py-1", lg: "px-4 py-2" },
+ *   },
+ *   defaultVariants: { intent: "primary", size: "sm" },
+ * });
+ *
+ * button({ intent: "ghost", size: "lg" });
+ *
+ * type ButtonVariants = VariantProps<typeof button>;
+ */
+export const classVariant = createClassVariant();

package/templates/tailwindcss/class-variant/index.ts

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

package/templates/tailwindcss/cn/cn.ts

@@ -0,0 +1,29 @@
+import { type ClassValue, clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+import { type TWMergeConfig, twMergeConfig as defaultTwMergeConfig } from "../tw-merge-config/index";
+
+export type Cn = (...inputs: ClassValue[]) => string;
+
+export type { ClassValue };
+
+/**
+ * 지정한 tailwind-merge 설정을 사용하는 `cn` 함수를 만든다.
+ */
+export const createCn = (twMergeConfig: TWMergeConfig = defaultTwMergeConfig): Cn => {
+  const twMerge = extendTailwindMerge<string, string>(twMergeConfig);
+
+  return (...inputs) => twMerge(clsx(inputs));
+};
+
+/**
+ * 조건부 className을 합치고 충돌하는 Tailwind 클래스를 정리한다.
+ *
+ * `clsx`로 문자열, 배열, 객체 형태의 입력을 하나의 문자열로 합친 뒤
+ * `tailwind-merge`로 같은 속성을 다투는 클래스 중 뒤에 온 값만 남긴다.
+ * 병합 동작은 {@link twMergeConfig}를 따르며 `classVariant`와 설정을 공유한다.
+ *
+ * @example
+ * cn("px-2 py-1", "px-4"); // "py-1 px-4"
+ * cn("text-sm", { "font-bold": isActive });
+ */
+export const cn = createCn();

package/templates/tailwindcss/cn/index.ts

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

package/templates/tailwindcss/create-tailwind-css/create-tailwind-css.ts

@@ -0,0 +1,16 @@
+import { type ClassVariant, createClassVariant } from "../class-variant/index";
+import { type Cn, createCn } from "../cn/index";
+import { type TWMergeConfig, twMergeConfig as defaultTwMergeConfig } from "../tw-merge-config/index";
+
+export type TailwindCssHelpers = {
+  cn: Cn;
+  classVariant: ClassVariant;
+};
+
+/**
+ * 지정한 tailwind-merge 설정을 공유하는 className helper 세트를 만든다.
+ */
+export const createTailwindCss = (twMergeConfig: TWMergeConfig = defaultTwMergeConfig): TailwindCssHelpers => ({
+  cn: createCn(twMergeConfig),
+  classVariant: createClassVariant(twMergeConfig),
+});

package/templates/tailwindcss/create-tailwind-css/index.ts

@@ -0,0 +1 @@
+export * from "./create-tailwind-css";

package/templates/tailwindcss/tw-merge-config/index.ts

@@ -0,0 +1 @@
+export * from "./tw-merge-config";

package/templates/tailwindcss/tw-merge-config/tw-merge-config.ts

@@ -0,0 +1,14 @@
+import type { TWMergeConfig } from "tailwind-variants";
+
+export type { TWMergeConfig };
+
+/**
+ * `cn`과 `classVariant`가 함께 사용하는 tailwind-merge 설정.
+ *
+ * 프로젝트 고유 Tailwind 토큰(커스텀 색상, spacing, classGroup 등)을 여기에
+ * 추가하면 `cn`의 충돌 정리와 `classVariant`의 variant 머지에 동시에 반영된다.
+ * 기본값은 빈 설정이며 이 경우 tailwind-merge 기본 동작을 그대로 따른다.
+ *
+ * @see https://github.com/dcastil/tailwind-merge/blob/main/docs/configuration.md
+ */
+export const twMergeConfig: TWMergeConfig = {};

package/templates/type/get-type/get-type.ts

@@ -0,0 +1,27 @@
+export type TypeofResult =
+  | "undefined"
+  | "object"
+  | "boolean"
+  | "number"
+  | "bigint"
+  | "string"
+  | "symbol"
+  | "function"
+  | "array"
+  | "null";
+
+export const getType = (target: unknown): TypeofResult => {
+  if (typeof target !== "object") {
+    return typeof target;
+  }
+
+  if (target === null) {
+    return "null";
+  }
+
+  if (Array.isArray(target)) {
+    return "array";
+  }
+
+  return "object";
+};

package/templates/type/get-type/index.ts

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

package/templates/type/is-type-of/index.ts

@@ -0,0 +1 @@
+export * from "./is-type-of";

package/templates/type/is-type-of/is-type-of.ts

@@ -0,0 +1,26 @@
+import { type TypeofResult, getType } from "../get-type/index";
+
+export const isTypeOf = (
+  target: unknown,
+  expectedType: TypeofResult,
+  options?: {
+    debug?: boolean;
+    onDebug?: (param: {
+      expectedType: TypeofResult;
+      nowType: TypeofResult;
+    }) => void;
+  },
+) => {
+  const nowType = getType(target);
+
+  const result = nowType === expectedType;
+
+  if (options?.debug) {
+    if (!result) {
+      console.info({ expectedType, nowType });
+      options?.onDebug?.({ expectedType, nowType });
+    }
+  }
+
+  return nowType === expectedType;
+};

package/templates/util/mutex/index.ts

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

package/templates/util/mutex/mutex.ts

@@ -0,0 +1,109 @@
+import { Queue } from "../../data-structure/queue/index";
+
+const createTimeoutError = () => new Error("Mutex lock timeout");
+const createAbortError = () => new Error("Mutex lock aborted");
+
+type LockOptions = {
+  timeout?: number; // ms
+  signal?: AbortSignal;
+};
+
+export class Mutex<T> {
+  private waitOrderQueue = new Queue<(value?: unknown) => void>();
+  private locked = false;
+
+  /**
+   * register promiseQueue
+   */
+  private wait() {
+    return new Promise((resolve) => {
+      this.waitOrderQueue.enqueue(resolve);
+    });
+  }
+
+  /**
+   * 다음 작업 실행
+   */
+  private next() {
+    const nextResolve = this.waitOrderQueue.dequeue();
+    if (nextResolve) {
+      nextResolve();
+    } else {
+      this.locked = false;
+    }
+  }
+
+  /**
+   * run with locked: true
+   */
+  public async lock<T>(callback: () => Promise<T>, { timeout, signal }: LockOptions = {}): Promise<T> {
+    if (this.locked) {
+      const wait = this.wait();
+
+      if (timeout != null || signal) {
+        await Promise.race([
+          wait,
+          ...(timeout != null ? [this.createTimeout(timeout)] : []),
+          ...(signal ? [this.createAbort(signal)] : []),
+        ]);
+      } else {
+        await wait;
+      }
+    }
+
+    this.locked = true;
+
+    try {
+      return await callback();
+    } finally {
+      this.next();
+    }
+  }
+
+  /**
+   * locked true: return null
+   * locked false: locked + run callback
+   */
+  public async spinLock<T>(callback: () => Promise<T>): Promise<T | null> {
+    if (this.locked) return null;
+
+    this.locked = true;
+
+    try {
+      return await callback();
+    } finally {
+      this.next();
+    }
+  }
+
+  /**
+   * timeout helper
+   */
+  private createTimeout(ms: number): Promise<never> {
+    return new Promise((_, reject) => {
+      const id = setTimeout(() => {
+        clearTimeout(id);
+        reject(createTimeoutError());
+      }, ms);
+    });
+  }
+
+  /**
+   * abort helper
+   */
+  private createAbort(signal: AbortSignal): Promise<never> {
+    return new Promise((_, reject) => {
+      if (signal.aborted) {
+        reject(createAbortError());
+        return;
+      }
+
+      const abort = () => {
+        signal.removeEventListener("abort", abort);
+        reject(createAbortError());
+      };
+
+      signal.addEventListener("abort", abort);
+    });
+  }
+}

package/templates/util/url-parser/index.ts

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

package/templates/util/url-parser/url-parser.ts

@@ -0,0 +1,44 @@
+type URLQuery = Record<string, string | string[]>;
+
+export class URLParser {
+  private toURL(url: string): URL {
+    try {
+      return new URL(url);
+    } catch {
+      return new URL(decodeURIComponent(url));
+    }
+  }
+
+  getQuery(url: string): URLQuery {
+    const result: URLQuery = {};
+    const parsedUrl = this.toURL(url);
+
+    parsedUrl.searchParams.forEach((value, key) => {
+      const previousValue = result[key];
+
+      if (Array.isArray(previousValue)) {
+        previousValue.push(value);
+        return;
+      }
+
+      if (previousValue !== undefined) {
+        result[key] = [previousValue, value];
+        return;
+      }
+
+      result[key] = value;
+    });
+
+    return result;
+  }
+
+  getFragment(url: string): string {
+    const parsedUrl = this.toURL(url);
+
+    return decodeURIComponent(parsedUrl.hash.slice(1));
+  }
+
+  getOrigin(url: string): string {
+    return this.toURL(url).origin;
+  }
+}