akanjs 0.0.1 → 2.0.0-beta.0

package/common/index.ts

@@ -0,0 +1,50 @@
+export { applyMixins } from "./applyMixins";
+export { capitalize } from "./capitalize";
+export { deepObjectify } from "./deepObjectify";
+export { formatNumber } from "./formatNumber";
+export { formatPhone } from "./formatPhone";
+export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors";
+export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase";
+export { HttpClient } from "./httpClient";
+export { isDayjs } from "./isDayjs";
+export { isEmail } from "./isEmail";
+export { isPhoneNumber } from "./isPhoneNumber";
+export { isQueryEqual } from "./isQueryEqual";
+export { isValidDate } from "./isValidDate";
+export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger";
+export {
+  type AkanI18nConfig,
+  type AkanI18nConfigInput,
+  DEFAULT_AKAN_I18N,
+  parseAkanI18nEnv,
+  resolveAkanI18nConfig,
+} from "./localeConfig";
+export { lowerlize } from "./lowerlize";
+export { mergeVersion } from "./mergeVersion";
+export { objectify } from "./objectify";
+export { pathGet } from "./pathGet";
+export { pathSet } from "./pathSet";
+export { randomPick } from "./randomPick";
+export { randomPicks } from "./randomPicks";
+export {
+  assertUniqueRoutePatterns,
+  compareRouteSpecificity,
+  isRouteSourceFile,
+  isSpecialRouteLeaf,
+  matchRoutePattern,
+  normalizeRoutePattern,
+  type ParsedRouteModuleKey,
+  parseRouteModuleKey,
+  type RouteModuleKind,
+  routeSegmentToPatternPart,
+  routeSegmentToTreePath,
+  tryParseRouteModuleKey,
+  type ValidatePageSourceFileOptions,
+  type ValidateSubRoutePageKeyOptions,
+  validatePageSourceFile,
+  validateSubRoutePageKey,
+} from "./routeConvention";
+export { sleep } from "./sleep";
+export { splitVersion } from "./splitVersion";
+export { getBasePathFromPathname, parseBasePaths } from "./subRoute";
+export type * from "./types";

package/common/isDayjs.ts

@@ -0,0 +1,3 @@
+import dayjs from "dayjs";
+
+export const isDayjs = dayjs.isDayjs;

package/common/isEmail.ts

@@ -0,0 +1,2 @@
+/** Returns true when the value matches the email format accepted by Akan forms. */
+export const isEmail = (email?: string | null) => !!email && /^\w+([.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,8})+$/.test(email);

package/common/isPhoneNumber.ts

