@mokup/shared 1.1.0 → 1.1.2

package/dist/route-utils.d.cts

@@ -0,0 +1,42 @@
+interface RouteParserResult<TToken = unknown> {
+    template: string;
+    tokens: TToken[];
+    score: number[];
+    errors: string[];
+    warnings: string[];
+}
+type RouteParser<TToken = unknown> = (template: string) => RouteParserResult<TToken>;
+type RouteScoreComparator = (a: number[], b: number[]) => number;
+interface DerivedRoute<TToken = unknown> {
+    template: string;
+    method: string;
+    tokens: TToken[];
+    score: number[];
+}
+declare function createRouteUtils<TToken = unknown, TRule extends {
+    handler: unknown;
+} = {
+    handler: unknown;
+}>(params: {
+    parseRouteTemplate: RouteParser<TToken>;
+    compareRouteScore: RouteScoreComparator;
+}): {
+    deriveRouteFromFile: (file: string, rootDir: string, warn?: (message: string) => void) => DerivedRoute<TToken> | null;
+    resolveRule: <TOutput = DerivedRoute<TToken>>(input: {
+        rule: TRule;
+        derivedTemplate: string;
+        derivedMethod?: string;
+        prefix: string;
+        file: string;
+        warn?: (message: string) => void;
+        build?: (base: DerivedRoute<TToken>, rule: TRule) => TOutput;
+    }) => TOutput | null;
+    sortRoutes: <TRoute extends {
+        method: string;
+        score: number[];
+        template: string;
+    }>(routes: TRoute[]) => TRoute[];
+};
+
+export { createRouteUtils };
+export type { DerivedRoute, RouteParser, RouteParserResult, RouteScoreComparator };

package/dist/route-utils.d.mts

@@ -0,0 +1,42 @@
+interface RouteParserResult<TToken = unknown> {
+    template: string;
+    tokens: TToken[];
+    score: number[];
+    errors: string[];
+    warnings: string[];
+}
+type RouteParser<TToken = unknown> = (template: string) => RouteParserResult<TToken>;
+type RouteScoreComparator = (a: number[], b: number[]) => number;
+interface DerivedRoute<TToken = unknown> {
+    template: string;
+    method: string;
+    tokens: TToken[];
+    score: number[];
+}
+declare function createRouteUtils<TToken = unknown, TRule extends {
+    handler: unknown;
+} = {
+    handler: unknown;
+}>(params: {
+    parseRouteTemplate: RouteParser<TToken>;
+    compareRouteScore: RouteScoreComparator;
+}): {
+    deriveRouteFromFile: (file: string, rootDir: string, warn?: (message: string) => void) => DerivedRoute<TToken> | null;
+    resolveRule: <TOutput = DerivedRoute<TToken>>(input: {
+        rule: TRule;
+        derivedTemplate: string;
+        derivedMethod?: string;
+        prefix: string;
+        file: string;
+        warn?: (message: string) => void;
+        build?: (base: DerivedRoute<TToken>, rule: TRule) => TOutput;
+    }) => TOutput | null;
+    sortRoutes: <TRoute extends {
+        method: string;
+        score: number[];
+        template: string;
+    }>(routes: TRoute[]) => TRoute[];
+};
+
+export { createRouteUtils };
+export type { DerivedRoute, RouteParser, RouteParserResult, RouteScoreComparator };

package/dist/route-utils.d.ts

@@ -0,0 +1,42 @@
+interface RouteParserResult<TToken = unknown> {
+    template: string;
+    tokens: TToken[];
+    score: number[];
+    errors: string[];
+    warnings: string[];
+}
+type RouteParser<TToken = unknown> = (template: string) => RouteParserResult<TToken>;
+type RouteScoreComparator = (a: number[], b: number[]) => number;
+interface DerivedRoute<TToken = unknown> {
+    template: string;
+    method: string;
+    tokens: TToken[];
+    score: number[];
+}
+declare function createRouteUtils<TToken = unknown, TRule extends {
+    handler: unknown;
+} = {
+    handler: unknown;
+}>(params: {
+    parseRouteTemplate: RouteParser<TToken>;
+    compareRouteScore: RouteScoreComparator;
+}): {
+    deriveRouteFromFile: (file: string, rootDir: string, warn?: (message: string) => void) => DerivedRoute<TToken> | null;
+    resolveRule: <TOutput = DerivedRoute<TToken>>(input: {
+        rule: TRule;
+        derivedTemplate: string;
+        derivedMethod?: string;
+        prefix: string;
+        file: string;
+        warn?: (message: string) => void;
+        build?: (base: DerivedRoute<TToken>, rule: TRule) => TOutput;
+    }) => TOutput | null;
+    sortRoutes: <TRoute extends {
+        method: string;
+        score: number[];
+        template: string;
+    }>(routes: TRoute[]) => TRoute[];
+};
+
+export { createRouteUtils };
+export type { DerivedRoute, RouteParser, RouteParserResult, RouteScoreComparator };

