@vimcord/internal 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Deep partial type utility - recursively makes all properties optional.
+ * Preserves function types to maintain their signatures.
+ */
+type PartialDeep<T> = T extends (...args: unknown[]) => unknown ? T : T extends object ? T extends ReadonlyArray<infer U> ? ReadonlyArray<PartialDeep<U>> : T extends Array<infer U> ? Array<PartialDeep<U>> : {
+    [K in keyof T]?: PartialDeep<T[K]>;
+} : T;
+/** A function used for indexing something. */
+type IndexFn<T> = (module: T) => string | string[] | undefined;
+
+declare class VimcordError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+/** Ensures a value is always returned as an array */
+declare function forceArray<T>(value: T | T[]): T[];
+
+interface ImportedModule<T> {
+    module: T;
+    path: string;
+}
+declare function getProcessDir(): string;
+declare function isTSOrJS(filename: string, suffix?: string | string[]): boolean;
+declare function importModulesFromDir<T>(dir: string, suffix?: string | string[]): Promise<ImportedModule<T>[]>;
+
+type LogLevel = "debug" | "info" | "success" | "warn" | "error";
+type ColorScheme = {
+    primary: string;
+    success: string;
+    warn: string;
+    caution: string;
+    error: string;
+    muted: string;
+    info: string;
+    text: string;
+};
+type LoggerOptions = {
+    /** Emoji shown before the prefix. */
+    prefixEmoji?: string | null;
+    /** Prefix label shown before each message. */
+    prefix?: string | null;
+    /**
+     * Minimum log level to output.
+     * @default "debug"
+     */
+    minLevel?: LogLevel;
+    /**
+     * Log verbose messages.
+     * @default false
+     */
+    verbose?: boolean;
+    /** Color scheme to use. */
+    colors?: Partial<ColorScheme>;
+};
+type LoaderOptions = {
+    /** Returns the next loader message while the spinner is active. */
+    cycle?: () => string;
+    /** How often `cycle` should be called in milliseconds. */
+    interval?: number;
+};
+declare const DEFAULT_COLORS: ColorScheme;
+/** Strips ANSI escape codes from a string for accurate length measurement */
+declare function stripAnsi(str: string): string;
+/** Timestamped console logger with level filtering, colors, and optional live terminal loaders. */
+declare class Logger {
+    readonly options: Required<LoggerOptions> & {
+        colors: ColorScheme;
+    };
+    private activeLoaders;
+    private nextLoaderId;
+    private renderInterval;
+    private frameIndex;
+    constructor(options?: LoggerOptions);
+    private formatPrefix;
+    private formatLevel;
+    /** Checks if the given log level should be logged. */
+    private shouldLog;
+    /** Returns a colored `[HH:mm:ss]` timestamp for log prefixes. */
+    timestamp(): string;
+    /** Writes a line using the builtin `console`, keeping active TTY loaders pinned below the new output. */
+    write(stream: "log" | "warn" | "error", ...data: unknown[]): void;
+    /** Logs a message without level filtering. */
+    log(...data: unknown[]): void;
+    logVerbose(...data: unknown[]): void;
+    debug(message: string, ...data: unknown[]): void;
+    debugVerbose(message: string, ...data: unknown[]): void;
+    info(...data: unknown[]): void;
+    infoVerbose(...data: unknown[]): void;
+    success(message: string, ...data: unknown[]): void;
+    successVerbose(message: string, ...data: unknown[]): void;
+    warn(message: string, ...data: unknown[]): void;
+    warnVerbose(message: string, ...data: unknown[]): void;
+    error(message: string, error?: Error, ...data: unknown[]): void;
+    errorVerbose(message: string, error?: Error, ...data: unknown[]): void;
+    /** @deprecated */
+    table(title: string, data: Record<string, unknown>): void;
+    /** @deprecated */
+    section(title: string): void;
+    /**
+     * Starts a loader and returns a `stop` function.
+     *
+     * In an interactive TTY, loaders render as live spinners pinned below regular logs. In hosted logs, CI,
+     * Docker logs, and other non-TTY streams, loaders degrade to normal start/final lines without ANSI cursor codes.
+     * Always call `stop()` with `try/finally` so the render loop can be cleaned up.
+     *
+     * @param message Initial loader message.
+     * @param cycleOrOptions Optional message cycle function or options object.
+     * @param interval How often to call the cycle function in milliseconds. Defaults to `3000`.
+     * @returns A function that stops the loader. Pass `clear: true` to suppress the success line.
+     *
+     * @example
+     * ```ts
+     * const stop = logger.loader("Loading...")
+     * try {
+     *   await doWork()
+     *   stop("Done!")
+     * } catch (e) {
+     *   stop("Failed")
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * const stop = logger.loader("Starting...", () => "Still starting...", 1000)
+     * ```
+     */
+    loader(message: string, cycle?: () => string, interval?: number): (finalMessage?: string, clear?: boolean) => void;
+    loader(message: string, options?: LoaderOptions): (finalMessage?: string, clear?: boolean) => void;
+    /** Sets the minimum log level required for level-filtered messages. */
+    setLevel(level: LogLevel): void;
+    /** Enables or disables verbose-only log methods. */
+    setVerbose(verbose: boolean): void;
+}
+
+/** Deep merge objects - mutates target and returns it */
+declare function mergeDeep<T extends object>(target: PartialDeep<T>, ...sources: Array<object | undefined>): T;
+
+/** Reads the `package.json` file from the current working directory. */
+declare function getPackageJson(): Record<string, unknown>;
+/** Checks if the process was ran using the `--dev` flag. */
+declare function getDevMode(): boolean;
+
+declare function createRandomId(): string;
+declare function createHumanId(): string;
+
+export { type ColorScheme, DEFAULT_COLORS, type IndexFn, type LoaderOptions, type LogLevel, Logger, type LoggerOptions, type PartialDeep, VimcordError, createHumanId, createRandomId, forceArray, getDevMode, getPackageJson, getProcessDir, importModulesFromDir, isTSOrJS, mergeDeep, stripAnsi };