@@ -0,0 +1,8 @@
+/** Returns true when the value matches Akan's supported dashed phone-number format. */
+export const isPhoneNumber = (phone?: string | null) => {
+  if (!phone) return false;
+  const comp = phone.startsWith("0") ? phone.slice(1) : phone;
+  const regExp1 = /^\(?([0-9]{2})\)?[-. ]?([0-9]{4})[-. ]?([0-9]{4})$/;
+  const regExp2 = /^\(?([0-9]{2})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;
+  return (regExp1.test(comp) || regExp2.test(comp)) && phone.split("-").length === 3;
+};

package/common/isQueryEqual.ts

@@ -0,0 +1,23 @@
+import dayjs from "dayjs";
+
+import { isDayjs } from "./isDayjs";
+
+export const isQueryEqual = (value1: unknown, value2: unknown) => {
+  if (value1 === value2) return true;
+  if (Array.isArray(value1) && Array.isArray(value2)) {
+    if (value1.length !== value2.length) return false;
+    for (let i = 0; i < value1.length; i++) if (!isQueryEqual(value1[i], value2[i])) return false;
+    return true;
+  }
+  if ([value1, value2].some((val) => val instanceof Date || isDayjs(val)))
+    return dayjs(value1 as Date).isSame(dayjs(value2 as Date));
+  if (typeof value1 === "object" && typeof value2 === "object") {
+    if (value1 === null || value2 === null) return value1 === value2;
+    if (Object.keys(value1).length !== Object.keys(value2).length) return false;
+    const v1 = value1 as Record<string, unknown>;
+    const v2 = value2 as Record<string, unknown>;
+    for (const key of Object.keys(value1)) if (!isQueryEqual(v1[key], v2[key])) return false;
+    return true;
+  }
+  return false;
+};

package/common/isValidDate.ts

@@ -0,0 +1,14 @@
+import dayjs, { type Dayjs } from "dayjs";
+import customParseFormat from "dayjs/plugin/customParseFormat.js";
+
+import { isDayjs } from "./isDayjs";
+
+dayjs.extend(customParseFormat);
+
+export const isValidDate = (d: string | Date | Dayjs) => {
+  const format = "YYYY-MM-DD";
+  if (typeof d === "string") {
+    return dayjs(d, format).isValid();
+  } else if (isDayjs(d)) return d.isValid();
+  else return d instanceof Date && !isNaN(d.getTime());
+};

package/common/localeConfig.ts

@@ -0,0 +1,41 @@
+export interface AkanI18nConfig {
+  defaultLocale: string;
+  locales: string[];
+}
+
+export interface AkanI18nConfigInput {
+  defaultLocale?: string;
+  locales?: readonly string[];
+}
+
+export const DEFAULT_AKAN_I18N: AkanI18nConfig = Object.freeze({
+  defaultLocale: "en",
+  locales: Object.freeze(["en", "ko"]) as unknown as string[],
+});
+
+const normalizeLocale = (locale: string) => locale.trim();
+
+export function resolveAkanI18nConfig(input: AkanI18nConfigInput = {}): AkanI18nConfig {
+  const locales = [...new Set((input.locales ?? DEFAULT_AKAN_I18N.locales).map(normalizeLocale).filter(Boolean))];
+  const defaultLocale = normalizeLocale(input.defaultLocale ?? DEFAULT_AKAN_I18N.defaultLocale);
+
+  if (locales.length === 0) throw new Error("[i18n] locales must include at least one locale");
+  if (!defaultLocale) throw new Error("[i18n] defaultLocale must not be empty");
+  if (!locales.includes(defaultLocale)) {
+    throw new Error(`[i18n] defaultLocale "${defaultLocale}" must be included in locales: ${locales.join(",")}`);
+  }
+
+  return { defaultLocale, locales };
+}
+
+export function parseAkanI18nEnv(
+  env: Record<string, string | undefined> = {
+    AKAN_PUBLIC_DEFAULT_LOCALE: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_DEFAULT_LOCALE : undefined,
+    AKAN_PUBLIC_LOCALES: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_LOCALES : undefined,
+  },
+): AkanI18nConfig {
+  return resolveAkanI18nConfig({
+    defaultLocale: env.AKAN_PUBLIC_DEFAULT_LOCALE,
+    locales: env.AKAN_PUBLIC_LOCALES?.split(","),
+  });
+}

package/common/lowerlize.ts

@@ -0,0 +1,4 @@
+/** Lowercases only the first character of a string. */
+export const lowerlize = (str: string) => {
+  return str.charAt(0).toLowerCase() + str.slice(1);
+};

package/common/mergeVersion.ts

@@ -0,0 +1,10 @@
+/**
+ *
+ * semantic version 규격에 맞게 조합하는 함수
+ * https://semver.org/
+ * @param major 릴리즈(플랫폼(google,apple,etc...)에 올라가 있는) 버전
+ * @param minor 릴리즈(플랫폼(google,apple,etc...)에 올라가 있는) 버전
+ * @param patch 코드푸시 (Framework 자체 버전)
+ * @returns `major.minor.patch` 형식으로 조합된 버전
+ */
+export const mergeVersion = (major: number, minor: number, patch: number) => `${major}.${minor}.${patch}`;

package/common/objectify.ts

@@ -0,0 +1,7 @@
+export const objectify = <T extends object>(obj: T, keys = Object.keys(obj) as (keyof T)[]): Partial<T> => {
+  const val: Partial<T> = {};
+  keys.forEach((key) => {
+    if (typeof obj[key] !== "function") val[key] = obj[key];
+  });
+  return val;
+};

package/common/pathGet.ts

@@ -0,0 +1,13 @@
+type Indexable = Record<string | number, unknown>;
+
+const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
+
+export const pathGet = (
+  path: string | (string | number)[],
+  obj: unknown,
+  separator = ".",
+  fallback: unknown = null,
+): unknown => {
+  const properties = Array.isArray(path) ? path : path.split(separator);
+  return properties.reduce((prev, curr) => (isIndexable(prev) ? (prev[curr] ?? fallback) : fallback), obj);
+};

package/common/pathSet.ts

@@ -0,0 +1,16 @@
+type MutableIndexable = Record<string | number, unknown>;
+type PathSegment = string | number;
+
+const toPathSegments = (path: string | readonly PathSegment[]) =>
+  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
+
+export const pathSet = <T>(obj: T, path: string | readonly PathSegment[], value: unknown): T => {
+  if (Object(obj) !== obj) return obj;
+  const pathSegments = toPathSegments(path);
+  pathSegments.slice(0, -1).reduce<MutableIndexable>((a, c, i) => {
+    if (Object(a[c]) === a[c]) return a[c] as MutableIndexable;
+    a[c] = Math.abs(Number(pathSegments[i + 1])) >> 0 === +pathSegments[i + 1] ? [] : {};
+    return a[c] as MutableIndexable;
+  }, obj as MutableIndexable)[pathSegments[pathSegments.length - 1]] = value;
+  return obj;
+};

package/common/randomPick.ts

@@ -0,0 +1 @@
+export const randomPick = <T = unknown>(arr: T[] | readonly T[]): T => arr[Math.floor(Math.random() * arr.length)];

package/common/randomPicks.ts

@@ -0,0 +1,12 @@
+export const randomPicks = <T>(arr: T[] | readonly T[], count = 1, allowDuplicate = false): T[] => {
+  if (!allowDuplicate && arr.length <= count) return arr as T[];
+  const idxs: number[] = [];
+  let pickIdx: number;
+  for (let i = 0; i < count; i++) {
+    do {
+      pickIdx = Math.floor(Math.random() * arr.length);
+    } while (!allowDuplicate && idxs.includes(pickIdx));
+    idxs.push(pickIdx);
+  }
+  return idxs.map((idx) => arr[idx]);
+};

package/common/routeConvention.ts

@@ -0,0 +1,203 @@
+const ROUTE_SOURCE_RE = /^\.\/(.+)\.(tsx|ts|jsx|js)$/;
+const SOURCE_EXT_RE = /\.(tsx|ts|jsx|js)$/;
+const RESERVED_ROUTE_FILES = new Set(["_layout", "_index"]);
+const INTERNAL_ROOT_LAYOUT_LEAF = "__root_layout";
+const IMPLICIT_LOCALE_SEGMENT = "[lang]";
+const SPECIAL_ROUTE_LEAVES = new Set(["robots.txt"]);
+
+export type RouteModuleKind = "page" | "layout";
+
+export interface ParsedRouteModuleKey {
+  key: string;
+  kind: RouteModuleKind;
+  routeSegments: string[];
+  moduleSegments: string[];
+  sourceRouteSegments: string[];
+  ext: string;
+  leaf: string;
+  pattern: string;
+  isSpecialRoute: boolean;
+  isInternalRootLayout: boolean;
+}
+
+export interface ValidateSubRoutePageKeyOptions {
+  appName?: string;
+  filePath?: string;
+}
+
+export interface ValidatePageSourceFileOptions {
+  filePath?: string;
+}
+
+export function isRouteSourceFile(filePath: string): boolean {
+  if (!SOURCE_EXT_RE.test(filePath)) return false;
+  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
+  return tryParseRouteModuleKey(key) !== null;
+}
+
+export function validatePageSourceFile(filePath: string, options: ValidatePageSourceFileOptions = {}): boolean {
+  if (!SOURCE_EXT_RE.test(filePath)) return false;
+
+  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
+  const match = ROUTE_SOURCE_RE.exec(key);
+  const displayPath = options.filePath ?? key;
+  if (!match) throw new Error(`[route-convention] invalid page source file: ${displayPath}`);
+
+  const file = match[1] as string;
+  const ext = match[2] as string;
+  const leaf = file.split("/").filter(Boolean).at(-1);
+  if (!leaf) throw new Error(`[route-convention] invalid page source file: ${displayPath}`);
+
+  if (ext !== "tsx") throw new Error(`[route-convention] route source files under page/ must use .tsx: ${displayPath}`);
+  if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && leaf !== INTERNAL_ROOT_LAYOUT_LEAF)
+    throw new Error(
+      `[route-convention] only _index.tsx and _layout.tsx are allowed as reserved route files under page/: ${displayPath}`,
+    );
+  if (/^[A-Z]/.test(leaf))
+    throw new Error(`[route-convention] route page filenames must not start with an uppercase letter: ${displayPath}`);
+  return true;
+}
+
+export function validateSubRoutePageKey(
+  key: string,
+  basePaths: Iterable<string>,
+  options: ValidateSubRoutePageKeyOptions = {},
+): void {
+  const allowedBasePaths = [
+    ...new Set([...basePaths].map((basePath) => basePath.trim().replace(/^\/+|\/+$/g, "")).filter(Boolean)),
+  ];
+  if (allowedBasePaths.length === 0) return;
+
+  const match = ROUTE_SOURCE_RE.exec(key);
+  if (!match) throw new Error(`[route-convention] invalid route module key: ${key}`);
+
+  const moduleSegments = (match[1] as string).split("/").filter(Boolean);
+  const basePath = moduleSegments[0];
+  if (basePath && allowedBasePaths.includes(basePath)) return;
+
+  const appLabel = options.appName ? `app "${options.appName}"` : "app";
+  const invalidRoute = options.filePath ?? key;
+  throw new Error(
+    `[route-convention] ${appLabel} uses subRoutes (${allowedBasePaths.join(", ")}), so route files must live under page/<basePath>. Invalid route file: ${invalidRoute}`,
+  );
+}
+
+export function parseRouteModuleKey(key: string): ParsedRouteModuleKey {
+  const match = ROUTE_SOURCE_RE.exec(key);
+  if (!match) throw new Error(`[route-convention] invalid route module key: ${key}`);
+
+  const file = match[1] as string;
+  const ext = match[2] as string;
+  const moduleSegments = file.split("/").filter(Boolean);
+  const leaf = moduleSegments.at(-1);
+  if (!leaf) throw new Error(`[route-convention] invalid route module key: ${key}`);
+
+  if (moduleSegments.includes(IMPLICIT_LOCALE_SEGMENT)) {
+    throw new Error(`[route-convention] Akan.js injects \`[lang]\` automatically. Move files one level up: ${key}`);
+  }
+
+  const isInternalRootLayout = leaf === INTERNAL_ROOT_LAYOUT_LEAF;
+  const kind: RouteModuleKind = leaf === "_layout" || isInternalRootLayout ? "layout" : "page";
+  if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && !isInternalRootLayout) {
+    throw new Error(`[route-convention] unsupported reserved route file "${leaf}" in ${key}`);
+  }
+
+  const sourceRouteSegments =
+    leaf === "_layout" || leaf === "_index" || isInternalRootLayout ? moduleSegments.slice(0, -1) : moduleSegments;
+  const isSpecialRoute = kind === "page" && SPECIAL_ROUTE_LEAVES.has(leaf);
+  const routeSegments = isSpecialRoute ? sourceRouteSegments : [IMPLICIT_LOCALE_SEGMENT, ...sourceRouteSegments];
+  for (const segment of routeSegments) validateRouteSegment(segment, key);
+
+  return {
+    key,
+    kind,
+    routeSegments,
+    moduleSegments,
+    sourceRouteSegments,
+    ext,
+    leaf,
+    pattern: normalizeRoutePattern(routeSegments),
+    isSpecialRoute,
+    isInternalRootLayout,
+  };
+}
+
+export function isSpecialRouteLeaf(leaf: string): boolean {
+  return SPECIAL_ROUTE_LEAVES.has(leaf);
+}
+
+export function tryParseRouteModuleKey(key: string): ParsedRouteModuleKey | null {
+  try {
+    return parseRouteModuleKey(key);
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeRoutePattern(segments: string[]): string {
+  const parts = segments.map(routeSegmentToPatternPart).filter((part) => part.length > 0);
+  return `/${parts.join("/")}`.replace(/\/+$/, "") || "/";
+}
+
+export function routeSegmentToPatternPart(segment: string): string {
+  if (/^\(.+\)$/.test(segment)) return "";
+  return segment.replace(/^\[([^\]]+)\]$/, ":$1");
+}
+
+export function routeSegmentToTreePath(segment: string): string {
+  return `/${segment.replace(/^\[([^\]]+)\]$/, ":$1")}`;
+}
+
+export function compareRouteSpecificity(a: string, b: string): number {
+  const as = a.split("/").filter(Boolean);
+  const bs = b.split("/").filter(Boolean);
+  const len = Math.min(as.length, bs.length);
+  for (let i = 0; i < len; i++) {
+    const ad = (as[i] ?? "").startsWith(":");
+    const bd = (bs[i] ?? "").startsWith(":");
+    if (ad !== bd) return ad ? 1 : -1;
+  }
+  if (as.length !== bs.length) return bs.length - as.length;
+  const aDyn = as.filter((s) => s.startsWith(":")).length;
+  const bDyn = bs.filter((s) => s.startsWith(":")).length;
+  if (aDyn !== bDyn) return aDyn - bDyn;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+export function matchRoutePattern(pattern: string, pathname: string): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = pathname.split("/").filter(Boolean);
+  if (patternParts.length !== pathParts.length) return null;
+
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const pat = patternParts[i] ?? "";
+    const val = pathParts[i] ?? "";
+    if (pat.startsWith(":")) params[pat.slice(1)] = decodeURIComponent(val);
+    else if (pat !== val) return null;
+  }
+  return params;
+}
+
+export function assertUniqueRoutePatterns(entries: { key: string; pattern: string }[]): void {
+  const byPattern = new Map<string, string>();
+  for (const entry of entries) {
+    const prev = byPattern.get(entry.pattern);
+    if (prev) {
+      throw new Error(
+        `[route-convention] route conflict for "${entry.pattern}": ${prev} and ${entry.key} resolve to the same URL`,
+      );
+    }
+    byPattern.set(entry.pattern, entry.key);
+  }
+}
+
+function validateRouteSegment(segment: string, key: string): void {
+  if (segment.includes("[...") || segment.includes("[[...")) {
+    throw new Error(`[route-convention] catch-all routes are not supported yet: ${key}`);
+  }
+  const dynamic = /^\[(.+)\]$/.exec(segment);
+  if (dynamic && (dynamic[1]?.includes("[") || dynamic[1]?.includes("]") || dynamic[1]?.startsWith("..."))) {
+    throw new Error(`[route-convention] invalid dynamic route segment "${segment}" in ${key}`);
+  }
+}