package/dist/route-utils.mjs

@@ -0,0 +1,124 @@
+import { toPosix } from './path-utils.mjs';
+import { relative, extname, dirname, basename, join } from 'pathe';
+import { jsonExtensions, methodSuffixSet } from './route-constants.mjs';
+import { normalizePrefix } from './scan-utils.mjs';
+import 'node:process';
+
+function createRouteUtils(params) {
+  const { parseRouteTemplate, compareRouteScore } = params;
+  function resolveTemplate(template, prefix) {
+    const normalized = template.startsWith("/") ? template : `/${template}`;
+    if (!prefix) {
+      return normalized;
+    }
+    const normalizedPrefix = normalizePrefix(prefix);
+    if (!normalizedPrefix) {
+      return normalized;
+    }
+    if (normalized === normalizedPrefix || normalized.startsWith(`${normalizedPrefix}/`)) {
+      return normalized;
+    }
+    if (normalized === "/") {
+      return `${normalizedPrefix}/`;
+    }
+    return `${normalizedPrefix}${normalized}`;
+  }
+  function stripMethodSuffix(base) {
+    const segments = base.split(".");
+    const last = segments.at(-1);
+    if (last && methodSuffixSet.has(last.toLowerCase())) {
+      segments.pop();
+      return {
+        name: segments.join("."),
+        method: last.toUpperCase()
+      };
+    }
+    return {
+      name: base,
+      method: void 0
+    };
+  }
+  function deriveRouteFromFile(file, rootDir, warn) {
+    const rel = toPosix(relative(rootDir, file));
+    const ext = extname(rel);
+    const withoutExt = rel.slice(0, rel.length - ext.length);
+    const dir = dirname(withoutExt);
+    const base = basename(withoutExt);
+    const { name, method } = stripMethodSuffix(base);
+    const resolvedMethod = method ?? (jsonExtensions.has(ext) ? "GET" : void 0);
+    if (!resolvedMethod) {
+      warn?.(`Skip mock without method suffix: ${file}`);
+      return null;
+    }
+    if (!name) {
+      warn?.(`Skip mock with empty route name: ${file}`);
+      return null;
+    }
+    const joined = dir === "." ? name : join(dir, name);
+    const segments = toPosix(joined).split("/");
+    if (segments.at(-1) === "index") {
+      segments.pop();
+    }
+    const template = segments.length === 0 ? "/" : `/${segments.join("/")}`;
+    const parsed = parseRouteTemplate(template);
+    if (parsed.errors.length > 0) {
+      for (const error of parsed.errors) {
+        warn?.(`${error} in ${file}`);
+      }
+      return null;
+    }
+    for (const warning of parsed.warnings) {
+      warn?.(`${warning} in ${file}`);
+    }
+    return {
+      template: parsed.template,
+      method: resolvedMethod,
+      tokens: parsed.tokens,
+      score: parsed.score
+    };
+  }
+  function resolveRule(input) {
+    const method = input.derivedMethod;
+    if (!method) {
+      input.warn?.(`Skip mock without method suffix: ${input.file}`);
+      return null;
+    }
+    const template = resolveTemplate(input.derivedTemplate, input.prefix);
+    const parsed = parseRouteTemplate(template);
+    if (parsed.errors.length > 0) {
+      for (const error of parsed.errors) {
+        input.warn?.(`${error} in ${input.file}`);
+      }
+      return null;
+    }
+    for (const warning of parsed.warnings) {
+      input.warn?.(`${warning} in ${input.file}`);
+    }
+    const base = {
+      template: parsed.template,
+      method,
+      tokens: parsed.tokens,
+      score: parsed.score
+    };
+    return input.build ? input.build(base, input.rule) : base;
+  }
+  function sortRoutes(routes) {
+    return routes.sort((a, b) => {
+      if (a.method !== b.method) {
+        return a.method.localeCompare(b.method);
+      }
+      const scoreCompare = compareRouteScore(a.score, b.score);
+      if (scoreCompare !== 0) {
+        return scoreCompare;
+      }
+      return a.template.localeCompare(b.template);
+    });
+  }
+  return {
+    deriveRouteFromFile,
+    resolveRule,
+    sortRoutes
+  };
+}
+
+export { createRouteUtils };