package/dist/index.js

@@ -0,0 +1,405 @@
+// src/utils/VimcordError.ts
+var VimcordError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "VimcordError";
+  }
+  code;
+};
+
+// src/utils/arr.ts
+function forceArray(value) {
+  return Array.isArray(value) ? value : [value];
+}
+
+// src/utils/import.ts
+import { existsSync, readdirSync } from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+function getProcessDir() {
+  const mainPath = process.argv[1];
+  if (!mainPath) return "";
+  return path.dirname(mainPath);
+}
+function isTSOrJS(filename, suffix) {
+  if (!suffix) return filename.endsWith(".ts") || filename.endsWith(".js");
+  if (Array.isArray(suffix)) {
+    return suffix.some((s) => filename.endsWith(`${s}.ts`) || filename.endsWith(`${s}.js`));
+  } else {
+    return filename.endsWith(`${suffix}.ts`) || filename.endsWith(`${suffix}.js`);
+  }
+}
+async function importModulesFromDir(dir, suffix) {
+  const cwd = getProcessDir();
+  const MODULE_RELATIVE_PATH = path.join(cwd, dir);
+  const MODULE_LOG_PATH = dir;
+  const files = (() => {
+    if (!existsSync(MODULE_RELATIVE_PATH)) return [];
+    const walk = (targetDir, base = "") => {
+      return readdirSync(targetDir, { withFileTypes: true }).flatMap((entry) => {
+        const relativePath = base ? path.join(base, entry.name) : entry.name;
+        const fullPath = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) return walk(fullPath, relativePath);
+        if (entry.isFile()) return [relativePath];
+        return [];
+      });
+    };
+    return walk(MODULE_RELATIVE_PATH);
+  })().filter((filename) => isTSOrJS(filename, suffix));
+  if (!files.length) return [];
+  const modules = await Promise.all(
+    files.map(async (fn) => {
+      const modulePath = path.join(MODULE_RELATIVE_PATH, fn);
+      const logPath = `./${path.join(MODULE_LOG_PATH, fn)}`;
+      try {
+        const moduleUrl = pathToFileURL(modulePath);
+        moduleUrl.searchParams.set("updated", Date.now().toString());
+        const importedModule = await import(moduleUrl.href);
+        return { module: importedModule, path: logPath };
+      } catch (err) {
+        console.warn(`Failed to import module at '${logPath}'`, err);
+        return null;
+      }
+    })
+  );
+  const filteredModules = modules.filter((m) => Boolean(m));
+  if (!filteredModules.length) {
+    console.warn(`No valid modules were found in directory '${dir}'`);
+  }
+  return filteredModules;
+}
+
+// src/utils/Logger.ts
+import ansis from "ansis";
+import { spinners } from "unicode-animations";
+var LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  success: 2,
+  warn: 3,
+  error: 4
+};
+var DEFAULT_COLORS = {
+  primary: "#5865F2",
+  success: "#57F287",
+  warn: "#FEE75C",
+  caution: "#FF9D00",
+  error: "#ED4245",
+  muted: "#747F8D",
+  info: "#87CEEB",
+  text: "#FFFFFF"
+};
+var SPINNER_FRAMES = spinners.breathe.frames.map((f) => ansis.hex(DEFAULT_COLORS.muted)(f));
+var SPINNER_INTERVAL = spinners.breathe.interval;
+var DEFAULT_LOADER_CYCLE_INTERVAL_MS = 3e3;
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+function padVisible(str, length) {
+  const visible = stripAnsi(str).length;
+  return str + " ".repeat(Math.max(0, length - visible));
+}
+var Logger = class {
+  options;
+  activeLoaders = /* @__PURE__ */ new Map();
+  nextLoaderId = 0;
+  renderInterval = null;
+  frameIndex = 0;
+  constructor(options = {}) {
+    this.options = {
+      prefix: null,
+      prefixEmoji: null,
+      minLevel: "debug",
+      verbose: false,
+      ...options,
+      colors: { ...DEFAULT_COLORS, ...options.colors }
+    };
+  }
+  formatPrefix() {
+    const { prefixEmoji, prefix, colors } = this.options;
+    if (!prefix) return "";
+    const emoji = prefixEmoji ? `${prefixEmoji} ` : "";
+    return ansis.bold.hex(colors.primary)(`${emoji}${prefix}`);
+  }
+  formatLevel(level) {
+    const { colors } = this.options;
+    switch (level) {
+      case "debug":
+        return ansis.hex(colors.muted)("DEBUG");
+      case "info":
+        return ansis.hex(colors.info)("INFO");
+      case "success":
+        return ansis.bold.hex(colors.success)("\u2713 SUCCESS");
+      case "warn":
+        return ansis.bold.hex(colors.warn)("\u26A0 WARN");
+      case "error":
+        return ansis.bold.hex(colors.error)("\u2715 ERROR");
+    }
+  }
+  /** Checks if the given log level should be logged. */
+  shouldLog(level) {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.options.minLevel];
+  }
+  /** Returns a colored `[HH:mm:ss]` timestamp for log prefixes. */
+  timestamp() {
+    const { colors } = this.options;
+    const now = /* @__PURE__ */ new Date();
+    const time = now.toLocaleTimeString("en-US", {
+      hour12: false,
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit"
+    });
+    return ansis.hex(colors.muted)(`[${time}]`);
+  }
+  /** Writes a line using the builtin `console`, keeping active TTY loaders pinned below the new output. */
+  write(stream, ...data) {
+    const loaderCount = this.activeLoaders.size;
+    const shouldRedrawLoaders = process.stdout.isTTY === true && loaderCount > 0;
+    if (shouldRedrawLoaders) process.stdout.write(`\x1B[${loaderCount}A\x1B[J`);
+    console[stream](...data);
+    if (!shouldRedrawLoaders) return;
+    const now = Date.now();
+    const frame = SPINNER_FRAMES[this.frameIndex];
+    for (const [, loader] of this.activeLoaders) {
+      if (loader.cycle && now - loader.lastCycleAt >= loader.cycleInterval) {
+        loader.message = loader.cycle();
+        loader.lastCycleAt = now;
+      }
+      process.stdout.write(`${this.timestamp()} ${this.formatPrefix()} ${frame} ${loader.message}
+`);
+    }
+  }
+  /** Logs a message without level filtering. */
+  log(...data) {
+    this.write("log", this.timestamp(), this.formatPrefix(), ...data);
+  }
+  logVerbose(...data) {
+    if (!this.options.verbose) return;
+    this.log(...data);
+  }
+  debug(message, ...data) {
+    if (!this.shouldLog("debug")) return;
+    this.write("log", this.timestamp(), this.formatPrefix(), this.formatLevel("debug"), ansis.dim(message), ...data);
+  }
+  debugVerbose(message, ...data) {
+    if (!this.options.verbose) return;
+    this.debug(message, ...data);
+  }
+  info(...data) {
+    if (!this.shouldLog("info")) return;
+    this.write("log", this.timestamp(), this.formatPrefix(), this.formatLevel("info"), ...data);
+  }
+  infoVerbose(...data) {
+    if (!this.options.verbose) return;
+    this.info(...data);
+  }
+  success(message, ...data) {
+    if (!this.shouldLog("success")) return;
+    this.write(
+      "log",
+      this.timestamp(),
+      this.formatPrefix(),
+      this.formatLevel("success"),
+      ansis.hex(this.options.colors.success)(message),
+      ...data
+    );
+  }
+  successVerbose(message, ...data) {
+    if (!this.options.verbose) return;
+    this.success(message, ...data);
+  }
+  warn(message, ...data) {
+    if (!this.shouldLog("warn")) return;
+    this.write(
+      "warn",
+      this.timestamp(),
+      this.formatPrefix(),
+      this.formatLevel("warn"),
+      ansis.hex(this.options.colors.warn)(message),
+      ...data
+    );
+  }
+  warnVerbose(message, ...data) {
+    if (!this.options.verbose) return;
+    this.warn(message, ...data);
+  }
+  error(message, error, ...data) {
+    if (!this.shouldLog("error")) return;
+    this.write(
+      "error",
+      this.timestamp(),
+      this.formatPrefix(),
+      this.formatLevel("error"),
+      ansis.hex(this.options.colors.error)(message),
+      ...data
+    );
+    if (error?.stack) {
+      this.write("error", ansis.dim(error.stack));
+    }
+  }
+  errorVerbose(message, error, ...data) {
+    if (!this.options.verbose) return;
+    this.error(message, error, ...data);
+  }
+  // --- Structured Output ---
+  /** @deprecated */
+  table(title, data) {
+    const { colors } = this.options;
+    this.write("log", this.timestamp(), this.formatPrefix(), ansis.bold(title));
+    for (const [key, value] of Object.entries(data)) {
+      const formattedKey = padVisible(ansis.hex(colors.warn)(`  ${key}`), 25);
+      const formattedValue = ansis.hex(colors.muted)(String(value));
+      this.write("log", `${formattedKey} ${formattedValue}`);
+    }
+  }
+  // TODO: Make this prettier, replace it with `header` using the textThroughLine helper
+  /** @deprecated */
+  section(title) {
+    const { colors } = this.options;
+    const titleVisible = stripAnsi(title);
+    const width = Math.max(30, titleVisible.length + 4);
+    const line = "\u2500".repeat(width);
+    const paddedTitle = padVisible(ansis.bold.hex(colors.text)(title), width);
+    this.write("log", ansis.hex(colors.muted)(`
+\u250C\u2500${line}\u2500\u2510`));
+    this.write("log", ansis.hex(colors.muted)("\u2502  ") + paddedTitle + ansis.hex(colors.muted)("  \u2502"));
+    this.write("log", ansis.hex(colors.muted)(`\u2514\u2500${line}\u2500\u2518`));
+  }
+  loader(message, cycleOrOptions, interval = DEFAULT_LOADER_CYCLE_INTERVAL_MS) {
+    const { colors } = this.options;
+    const cycle = typeof cycleOrOptions === "function" ? cycleOrOptions : cycleOrOptions?.cycle;
+    const cycleInterval = typeof cycleOrOptions === "function" ? interval : cycleOrOptions?.interval ?? interval;
+    let stopped = false;
+    const id = this.nextLoaderId++;
+    const prefix = `${this.timestamp()} ${this.formatPrefix()}`;
+    this.activeLoaders.set(id, { cycle, cycleInterval, lastCycleAt: Date.now(), message });
+    if (process.stdout.isTTY !== true) {
+      this.write("log", prefix, message);
+    } else {
+      process.stdout.write(`${prefix} ${SPINNER_FRAMES[0]} ${message}
+`);
+      if (!this.renderInterval) {
+        this.renderInterval = setInterval(() => {
+          const loaderCount = this.activeLoaders.size;
+          if (!loaderCount) return;
+          this.frameIndex = (this.frameIndex + 1) % SPINNER_FRAMES.length;
+          process.stdout.write(`\x1B[${loaderCount}A\x1B[J`);
+          const now = Date.now();
+          const frame = SPINNER_FRAMES[this.frameIndex];
+          for (const [, loader] of this.activeLoaders) {
+            if (loader.cycle && now - loader.lastCycleAt >= loader.cycleInterval) {
+              loader.message = loader.cycle();
+              loader.lastCycleAt = now;
+            }
+            process.stdout.write(`${this.timestamp()} ${this.formatPrefix()} ${frame} ${loader.message}
+`);
+          }
+        }, SPINNER_INTERVAL);
+      }
+    }
+    return (finalMessage, clear = false) => {
+      if (stopped) return;
+      stopped = true;
+      this.activeLoaders.delete(id);
+      if (this.activeLoaders.size === 0 && this.renderInterval) {
+        clearInterval(this.renderInterval);
+        this.renderInterval = null;
+        this.frameIndex = 0;
+      }
+      if (process.stdout.isTTY !== true) {
+        if (clear) {
+          if (finalMessage) this.write("log", finalMessage);
+          return;
+        }
+        this.write(
+          "log",
+          `${this.timestamp()} ${this.formatPrefix()}`,
+          ansis.hex(colors.success)("\u2713"),
+          finalMessage ?? message
+        );
+        return;
+      }
+      process.stdout.write(`\x1B[${this.activeLoaders.size + 1}A\x1B[J`);
+      if (clear) {
+        if (finalMessage) process.stdout.write(`${finalMessage}
+`);
+      } else {
+        const check = ansis.hex(colors.success)("\u2713");
+        process.stdout.write(`${this.timestamp()} ${this.formatPrefix()} ${check} ${finalMessage ?? message}
+`);
+      }
+      const frame = SPINNER_FRAMES[this.frameIndex];
+      for (const [, loader] of this.activeLoaders) {
+        process.stdout.write(`${this.timestamp()} ${this.formatPrefix()} ${frame} ${loader.message}
+`);
+      }
+    };
+  }
+  /** Sets the minimum log level required for level-filtered messages. */
+  setLevel(level) {
+    this.options.minLevel = level;
+  }
+  /** Enables or disables verbose-only log methods. */
+  setVerbose(verbose) {
+    this.options.verbose = verbose;
+  }
+};
+
+// src/utils/obj.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (Array.isArray(value)) return false;
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+function mergeDeep(target, ...sources) {
+  for (const source of sources) {
+    if (!source) continue;
+    for (const key in source) {
+      if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
+      const sourceValue = source[key];
+      const targetValue = target[key];
+      if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+        mergeDeep(targetValue, sourceValue);
+      } else if (sourceValue !== void 0) {
+        target[key] = sourceValue;
+      }
+    }
+  }
+  return target;
+}
+
+// src/utils/process.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+function getPackageJson() {
+  return JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf-8"));
+}
+function getDevMode() {
+  return process.argv.includes("--dev");
+}
+
+// src/utils/str.ts
+import { humanId } from "human-id";
+function createRandomId() {
+  return `v-${Math.random().toString(36).split(".")[1]}`;
+}
+function createHumanId() {
+  return humanId({ separator: "-", capitalize: false });
+}
+export {
+  DEFAULT_COLORS,
+  Logger,
+  VimcordError,
+  createHumanId,
+  createRandomId,
+  forceArray,
+  getDevMode,
+  getPackageJson,
+  getProcessDir,
+  importModulesFromDir,
+  isTSOrJS,
+  mergeDeep,
+  stripAnsi
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vimcord/internal",
+  "version": "0.1.0",
+  "description": "Shared internal types and utilities for the vimcord framework.",
+  "author": "xsqu1znt",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "ansis": "^4.3.0",
+    "human-id": "^4.1.3",
+    "unicode-animations": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check": "tsc --noEmit",
+    "format": "prettier --write \"./**/*.{ts,json}\""
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types/helpers.js";
+export * from "./utils/VimcordError.js";
+export * from "./utils/arr.js";
+export * from "./utils/import.js";
+export * from "./utils/Logger.js";
+export * from "./utils/obj.js";
+export * from "./utils/process.js";
+export * from "./utils/str.js";

package/src/types/helpers.ts

@@ -0,0 +1,18 @@
+/**
+ * Deep partial type utility - recursively makes all properties optional.
+ * Preserves function types to maintain their signatures.
+ */
+export type PartialDeep<T> = T extends (...args: unknown[]) => unknown
+    ? T
+    : T extends object
+      ? T extends ReadonlyArray<infer U>
+          ? ReadonlyArray<PartialDeep<U>>
+          : T extends Array<infer U>
+            ? Array<PartialDeep<U>>
+            : {
+                  [K in keyof T]?: PartialDeep<T[K]>;
+              }
+      : T;
+
+/** A function used for indexing something. */
+export type IndexFn<T> = (module: T) => string | string[] | undefined;