@real-router/route-utils 0.0.1

package/src/segmentTesters.ts

@@ -0,0 +1,253 @@
+// packages/route-utils/src/segmentTesters.ts
+
+import {
+  MAX_SEGMENT_LENGTH,
+  ROUTE_SEGMENT_SEPARATOR,
+  SAFE_SEGMENT_PATTERN,
+} from "./constants";
+
+import type { SegmentTestFunction } from "./types";
+import type { State } from "@real-router/types";
+
+/**
+ * Escapes special RegExp characters in a string.
+ * Handles all RegExp metacharacters including dash in character classes.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for RegExp construction
+ * @internal
+ */
+const escapeRegExp = (str: string): string =>
+  str.replaceAll(/[$()*+.?[\\\]^{|}-]/g, String.raw`\$&`);
+
+/**
+ * Creates a segment tester function with specified start and end patterns.
+ * This is a factory function that produces the actual test functions.
+ *
+ * @param start - RegExp pattern for start (e.g., "^" for startsWith)
+ * @param end - RegExp pattern for end (e.g., "$" or dotOrEnd for specific matching)
+ * @returns A test function that can check if routes match the segment pattern
+ * @internal
+ */
+const makeSegmentTester = (start: string, end: string) => {
+  const regexCache = new Map<string, RegExp>();
+
+  /**
+   * Builds a RegExp for testing segment matches.
+   * Validates length and character pattern. Type and empty checks are done by caller.
+   *
+   * This optimizes performance by avoiding redundant checks - callers verify
+   * type and empty before calling this function.
+   *
+   * @param segment - The segment to build a regex for (non-empty string, pre-validated)
+   * @returns RegExp for testing
+   * @throws {RangeError} If segment exceeds maximum length
+   * @throws {TypeError} If segment contains invalid characters
+   * @internal
+   */
+  const buildRegex = (segment: string): RegExp => {
+    const cached = regexCache.get(segment);
+
+    if (cached) {
+      return cached;
+    }
+
+    // Type and empty checks are SKIPPED - caller already verified these
+
+    // Length check
+    if (segment.length > MAX_SEGMENT_LENGTH) {
+      throw new RangeError(
+        `Segment exceeds maximum length of ${MAX_SEGMENT_LENGTH} characters`,
+      );
+    }
+
+    // Character pattern check
+    if (!SAFE_SEGMENT_PATTERN.test(segment)) {
+      throw new TypeError(
+        `Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)`,
+      );
+    }
+
+    const regex = new RegExp(start + escapeRegExp(segment) + end);
+
+    regexCache.set(segment, regex);
+
+    return regex;
+  };
+
+  // TypeScript cannot infer conditional return type for curried function with union return.
+  // The function returns either boolean or a tester function based on whether segment is provided.
+  // This is an intentional design pattern for API flexibility.
+  // eslint-disable-next-line sonarjs/function-return-type
+  return (route: State | string, segment?: string | null) => {
+    // Extract route name, handling both string and State object inputs
+    // State.name is always string by real-router type definition
+    const name = typeof route === "string" ? route : route.name;
+
+    if (typeof name !== "string") {
+      return false;
+    }
+
+    // Empty route name always returns false
+    if (name.length === 0) {
+      return false;
+    }
+
+    // null always returns false (consistent behavior)
+    if (segment === null) {
+      return false;
+    }
+
+    // Currying: if no segment provided, return a tester function
+    if (segment === undefined) {
+      return (localSegment: string) => {
+        // Type check for runtime safety (consistent with direct call)
+        if (typeof localSegment !== "string") {
+          throw new TypeError(
+            `Segment must be a string, got ${typeof localSegment}`,
+          );
+        }
+
+        // Empty string returns false (consistent with direct call)
+        if (localSegment.length === 0) {
+          return false;
+        }
+
+        // Use buildRegex (type and empty checks already done above)
+        return buildRegex(localSegment).test(name);
+      };
+    }
+
+    if (typeof segment !== "string") {
+      // Runtime protection: TypeScript already narrows to 'string' here,
+      // but we keep this check for defense against unexpected runtime values
+      throw new TypeError(`Segment must be a string, got ${typeof segment}`);
+    }
+
+    // Empty string returns false (consistent behavior)
+    if (segment.length === 0) {
+      return false;
+    }
+
+    // Perform the actual regex test
+    // buildRegex skips type and empty checks (already validated above)
+    return buildRegex(segment).test(name);
+  };
+};
+
+/**
+ * Pattern that matches either a dot separator or end of string.
+ * Used for prefix/suffix matching that respects segment boundaries.
+ */
+const dotOrEnd = `(?:${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)}|$)`;
+
+/**
+ * Tests if a route name starts with the given segment.
+ *
+ * Supports both direct calls and curried form for flexible usage patterns.
+ * All segments are validated for safety (length and character constraints).
+ *
+ * @param route - Route state object or route name string
+ * @param segment - Segment to test. If omitted, returns a tester function.
+ *
+ * @returns
+ * - `boolean` if segment is provided (true if route starts with segment)
+ * - `(segment: string) => boolean` if segment is omitted (curried tester function)
+ * - `false` if segment is null or empty string
+ *
+ * @example
+ * // Direct call
+ * startsWithSegment('users.list', 'users'); // true
+ * startsWithSegment('users.list', 'admin'); // false
+ *
+ * @example
+ * // Curried form
+ * const tester = startsWithSegment('users.list');
+ * tester('users'); // true
+ * tester('admin'); // false
+ *
+ * @example
+ * // With State object
+ * const state: State = { name: 'users.list', params: {}, path: '/users/list' };
+ * startsWithSegment(state, 'users'); // true
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @see endsWithSegment for suffix matching
+ * @see includesSegment for anywhere matching
+ */
+export const startsWithSegment = makeSegmentTester(
+  "^",
+  dotOrEnd,
+) as SegmentTestFunction;
+
+/**
+ * Tests if a route name ends with the given segment.
+ *
+ * Supports both direct calls and curried form for flexible usage patterns.
+ * All segments are validated for safety (length and character constraints).
+ *
+ * @param route - Route state object or route name string
+ * @param segment - Segment to test. If omitted, returns a tester function.
+ *
+ * @returns
+ * - `boolean` if segment is provided (true if route ends with segment)
+ * - `(segment: string) => boolean` if segment is omitted (curried tester function)
+ * - `false` if segment is null or empty string
+ *
+ * @example
+ * // Direct call
+ * endsWithSegment('users.list', 'list'); // true
+ * endsWithSegment('users.profile.edit', 'edit'); // true
+ *
+ * @example
+ * // Curried form
+ * const tester = endsWithSegment('users.list');
+ * tester('list'); // true
+ * tester('users'); // false
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @see startsWithSegment for prefix matching
+ * @see includesSegment for anywhere matching
+ */
+export const endsWithSegment = makeSegmentTester(
+  `(?:^|${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)})`,
+  "$",
+) as SegmentTestFunction;
+
+/**
+ * Tests if a route name includes the given segment anywhere in its path.
+ *
+ * Supports both direct calls and curried form for flexible usage patterns.
+ * All segments are validated for safety (length and character constraints).
+ *
+ * @param route - Route state object or route name string
+ * @param segment - Segment to test. If omitted, returns a tester function.
+ *
+ * @returns
+ * - `boolean` if segment is provided (true if route includes segment)
+ * - `(segment: string) => boolean` if segment is omitted (curried tester function)
+ * - `false` if segment is null or empty string
+ *
+ * @example
+ * // Direct call
+ * includesSegment('users.profile.edit', 'profile'); // true
+ *
+ * @example
+ * // Multi-segment inclusion
+ * includesSegment('a.b.c.d', 'b.c'); // true
+ * includesSegment('a.b.c.d', 'a.c'); // false (must be contiguous)
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @see startsWithSegment for prefix matching
+ * @see endsWithSegment for suffix matching
+ */
+export const includesSegment = makeSegmentTester(
+  `(?:^|${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)})`,
+  dotOrEnd,
+) as SegmentTestFunction;

package/src/types.ts

@@ -0,0 +1,33 @@
+// packages/route-utils/src/types.ts
+
+import type { State } from "@real-router/types";
+
+/**
+ * Minimal interface for route tree nodes used by RouteUtils.
+ * Structurally compatible with `RouteTree` from `route-tree` package.
+ * Defined locally to avoid a runtime dependency on the internal `route-tree` package.
+ */
+export interface RouteTreeNode {
+  /** Pre-computed full name (e.g. `"users.profile"`, `""` for root) */
+  readonly fullName: string;
+
+  /** Child route nodes */
+  readonly children: ReadonlyMap<string, RouteTreeNode>;
+
+  /** Children without absolute paths */
+  readonly nonAbsoluteChildren: readonly RouteTreeNode[];
+}
+
+/**
+ * Type definition for segment test functions.
+ * These functions can be called directly with a segment, or curried for later use.
+ */
+export interface SegmentTestFunction {
+  (route: State | string): (segment: string) => boolean;
+  (route: State | string, segment: string): boolean;
+  (route: State | string, segment: null): false;
+  (
+    route: State | string,
+    segment?: string | null,
+  ): boolean | ((segment: string) => boolean);
+}