package/dist/scan-utils.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+const pathe = require('pathe');
+const routeConstants = require('./route-constants.cjs');
+
+function normalizeMethod(method) {
+  if (!method) {
+    return void 0;
+  }
+  const normalized = method.toUpperCase();
+  if (routeConstants.methodSet.has(normalized)) {
+    return normalized;
+  }
+  return void 0;
+}
+function normalizePrefix(prefix) {
+  if (!prefix) {
+    return "";
+  }
+  const normalized = prefix.startsWith("/") ? prefix : `/${prefix}`;
+  return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+}
+function resolveDirs(dir, root) {
+  const raw = typeof dir === "function" ? dir(root) : dir;
+  const resolved = Array.isArray(raw) ? raw : raw ? [raw] : ["mock"];
+  const normalized = resolved.map(
+    (entry) => pathe.isAbsolute(entry) ? entry : pathe.resolve(root, entry)
+  );
+  return Array.from(new Set(normalized));
+}
+function normalizeIgnorePrefix(value, fallback = ["."]) {
+  const list = typeof value === "undefined" ? fallback : Array.isArray(value) ? value : [value];
+  return list.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+
+exports.normalizeIgnorePrefix = normalizeIgnorePrefix;
+exports.normalizeMethod = normalizeMethod;
+exports.normalizePrefix = normalizePrefix;
+exports.resolveDirs = resolveDirs;

package/dist/scan-utils.d.cts

@@ -0,0 +1,114 @@
+import './config-core.cjs';
+import './config-utils.cjs';
+import './define-config.cjs';
+import './jsonc-utils.cjs';
+import './load-rules.cjs';
+import './mock-files.cjs';
+import './module-loader.cjs';
+import './route-constants.cjs';
+import './route-utils.cjs';
+
+declare function normalizeMethod(method?: string | null): string | undefined;
+declare function normalizePrefix(prefix: string): string;
+declare function resolveDirs(dir: DirInput, root: string): string[];
+declare function normalizeIgnorePrefix(value: string | string[] | undefined, fallback?: string[]): string[];
+
+/**
+ * Directory input for mock scanning.
+ *
+ * @example
+ * import type { DirInput } from '@mokup/shared'
+ *
+ * const dir: DirInput = ['mock', 'fixtures']
+ */
+type DirInput = string | string[] | ((root: string) => string | string[]) | undefined;
+/**
+ * Shared entry options for mokup scanners and plugins.
+ *
+ * @example
+ * import type { MockEntryOptions } from '@mokup/shared'
+ *
+ * const entry: MockEntryOptions = {
+ *   dir: 'mock',
+ *   prefix: '/api',
+ *   watch: true,
+ * }
+ */
+interface MockEntryOptions {
+    /**
+     * Directory (or directories) to scan for mock routes.
+     *
+     * @default "mock" (resolved by Vite/webpack plugins)
+     */
+    dir?: DirInput;
+    /**
+     * Request path prefix to mount mock routes under.
+     *
+     * @default ""
+     */
+    prefix?: string;
+    /**
+     * Include filter for files to scan.
+     *
+     * @default undefined
+     */
+    include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files to scan.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+    /**
+     * Ignore file or folder prefixes when scanning.
+     *
+     * @default ["."]
+     */
+    ignorePrefix?: string | string[];
+    /**
+     * Enable file watching for live route updates.
+     *
+     * @default true
+     */
+    watch?: boolean;
+    /**
+     * Enable mokup logging.
+     *
+     * @default true
+     */
+    log?: boolean;
+}
+/**
+ * Playground configuration input.
+ *
+ * @example
+ * import type { PlaygroundOptionsInput } from '@mokup/shared'
+ *
+ * const playground: PlaygroundOptionsInput = {
+ *   path: '/__mokup',
+ *   enabled: true,
+ * }
+ */
+type PlaygroundOptionsInput = boolean | {
+    /**
+     * Base path for the playground UI.
+     *
+     * @default "/__mokup"
+     */
+    path?: string;
+    /**
+     * Emit playground assets during production builds.
+     *
+     * @default false
+     */
+    build?: boolean;
+    /**
+     * Enable or disable the playground routes.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+} | undefined;
+
+export { normalizeIgnorePrefix, normalizeMethod, normalizePrefix, resolveDirs };
+export type { DirInput as D, MockEntryOptions as M, PlaygroundOptionsInput as P };

package/dist/scan-utils.d.mts

@@ -0,0 +1,114 @@
+import './config-core.mjs';
+import './config-utils.mjs';
+import './define-config.mjs';
+import './jsonc-utils.mjs';
+import './load-rules.mjs';
+import './mock-files.mjs';
+import './module-loader.mjs';
+import './route-constants.mjs';
+import './route-utils.mjs';
+
+declare function normalizeMethod(method?: string | null): string | undefined;
+declare function normalizePrefix(prefix: string): string;
+declare function resolveDirs(dir: DirInput, root: string): string[];
+declare function normalizeIgnorePrefix(value: string | string[] | undefined, fallback?: string[]): string[];
+
+/**
+ * Directory input for mock scanning.
+ *
+ * @example
+ * import type { DirInput } from '@mokup/shared'
+ *
+ * const dir: DirInput = ['mock', 'fixtures']
+ */
+type DirInput = string | string[] | ((root: string) => string | string[]) | undefined;
+/**
+ * Shared entry options for mokup scanners and plugins.
+ *
+ * @example
+ * import type { MockEntryOptions } from '@mokup/shared'
+ *
+ * const entry: MockEntryOptions = {
+ *   dir: 'mock',
+ *   prefix: '/api',
+ *   watch: true,
+ * }
+ */
+interface MockEntryOptions {
+    /**
+     * Directory (or directories) to scan for mock routes.
+     *
+     * @default "mock" (resolved by Vite/webpack plugins)
+     */
+    dir?: DirInput;
+    /**
+     * Request path prefix to mount mock routes under.
+     *
+     * @default ""
+     */
+    prefix?: string;
+    /**
+     * Include filter for files to scan.
+     *
+     * @default undefined
+     */
+    include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files to scan.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+    /**
+     * Ignore file or folder prefixes when scanning.
+     *
+     * @default ["."]
+     */
+    ignorePrefix?: string | string[];
+    /**
+     * Enable file watching for live route updates.
+     *
+     * @default true
+     */
+    watch?: boolean;
+    /**
+     * Enable mokup logging.
+     *
+     * @default true
+     */
+    log?: boolean;
+}
+/**
+ * Playground configuration input.
+ *
+ * @example
+ * import type { PlaygroundOptionsInput } from '@mokup/shared'
+ *
+ * const playground: PlaygroundOptionsInput = {
+ *   path: '/__mokup',
+ *   enabled: true,
+ * }
+ */
+type PlaygroundOptionsInput = boolean | {
+    /**
+     * Base path for the playground UI.
+     *
+     * @default "/__mokup"
+     */
+    path?: string;
+    /**
+     * Emit playground assets during production builds.
+     *
+     * @default false
+     */
+    build?: boolean;
+    /**
+     * Enable or disable the playground routes.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+} | undefined;
+
+export { normalizeIgnorePrefix, normalizeMethod, normalizePrefix, resolveDirs };
+export type { DirInput as D, MockEntryOptions as M, PlaygroundOptionsInput as P };

package/dist/scan-utils.d.ts

@@ -0,0 +1,114 @@
+import './config-core.js';
+import './config-utils.js';
+import './define-config.js';
+import './jsonc-utils.js';
+import './load-rules.js';
+import './mock-files.js';
+import './module-loader.js';
+import './route-constants.js';
+import './route-utils.js';
+
+declare function normalizeMethod(method?: string | null): string | undefined;
+declare function normalizePrefix(prefix: string): string;
+declare function resolveDirs(dir: DirInput, root: string): string[];
+declare function normalizeIgnorePrefix(value: string | string[] | undefined, fallback?: string[]): string[];
+
+/**
+ * Directory input for mock scanning.
+ *
+ * @example
+ * import type { DirInput } from '@mokup/shared'
+ *
+ * const dir: DirInput = ['mock', 'fixtures']
+ */
+type DirInput = string | string[] | ((root: string) => string | string[]) | undefined;
+/**
+ * Shared entry options for mokup scanners and plugins.
+ *
+ * @example
+ * import type { MockEntryOptions } from '@mokup/shared'
+ *
+ * const entry: MockEntryOptions = {
+ *   dir: 'mock',
+ *   prefix: '/api',
+ *   watch: true,
+ * }
+ */
+interface MockEntryOptions {
+    /**
+     * Directory (or directories) to scan for mock routes.
+     *
+     * @default "mock" (resolved by Vite/webpack plugins)
+     */
+    dir?: DirInput;
+    /**
+     * Request path prefix to mount mock routes under.
+     *
+     * @default ""
+     */
+    prefix?: string;
+    /**
+     * Include filter for files to scan.
+     *
+     * @default undefined
+     */
+    include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files to scan.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+    /**
+     * Ignore file or folder prefixes when scanning.
+     *
+     * @default ["."]
+     */
+    ignorePrefix?: string | string[];
+    /**
+     * Enable file watching for live route updates.
+     *
+     * @default true
+     */
+    watch?: boolean;
+    /**
+     * Enable mokup logging.
+     *
+     * @default true
+     */
+    log?: boolean;
+}
+/**
+ * Playground configuration input.
+ *
+ * @example
+ * import type { PlaygroundOptionsInput } from '@mokup/shared'
+ *
+ * const playground: PlaygroundOptionsInput = {
+ *   path: '/__mokup',
+ *   enabled: true,
+ * }
+ */
+type PlaygroundOptionsInput = boolean | {
+    /**
+     * Base path for the playground UI.
+     *
+     * @default "/__mokup"
+     */
+    path?: string;
+    /**
+     * Emit playground assets during production builds.
+     *
+     * @default false
+     */
+    build?: boolean;
+    /**
+     * Enable or disable the playground routes.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+} | undefined;
+
+export { normalizeIgnorePrefix, normalizeMethod, normalizePrefix, resolveDirs };
+export type { DirInput as D, MockEntryOptions as M, PlaygroundOptionsInput as P };

package/dist/scan-utils.mjs

@@ -0,0 +1,34 @@
+import { resolve, isAbsolute } from 'pathe';
+import { methodSet } from './route-constants.mjs';
+
+function normalizeMethod(method) {
+  if (!method) {
+    return void 0;
+  }
+  const normalized = method.toUpperCase();
+  if (methodSet.has(normalized)) {
+    return normalized;
+  }
+  return void 0;
+}
+function normalizePrefix(prefix) {
+  if (!prefix) {
+    return "";
+  }
+  const normalized = prefix.startsWith("/") ? prefix : `/${prefix}`;
+  return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+}
+function resolveDirs(dir, root) {
+  const raw = typeof dir === "function" ? dir(root) : dir;
+  const resolved = Array.isArray(raw) ? raw : raw ? [raw] : ["mock"];
+  const normalized = resolved.map(
+    (entry) => isAbsolute(entry) ? entry : resolve(root, entry)
+  );
+  return Array.from(new Set(normalized));
+}
+function normalizeIgnorePrefix(value, fallback = ["."]) {
+  const list = typeof value === "undefined" ? fallback : Array.isArray(value) ? value : [value];
+  return list.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+
+export { normalizeIgnorePrefix, normalizeMethod, normalizePrefix, resolveDirs };

package/dist/timing.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+function createDebouncer(delayMs, fn) {
+  let timer = null;
+  return () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      fn();
+    }, delayMs);
+  };
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+exports.createDebouncer = createDebouncer;
+exports.delay = delay;

package/dist/timing.d.cts

@@ -0,0 +1,4 @@
+declare function createDebouncer(delayMs: number, fn: () => void): () => void;
+declare function delay(ms: number): Promise<void>;
+
+export { createDebouncer, delay };

package/dist/timing.d.mts

@@ -0,0 +1,4 @@
+declare function createDebouncer(delayMs: number, fn: () => void): () => void;
+declare function delay(ms: number): Promise<void>;
+
+export { createDebouncer, delay };