package/common/sleep.ts

@@ -0,0 +1,8 @@
+/** Resolves after the requested delay in milliseconds. */
+export const sleep = async (ms: number) => {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(true);
+    }, ms);
+  });
+};

package/common/splitVersion.ts

@@ -0,0 +1,11 @@
+/**
+ *
+ * semantic version 규격에 맞게 major, minor, patch로 나누는 함수
+ * https://semver.org/
+ * @params version `major.minor.patch` 형식으로 조합된 버전
+ */
+export const splitVersion = (version: string) => {
+  const [major, minor, patch] = version.split(".");
+  if (!major || !minor || !patch) throw new Error("Invalid version");
+  return { major, minor, patch };
+};

package/common/subRoute.ts

@@ -0,0 +1,34 @@
+import type { AkanI18nConfig } from "./localeConfig";
+
+export const parseBasePaths = (value: string | string[] | Set<string> | undefined | null): string[] => {
+  const items =
+    typeof value === "string"
+      ? value.split(",")
+      : value instanceof Set
+        ? [...value]
+        : Array.isArray(value)
+          ? value
+          : [];
+  return [...new Set(items.map((basePath) => basePath.trim()).filter(Boolean))];
+};
+
+export const getBasePathFromPathname = (
+  pathname: string,
+  {
+    basePaths,
+    i18n,
+    headerBasePath,
+  }: {
+    basePaths: Iterable<string>;
+    i18n?: Pick<AkanI18nConfig, "locales" | "defaultLocale">;
+    headerBasePath?: string | null;
+  },
+): string | null => {
+  const configuredBasePaths = new Set(parseBasePaths([...basePaths]));
+  if (headerBasePath && configuredBasePaths.has(headerBasePath)) return headerBasePath;
+
+  const segments = pathname.split("/").filter(Boolean);
+  const locales = new Set(i18n?.locales ?? (i18n?.defaultLocale ? [i18n.defaultLocale] : []));
+  const maybeBasePath = locales.has(segments[0] ?? "") ? segments[1] : segments[0];
+  return maybeBasePath && configuredBasePaths.has(maybeBasePath) ? maybeBasePath : null;
+};

package/common/types.ts

@@ -0,0 +1,15 @@
+export interface FetchPolicy<Returns = unknown> {
+  cache?: boolean | number;
+  crystalize?: boolean;
+  url?: string;
+  onError?: (error: string) => void;
+  token?: string;
+  partial?: string[];
+  timeout?: number;
+}
+
+export type SnakeCase<S extends string> = S extends `${infer T}_${infer U}` ? `${Lowercase<T>}_${SnakeCase<U>}` : S;
+export type SnakeCaseObj<T> = {
+  [K in keyof T as SnakeCase<K & string>]: T[K] extends object ? SnakeCaseObj<T[K]> : T[K];
+};
+export type SnakeMsg<Msg> = SnakeCaseObj<Msg>;