@real-router/helpers 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Oleg Ivanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,575 @@
+# @real-router/helpers
+
+[![npm version](https://badge.fury.io/js/@real-router%2Fhelpers.svg)](https://www.npmjs.com/package/@real-router/helpers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+
+> High-performance route segment testing utilities for Real-Router
+
+## Overview
+
+`@real-router/helpers` provides efficient utilities for testing route name segments in Real-Router applications. These helpers are essential for:
+
+- Conditional rendering based on route hierarchy
+- Active navigation menu items
+- Breadcrumb construction
+- Route-based access guards
+- UI component visibility logic
+
+## Installation
+
+```bash
+npm install @real-router/helpers
+# or
+pnpm add @real-router/helpers
+# or
+yarn add @real-router/helpers
+# or
+bun add @real-router/helpers
+```
+
+## Quick Start
+
+```typescript
+import {
+  startsWithSegment,
+  endsWithSegment,
+  includesSegment,
+  areRoutesRelated,
+} from "@real-router/helpers";
+
+// Check if route starts with segment
+startsWithSegment("users.profile.edit", "users"); // true
+startsWithSegment("admin.dashboard", "users"); // false
+
+// Check if route ends with segment
+endsWithSegment("users.profile.edit", "edit"); // true
+endsWithSegment("users.profile.edit", "view"); // false
+
+// Check if route includes segment anywhere
+includesSegment("users.profile.edit", "profile"); // true
+includesSegment("users.profile.edit", "admin"); // false
+
+// Check if routes are related (parent-child or same)
+areRoutesRelated("users", "users.list"); // true
+areRoutesRelated("users", "admin"); // false
+```
+
+## API Reference
+
+### `startsWithSegment(route, segment?)`
+
+Tests if a route name starts with the given segment.
+
+**Parameters:**
+
+- `route: State | string` - Route state object or route name string
+- `segment?: string | null` - Segment to test (optional for curried form)
+
+**Returns:**
+
+- `boolean` - True if route starts with segment
+- `(segment: string) => boolean` - Tester function if segment omitted
+- `false` - If segment is null or empty string
+
+**Examples:**
+
+```typescript
+// Direct usage
+startsWithSegment("users.list", "users"); // true
+startsWithSegment("users.list", "admin"); // false
+
+// Multi-segment matching
+startsWithSegment("users.profile.edit", "users.profile"); // true
+
+// With State object
+const state = { name: "users.list", params: {}, path: "/users" };
+startsWithSegment(state, "users"); // true
+
+// Curried form
+const tester = startsWithSegment("users.profile.edit");
+tester("users"); // true
+tester("admin"); // false
+
+// Edge cases
+startsWithSegment("users", ""); // false
+startsWithSegment("users", null); // false
+```
+
+**Use Cases:**
+
+```typescript
+// Active navigation menu
+const isAdminSection = startsWithSegment(currentRoute, 'admin');
+
+// Conditional rendering
+{startsWithSegment(route, 'users') && <UsersToolbar />}
+
+// Access guards
+if (!startsWithSegment(route, 'admin')) {
+  throw new UnauthorizedError();
+}
+```
+
+---
+
+### `endsWithSegment(route, segment?)`
+
+Tests if a route name ends with the given segment.
+
+**Parameters:**
+
+- `route: State | string` - Route state object or route name string
+- `segment?: string | null` - Segment to test (optional for curried form)
+
+**Returns:**
+
+- `boolean` - True if route ends with segment
+- `(segment: string) => boolean` - Tester function if segment omitted
+- `false` - If segment is null or empty string
+
+**Examples:**
+
+```typescript
+// Direct usage
+endsWithSegment("users.profile.edit", "edit"); // true
+endsWithSegment("users.profile.edit", "view"); // false
+
+// Multi-segment matching
+endsWithSegment("a.b.c.d", "c.d"); // true
+
+// Curried form
+const tester = endsWithSegment("users.list");
+tester("list"); // true
+tester("edit"); // false
+```
+
+**Use Cases:**
+
+```typescript
+// Detect edit pages
+const isEditPage = endsWithSegment(route, 'edit');
+
+// Page type detection
+const pageType = ['view', 'edit', 'create'].find(
+  type => endsWithSegment(route, type)
+);
+
+// Conditional toolbar
+{endsWithSegment(route, 'edit') && <EditToolbar />}
+```
+
+---
+
+### `includesSegment(route, segment?)`
+
+Tests if a route name includes the given segment anywhere in its path.
+
+**Parameters:**
+
+- `route: State | string` - Route state object or route name string
+- `segment?: string | null` - Segment to test (optional for curried form)
+
+**Returns:**
+
+- `boolean` - True if route includes segment
+- `(segment: string) => boolean` - Tester function if segment omitted
+- `false` - If segment is null or empty string
+
+**Examples:**
+
+```typescript
+// Direct usage
+includesSegment("admin.users.profile", "users"); // true
+includesSegment("admin.users.profile", "profile"); // true
+includesSegment("admin.users.profile", "settings"); // false
+
+// Multi-segment matching (contiguous)
+includesSegment("a.b.c.d", "b.c"); // true
+includesSegment("a.b.c.d", "a.c"); // false (not contiguous)
+
+// Curried form
+const tester = includesSegment("admin.users.profile");
+tester("users"); // true
+tester("settings"); // false
+```
+
+**Use Cases:**
+
+```typescript
+// Check if anywhere in users section
+const inUsersSection = includesSegment(route, "users");
+
+// Feature detection
+const hasProfileFeature = includesSegment(route, "profile");
+
+// Analytics tracking
+if (includesSegment(route, "checkout")) {
+  analytics.track("checkout_flow");
+}
+```
+
+---
+
+### `areRoutesRelated(route1, route2)`
+
+Tests if two routes are related in the hierarchy (same, parent-child, or child-parent).
+
+**Parameters:**
+
+- `route1: string` - First route name
+- `route2: string` - Second route name
+
+**Returns:**
+
+- `boolean` - True if routes are related
+
+**Examples:**
+
+```typescript
+// Same route
+areRoutesRelated("users", "users"); // true
+
+// Parent-child relationship
+areRoutesRelated("users", "users.list"); // true
+areRoutesRelated("users", "users.profile.edit"); // true
+
+// Child-parent relationship
+areRoutesRelated("users.list", "users"); // true
+areRoutesRelated("users.profile.edit", "users"); // true
+
+// Different branches (not related)
+areRoutesRelated("users", "admin"); // false
+areRoutesRelated("users.list", "admin.dashboard"); // false
+
+// Siblings (not related)
+areRoutesRelated("users.list", "users.view"); // false
+areRoutesRelated("users.profile", "users.settings"); // false
+```
+
+**Use Cases:**
+
+```typescript
+// Optimized re-rendering (only update when route is related)
+const shouldUpdate = areRoutesRelated(newRoute, watchedRoute);
+
+// Navigation menu highlighting
+const isInSection = areRoutesRelated(currentRoute, "admin");
+
+// Breadcrumb visibility
+const showBreadcrumb = areRoutesRelated(currentRoute, basePath);
+```
+
+---
+
+## Real-World Examples
+
+### Active Navigation Menu
+
+```typescript
+import { startsWithSegment } from '@real-router/helpers';
+
+function NavigationMenu({ currentRoute }) {
+  const menuItems = [
+    { name: 'Dashboard', route: 'dashboard' },
+    { name: 'Users', route: 'users' },
+    { name: 'Settings', route: 'settings' },
+  ];
+
+  return (
+    <nav>
+      {menuItems.map(item => (
+        <MenuItem
+          key={item.route}
+          active={startsWithSegment(currentRoute, item.route)}
+        >
+          {item.name}
+        </MenuItem>
+      ))}
+    </nav>
+  );
+}
+```
+
+### Breadcrumbs
+
+```typescript
+import { startsWithSegment } from '@real-router/helpers';
+
+function Breadcrumbs({ currentRoute }) {
+  const segments = currentRoute.split('.');
+  const breadcrumbs = segments.reduce((acc, segment, index) => {
+    const path = segments.slice(0, index + 1).join('.');
+    return [...acc, {
+      path,
+      label: segment,
+      isActive: path === currentRoute,
+    }];
+  }, []);
+
+  return (
+    <nav>
+      {breadcrumbs.map(crumb => (
+        <Breadcrumb
+          key={crumb.path}
+          active={crumb.isActive}
+        >
+          {crumb.label}
+        </Breadcrumb>
+      ))}
+    </nav>
+  );
+}
+```
+
+### Route Guards
+
+```typescript
+import { startsWithSegment } from "@real-router/helpers";
+
+const adminGuard = (router) => (toState, fromState, done) => {
+  if (startsWithSegment(toState, "admin") && !userHasAdminRole()) {
+    done({ redirect: { name: "unauthorized" } });
+  } else {
+    done();
+  }
+};
+
+router.useMiddleware(adminGuard);
+```
+
+### Conditional Rendering
+
+```typescript
+import { startsWithSegment, includesSegment, endsWithSegment } from '@real-router/helpers';
+
+function PageLayout({ route, children }) {
+  return (
+    <div>
+      {/* Show admin sidebar only in admin section */}
+      {startsWithSegment(route, 'admin') && <AdminSidebar />}
+
+      {/* Show edit toolbar on edit pages */}
+      {endsWithSegment(route, 'edit') && <EditToolbar />}
+
+      {/* Show user profile widget in user-related pages */}
+      {includesSegment(route, 'users') && <UserProfileWidget />}
+
+      <main>{children}</main>
+    </div>
+  );
+}
+```
+
+### Analytics Tracking
+
+```typescript
+import { startsWithSegment, includesSegment } from "@real-router/helpers";
+
+router.subscribe((state) => {
+  const routeName = state.route.name;
+
+  // Track section
+  if (startsWithSegment(routeName, "admin")) {
+    analytics.track("admin_section_view");
+  }
+
+  // Track feature usage
+  if (includesSegment(routeName, "checkout")) {
+    analytics.track("checkout_flow_step", {
+      step: routeName.split(".").pop(),
+    });
+  }
+});
+```
+
+---
+
+## Validation & Security
+
+### Automatic Validation
+
+All segment inputs are automatically validated for security and correctness:
+
+**Character Whitelist:**
+
+- Allowed: `a-z`, `A-Z`, `0-9`, `.` (dot), `-` (dash), `_` (underscore)
+- Disallowed: Special characters, spaces, slashes, etc.
+
+**Length Limits:**
+
+- Maximum segment length: 10,000 characters
+- Empty segments are rejected
+
+**Examples:**
+
+```typescript
+// Valid segments
+startsWithSegment("route", "users"); // OK
+startsWithSegment("route", "admin-panel"); // OK
+startsWithSegment("route", "users_v2"); // OK
+startsWithSegment("route", "app.settings"); // OK
+
+// Invalid segments (throw TypeError)
+startsWithSegment("route", "invalid!char"); // Throws
+startsWithSegment("route", "has space"); // Throws
+startsWithSegment("route", "path/segment"); // Throws
+startsWithSegment("route", "ns:segment"); // Throws
+
+// Too long (throw RangeError)
+startsWithSegment("route", "a".repeat(10001)); // Throws
+
+// Empty (returns false)
+startsWithSegment("route", ""); // false
+startsWithSegment("route", null); // false
+```
+
+### Error Handling
+
+```typescript
+try {
+  startsWithSegment("route", "invalid!segment");
+} catch (error) {
+  if (error instanceof TypeError) {
+    console.error("Invalid segment:", error.message);
+    // "Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)"
+  }
+}
+
+try {
+  startsWithSegment("route", "a".repeat(10001));
+} catch (error) {
+  if (error instanceof RangeError) {
+    console.error("Segment too long:", error.message);
+    // "Segment exceeds maximum length of 10000 characters"
+  }
+}
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included.
+
+```typescript
+import type { State } from "@real-router/core";
+import { startsWithSegment } from "@real-router/helpers";
+
+// Type inference works correctly
+const result: boolean = startsWithSegment("route", "segment");
+
+// Curried form also typed
+const tester: (segment: string) => boolean = startsWithSegment("route");
+
+// Works with State objects
+const state: State = { name: "route", params: {}, path: "/route" };
+const matches: boolean = startsWithSegment(state, "segment");
+```
+
+### Type Definitions
+
+```typescript
+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);
+}
+```
+
+---
+
+## Documentation
+
+Full documentation available on the [Real-Router Wiki](https://github.com/greydragon888/real-router/wiki):
+
+- [startsWithSegment](https://github.com/greydragon888/real-router/wiki/startsWithSegment)
+- [endsWithSegment](https://github.com/greydragon888/real-router/wiki/endsWithSegment)
+- [includesSegment](https://github.com/greydragon888/real-router/wiki/includesSegment)
+- [areRoutesRelated](https://github.com/greydragon888/real-router/wiki/areRoutesRelated)
+
+---
+
+## Related Packages
+
+- [@real-router/core](https://www.npmjs.com/package/@real-router/core) - Core router
+- [@real-router/react](https://www.npmjs.com/package/@real-router/react) - React integration
+- [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) - Browser integration
+
+---
+
+## Migration from router5-helpers
+
+### Import Changes
+
+```diff
+- import { startsWithSegment, endsWithSegment, includesSegment } from 'router5-helpers';
++ import { startsWithSegment, endsWithSegment, includesSegment } from '@real-router/helpers';
+```
+
+### Removed: `redirect`
+
+The `redirect` helper has been removed. Use router guards instead:
+
+```diff
+- import { redirect } from 'router5-helpers';
+-
+- router.canActivate('protected', () => redirect('login'));
++ router.canActivate('protected', (toState, fromState, done) => {
++   done({ redirect: { name: 'login' } });
++ });
+```
+
+### New: `areRoutesRelated`
+
+New helper function for checking route hierarchy:
+
+```typescript
+import { areRoutesRelated } from "@real-router/helpers";
+
+areRoutesRelated("users", "users.profile"); // true (parent-child)
+areRoutesRelated("users.profile", "users"); // true (child-parent)
+areRoutesRelated("users", "admin"); // false (different branches)
+```
+
+### New: Input Validation
+
+@real-router/helpers validates segment inputs for security:
+
+```typescript
+// Valid segments
+startsWithSegment("route", "users");
+startsWithSegment("route", "admin-panel");
+
+// Throws TypeError (invalid characters)
+startsWithSegment("route", "invalid!char");
+startsWithSegment("route", "has space");
+```
+
+### Full Migration Example
+
+```diff
+- import { startsWithSegment, redirect } from 'router5-helpers';
++ import { startsWithSegment } from '@real-router/helpers';
+
+  // Segment testing - unchanged
+  if (startsWithSegment(route, 'admin')) {
+    // ...
+  }
+
+  // Redirects - use guards instead
+- router.canActivate('old-page', () => redirect('new-page'));
++ router.canActivate('old-page', (toState, fromState, done) => {
++   done({ redirect: { name: 'new-page' } });
++ });
+```
+
+---
+
+## License
+
+MIT © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -0,0 +1,182 @@
+import { State } from '@real-router/core';
+
+/**
+ * Type definition for segment test functions.
+ * These functions can be called directly with a segment, or curried for later use.
+ */
+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);
+}
+
+/**
+ * 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
+ * startsWithSegment('admin.panel', 'users'); // false
+ *
+ * @example
+ * // Curried form
+ * const tester = startsWithSegment('users.list');
+ * tester('users'); // true
+ * tester('users.list'); // true
+ * tester('admin'); // false
+ *
+ * @example
+ * // With State object
+ * const state: State = { name: 'users.list', params: {}, path: '/users/list' };
+ * startsWithSegment(state, 'users'); // true
+ *
+ * @example
+ * // Edge cases
+ * startsWithSegment('users', ''); // false
+ * startsWithSegment('users', null); // false
+ * startsWithSegment('', 'users'); // false
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @remarks
+ * **Validation rules:**
+ * - Allowed characters: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)
+ * - Maximum segment length: 10,000 characters
+ * - Empty segments are rejected
+ *
+ * **Performance:**
+ * - No caching (RegExp compiled on each call)
+ * - For high-frequency checks, consider caching results at application level
+ *
+ * **Segment boundaries:**
+ * - Respects dot-separated segments
+ * - 'users' matches 'users' and 'users.list'
+ * - 'users' does NOT match 'users2' or 'admin.users'
+ *
+ * @see endsWithSegment for suffix matching
+ * @see includesSegment for anywhere matching
+ */
+declare const startsWithSegment: 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
+ * endsWithSegment('users.list', 'users'); // false
+ *
+ * @example
+ * // Multi-segment suffix
+ * endsWithSegment('a.b.c.d', 'c.d'); // true
+ * endsWithSegment('a.b.c.d', 'b.c'); // false
+ *
+ * @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)
+ *
+ * @remarks
+ * See {@link startsWithSegment} for detailed validation rules and performance notes.
+ *
+ * @see startsWithSegment for prefix matching
+ * @see includesSegment for anywhere matching
+ */
+declare const endsWithSegment: 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
+ * includesSegment('users.profile.edit', 'users'); // true
+ * includesSegment('users.profile.edit', 'edit'); // true
+ * includesSegment('users.profile.edit', 'admin'); // false
+ *
+ * @example
+ * // Multi-segment inclusion
+ * includesSegment('a.b.c.d', 'b.c'); // true
+ * includesSegment('a.b.c.d', 'a.c'); // false (must be contiguous)
+ *
+ * @example
+ * // Curried form
+ * const tester = includesSegment('users.profile.edit');
+ * tester('profile'); // true
+ * tester('admin'); // false
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @remarks
+ * **Important:** Segment must be contiguous in the route path.
+ * - 'a.b.c' includes 'a.b' and 'b.c' but NOT 'a.c'
+ *
+ * See {@link startsWithSegment} for detailed validation rules and performance notes.
+ *
+ * @see startsWithSegment for prefix matching
+ * @see endsWithSegment for suffix matching
+ */
+declare const includesSegment: SegmentTestFunction;
+
+/**
+ * Checks if two routes are related in the hierarchy.
+ *
+ * Routes are related if:
+ * - They are exactly the same
+ * - One is a parent of the other (e.g., "users" and "users.list")
+ * - One is a child of the other (e.g., "users.list" and "users")
+ *
+ * @param route1 - First route name
+ * @param route2 - Second route name
+ * @returns True if routes are related, false otherwise
+ *
+ * @example
+ * areRoutesRelated("users", "users.list");     // true (parent-child)
+ * areRoutesRelated("users.list", "users");     // true (child-parent)
+ * areRoutesRelated("users", "users");          // true (same)
+ * areRoutesRelated("users", "admin");          // false (different branches)
+ * areRoutesRelated("users.list", "users.view"); // false (siblings)
+ */
+declare function areRoutesRelated(route1: string, route2: string): boolean;
+
+export { type SegmentTestFunction, areRoutesRelated, endsWithSegment, includesSegment, startsWithSegment };

package/dist/cjs/index.js

@@ -0,0 +1 @@
+var e=/^[\w.-]+$/,t=e=>e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`),r=(r,n)=>{const s=s=>{if(s.length>1e4)throw new RangeError("Segment exceeds maximum length of 10000 characters");if(!e.test(s))throw new TypeError("Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)");return new RegExp(r+t(s)+n)};return(e,t)=>{const r="string"==typeof e?e:e.name;if("string"!=typeof r)return!1;if(0===r.length)return!1;if(null===t)return!1;if(void 0===t)return e=>{if("string"!=typeof e)throw new TypeError("Segment must be a string, got "+typeof e);return 0!==e.length&&s(e).test(r)};if("string"!=typeof t)throw new TypeError("Segment must be a string, got "+typeof t);return 0!==t.length&&s(t).test(r)}},n=`(?:${t(".")}|$)`,s=r("^",n),o=r(`(?:^|${t(".")})`,"$"),i=r(`(?:^|${t(".")})`,n);exports.areRoutesRelated=function(e,t){return e===t||e.startsWith(`${t}.`)||t.startsWith(`${e}.`)},exports.endsWithSegment=o,exports.includesSegment=i,exports.startsWithSegment=s;//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants.ts","../../src/helpers.ts","../../src/routeRelation.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// packages/helpers/modules/constants.ts\n\n/**\n * Maximum allowed segment length (10,000 characters)\n */\nexport const MAX_SEGMENT_LENGTH = 10_000;\n\n/**\n * Pattern for valid segment characters: alphanumeric + dot + dash + underscore\n * Uses explicit character ranges for clarity and portability.\n * Dash is placed at the end to avoid escaping (no range operator confusion).\n */\nexport const SAFE_SEGMENT_PATTERN = /^[\\w.-]+$/;\n\n/**\n * Route segment separator character\n */\nexport const ROUTE_SEGMENT_SEPARATOR = \".\";\n","// packages/helpers/modules/index.ts\n\nimport {\n  MAX_SEGMENT_LENGTH,\n  ROUTE_SEGMENT_SEPARATOR,\n  SAFE_SEGMENT_PATTERN,\n} from \"./constants\";\n\nimport type { SegmentTestFunction } from \"./types\";\nimport type { State } from \"@real-router/core\";\n\n/**\n * Escapes special RegExp characters in a string.\n * Handles all RegExp metacharacters including dash in character classes.\n *\n * @param str - String to escape\n * @returns Escaped string safe for RegExp construction\n * @internal\n */\nconst escapeRegExp = (str: string): string =>\n  str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n\n/**\n * Creates a segment tester function with specified start and end patterns.\n * This is a factory function that produces the actual test functions.\n *\n * @param start - RegExp pattern for start (e.g., \"^\" for startsWith)\n * @param end - RegExp pattern for end (e.g., \"$\" or dotOrEnd for specific matching)\n * @returns A test function that can check if routes match the segment pattern\n * @internal\n */\nconst makeSegmentTester = (start: string, end: string) => {\n  /**\n   * Builds a RegExp for testing segment matches.\n   * Validates length and character pattern. Type and empty checks are done by caller.\n   *\n   * This optimizes performance by avoiding redundant checks - callers verify\n   * type and empty before calling this function.\n   *\n   * @param segment - The segment to build a regex for (non-empty string, pre-validated)\n   * @returns RegExp for testing\n   * @throws {RangeError} If segment exceeds maximum length\n   * @throws {TypeError} If segment contains invalid characters\n   * @internal\n   */\n  const buildRegex = (segment: string): RegExp => {\n    // Type and empty checks are SKIPPED - caller already verified these\n\n    // Length check\n    if (segment.length > MAX_SEGMENT_LENGTH) {\n      throw new RangeError(\n        `Segment exceeds maximum length of ${MAX_SEGMENT_LENGTH} characters`,\n      );\n    }\n\n    // Character pattern check\n    if (!SAFE_SEGMENT_PATTERN.test(segment)) {\n      throw new TypeError(\n        `Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)`,\n      );\n    }\n\n    return new RegExp(start + escapeRegExp(segment) + end);\n  };\n\n  // TypeScript cannot infer conditional return type for curried function with union return.\n  // The function returns either boolean or a tester function based on whether segment is provided.\n  // This is an intentional design pattern for API flexibility.\n  // eslint-disable-next-line sonarjs/function-return-type\n  return (route: State | string, segment?: string | null) => {\n    // Extract route name, handling both string and State object inputs\n    // State.name is always string by real-router type definition\n    const name = typeof route === \"string\" ? route : route.name;\n\n    if (typeof name !== \"string\") {\n      return false;\n    }\n\n    // Empty route name always returns false\n    if (name.length === 0) {\n      return false;\n    }\n\n    // null always returns false (consistent behavior)\n    if (segment === null) {\n      return false;\n    }\n\n    // Currying: if no segment provided, return a tester function\n    if (segment === undefined) {\n      return (localSegment: string) => {\n        // Type check for runtime safety (consistent with direct call)\n        if (typeof localSegment !== \"string\") {\n          throw new TypeError(\n            `Segment must be a string, got ${typeof localSegment}`,\n          );\n        }\n\n        // Empty string returns false (consistent with direct call)\n        if (localSegment.length === 0) {\n          return false;\n        }\n\n        // Use buildRegex (type and empty checks already done above)\n        return buildRegex(localSegment).test(name);\n      };\n    }\n\n    if (typeof segment !== \"string\") {\n      // Runtime protection: TypeScript already narrows to 'string' here,\n      // but we keep this check for defense against unexpected runtime values\n      throw new TypeError(`Segment must be a string, got ${typeof segment}`);\n    }\n\n    // Empty string returns false (consistent behavior)\n    if (segment.length === 0) {\n      return false;\n    }\n\n    // Perform the actual regex test\n    // buildRegex skips type and empty checks (already validated above)\n    return buildRegex(segment).test(name);\n  };\n};\n\n/**\n * Pattern that matches either a dot separator or end of string.\n * Used for prefix/suffix matching that respects segment boundaries.\n */\nconst dotOrEnd = `(?:${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)}|$)`;\n\n/**\n * Tests if a route name starts with the given segment.\n *\n * Supports both direct calls and curried form for flexible usage patterns.\n * All segments are validated for safety (length and character constraints).\n *\n * @param route - Route state object or route name string\n * @param segment - Segment to test. If omitted, returns a tester function.\n *\n * @returns\n * - `boolean` if segment is provided (true if route starts with segment)\n * - `(segment: string) => boolean` if segment is omitted (curried tester function)\n * - `false` if segment is null or empty string\n *\n * @example\n * // Direct call\n * startsWithSegment('users.list', 'users'); // true\n * startsWithSegment('users.list', 'admin'); // false\n * startsWithSegment('admin.panel', 'users'); // false\n *\n * @example\n * // Curried form\n * const tester = startsWithSegment('users.list');\n * tester('users'); // true\n * tester('users.list'); // true\n * tester('admin'); // false\n *\n * @example\n * // With State object\n * const state: State = { name: 'users.list', params: {}, path: '/users/list' };\n * startsWithSegment(state, 'users'); // true\n *\n * @example\n * // Edge cases\n * startsWithSegment('users', ''); // false\n * startsWithSegment('users', null); // false\n * startsWithSegment('', 'users'); // false\n *\n * @throws {TypeError} If segment contains invalid characters or is not a string\n * @throws {RangeError} If segment exceeds maximum length (10,000 characters)\n *\n * @remarks\n * **Validation rules:**\n * - Allowed characters: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)\n * - Maximum segment length: 10,000 characters\n * - Empty segments are rejected\n *\n * **Performance:**\n * - No caching (RegExp compiled on each call)\n * - For high-frequency checks, consider caching results at application level\n *\n * **Segment boundaries:**\n * - Respects dot-separated segments\n * - 'users' matches 'users' and 'users.list'\n * - 'users' does NOT match 'users2' or 'admin.users'\n *\n * @see endsWithSegment for suffix matching\n * @see includesSegment for anywhere matching\n */\nexport const startsWithSegment = makeSegmentTester(\n  \"^\",\n  dotOrEnd,\n) as SegmentTestFunction;\n\n/**\n * Tests if a route name ends with the given segment.\n *\n * Supports both direct calls and curried form for flexible usage patterns.\n * All segments are validated for safety (length and character constraints).\n *\n * @param route - Route state object or route name string\n * @param segment - Segment to test. If omitted, returns a tester function.\n *\n * @returns\n * - `boolean` if segment is provided (true if route ends with segment)\n * - `(segment: string) => boolean` if segment is omitted (curried tester function)\n * - `false` if segment is null or empty string\n *\n * @example\n * // Direct call\n * endsWithSegment('users.list', 'list'); // true\n * endsWithSegment('users.profile.edit', 'edit'); // true\n * endsWithSegment('users.list', 'users'); // false\n *\n * @example\n * // Multi-segment suffix\n * endsWithSegment('a.b.c.d', 'c.d'); // true\n * endsWithSegment('a.b.c.d', 'b.c'); // false\n *\n * @example\n * // Curried form\n * const tester = endsWithSegment('users.list');\n * tester('list'); // true\n * tester('users'); // false\n *\n * @throws {TypeError} If segment contains invalid characters or is not a string\n * @throws {RangeError} If segment exceeds maximum length (10,000 characters)\n *\n * @remarks\n * See {@link startsWithSegment} for detailed validation rules and performance notes.\n *\n * @see startsWithSegment for prefix matching\n * @see includesSegment for anywhere matching\n */\nexport const endsWithSegment = makeSegmentTester(\n  `(?:^|${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)})`,\n  \"$\",\n) as SegmentTestFunction;\n\n/**\n * Tests if a route name includes the given segment anywhere in its path.\n *\n * Supports both direct calls and curried form for flexible usage patterns.\n * All segments are validated for safety (length and character constraints).\n *\n * @param route - Route state object or route name string\n * @param segment - Segment to test. If omitted, returns a tester function.\n *\n * @returns\n * - `boolean` if segment is provided (true if route includes segment)\n * - `(segment: string) => boolean` if segment is omitted (curried tester function)\n * - `false` if segment is null or empty string\n *\n * @example\n * // Direct call\n * includesSegment('users.profile.edit', 'profile'); // true\n * includesSegment('users.profile.edit', 'users'); // true\n * includesSegment('users.profile.edit', 'edit'); // true\n * includesSegment('users.profile.edit', 'admin'); // false\n *\n * @example\n * // Multi-segment inclusion\n * includesSegment('a.b.c.d', 'b.c'); // true\n * includesSegment('a.b.c.d', 'a.c'); // false (must be contiguous)\n *\n * @example\n * // Curried form\n * const tester = includesSegment('users.profile.edit');\n * tester('profile'); // true\n * tester('admin'); // false\n *\n * @throws {TypeError} If segment contains invalid characters or is not a string\n * @throws {RangeError} If segment exceeds maximum length (10,000 characters)\n *\n * @remarks\n * **Important:** Segment must be contiguous in the route path.\n * - 'a.b.c' includes 'a.b' and 'b.c' but NOT 'a.c'\n *\n * See {@link startsWithSegment} for detailed validation rules and performance notes.\n *\n * @see startsWithSegment for prefix matching\n * @see endsWithSegment for suffix matching\n */\nexport const includesSegment = makeSegmentTester(\n  `(?:^|${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)})`,\n  dotOrEnd,\n) as SegmentTestFunction;\n","// packages/helpers/modules/routeRelation.ts\n\n/**\n * Checks if two routes are related in the hierarchy.\n *\n * Routes are related if:\n * - They are exactly the same\n * - One is a parent of the other (e.g., \"users\" and \"users.list\")\n * - One is a child of the other (e.g., \"users.list\" and \"users\")\n *\n * @param route1 - First route name\n * @param route2 - Second route name\n * @returns True if routes are related, false otherwise\n *\n * @example\n * areRoutesRelated(\"users\", \"users.list\");     // true (parent-child)\n * areRoutesRelated(\"users.list\", \"users\");     // true (child-parent)\n * areRoutesRelated(\"users\", \"users\");          // true (same)\n * areRoutesRelated(\"users\", \"admin\");          // false (different branches)\n * areRoutesRelated(\"users.list\", \"users.view\"); // false (siblings)\n */\nexport function areRoutesRelated(route1: string, route2: string): boolean {\n  return (\n    route1 === route2 ||\n    route1.startsWith(`${route2}.`) ||\n    route2.startsWith(`${route1}.`)\n  );\n}\n"]}

package/dist/cjs/metafile-cjs.json

@@ -0,0 +1 @@
+{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/constants.ts":{"bytes":515,"imports":[{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/helpers.ts":{"bytes":9955,"imports":[{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/routeRelation.ts":{"bytes":994,"imports":[{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/index.ts":{"bytes":225,"imports":[{"path":"src/helpers.ts","kind":"import-statement","original":"./helpers"},{"path":"src/routeRelation.ts","kind":"import-statement","original":"./routeRelation"},{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js.map":{"imports":[],"exports":[],"inputs":{},"bytes":13383},"dist/cjs/index.js":{"imports":[],"exports":["areRoutesRelated","endsWithSegment","includesSegment","startsWithSegment"],"entryPoint":"src/index.ts","inputs":{"src/constants.ts":{"bytesInOutput":105},"src/helpers.ts":{"bytesInOutput":1800},"src/index.ts":{"bytesInOutput":0},"src/routeRelation.ts":{"bytesInOutput":144}},"bytes":2203}}}

package/dist/esm/index.d.mts

@@ -0,0 +1,182 @@
+import { State } from '@real-router/core';
+
+/**
+ * Type definition for segment test functions.
+ * These functions can be called directly with a segment, or curried for later use.
+ */
+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);
+}
+
+/**
+ * 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
+ * startsWithSegment('admin.panel', 'users'); // false
+ *
+ * @example
+ * // Curried form
+ * const tester = startsWithSegment('users.list');
+ * tester('users'); // true
+ * tester('users.list'); // true
+ * tester('admin'); // false
+ *
+ * @example
+ * // With State object
+ * const state: State = { name: 'users.list', params: {}, path: '/users/list' };
+ * startsWithSegment(state, 'users'); // true
+ *
+ * @example
+ * // Edge cases
+ * startsWithSegment('users', ''); // false
+ * startsWithSegment('users', null); // false
+ * startsWithSegment('', 'users'); // false
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @remarks
+ * **Validation rules:**
+ * - Allowed characters: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)
+ * - Maximum segment length: 10,000 characters
+ * - Empty segments are rejected
+ *
+ * **Performance:**
+ * - No caching (RegExp compiled on each call)
+ * - For high-frequency checks, consider caching results at application level
+ *
+ * **Segment boundaries:**
+ * - Respects dot-separated segments
+ * - 'users' matches 'users' and 'users.list'
+ * - 'users' does NOT match 'users2' or 'admin.users'
+ *
+ * @see endsWithSegment for suffix matching
+ * @see includesSegment for anywhere matching
+ */
+declare const startsWithSegment: 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
+ * endsWithSegment('users.list', 'users'); // false
+ *
+ * @example
+ * // Multi-segment suffix
+ * endsWithSegment('a.b.c.d', 'c.d'); // true
+ * endsWithSegment('a.b.c.d', 'b.c'); // false
+ *
+ * @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)
+ *
+ * @remarks
+ * See {@link startsWithSegment} for detailed validation rules and performance notes.
+ *
+ * @see startsWithSegment for prefix matching
+ * @see includesSegment for anywhere matching
+ */
+declare const endsWithSegment: 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
+ * includesSegment('users.profile.edit', 'users'); // true
+ * includesSegment('users.profile.edit', 'edit'); // true
+ * includesSegment('users.profile.edit', 'admin'); // false
+ *
+ * @example
+ * // Multi-segment inclusion
+ * includesSegment('a.b.c.d', 'b.c'); // true
+ * includesSegment('a.b.c.d', 'a.c'); // false (must be contiguous)
+ *
+ * @example
+ * // Curried form
+ * const tester = includesSegment('users.profile.edit');
+ * tester('profile'); // true
+ * tester('admin'); // false
+ *
+ * @throws {TypeError} If segment contains invalid characters or is not a string
+ * @throws {RangeError} If segment exceeds maximum length (10,000 characters)
+ *
+ * @remarks
+ * **Important:** Segment must be contiguous in the route path.
+ * - 'a.b.c' includes 'a.b' and 'b.c' but NOT 'a.c'
+ *
+ * See {@link startsWithSegment} for detailed validation rules and performance notes.
+ *
+ * @see startsWithSegment for prefix matching
+ * @see endsWithSegment for suffix matching
+ */
+declare const includesSegment: SegmentTestFunction;
+
+/**
+ * Checks if two routes are related in the hierarchy.
+ *
+ * Routes are related if:
+ * - They are exactly the same
+ * - One is a parent of the other (e.g., "users" and "users.list")
+ * - One is a child of the other (e.g., "users.list" and "users")
+ *
+ * @param route1 - First route name
+ * @param route2 - Second route name
+ * @returns True if routes are related, false otherwise
+ *
+ * @example
+ * areRoutesRelated("users", "users.list");     // true (parent-child)
+ * areRoutesRelated("users.list", "users");     // true (child-parent)
+ * areRoutesRelated("users", "users");          // true (same)
+ * areRoutesRelated("users", "admin");          // false (different branches)
+ * areRoutesRelated("users.list", "users.view"); // false (siblings)
+ */
+declare function areRoutesRelated(route1: string, route2: string): boolean;
+
+export { type SegmentTestFunction, areRoutesRelated, endsWithSegment, includesSegment, startsWithSegment };

package/dist/esm/index.mjs

@@ -0,0 +1 @@
+var t=/^[\w.-]+$/,e=t=>t.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`),r=(r,n)=>{const o=o=>{if(o.length>1e4)throw new RangeError("Segment exceeds maximum length of 10000 characters");if(!t.test(o))throw new TypeError("Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)");return new RegExp(r+e(o)+n)};return(t,e)=>{const r="string"==typeof t?t:t.name;if("string"!=typeof r)return!1;if(0===r.length)return!1;if(null===e)return!1;if(void 0===e)return t=>{if("string"!=typeof t)throw new TypeError("Segment must be a string, got "+typeof t);return 0!==t.length&&o(t).test(r)};if("string"!=typeof e)throw new TypeError("Segment must be a string, got "+typeof e);return 0!==e.length&&o(e).test(r)}},n=`(?:${e(".")}|$)`,o=r("^",n),i=r(`(?:^|${e(".")})`,"$"),s=r(`(?:^|${e(".")})`,n);function g(t,e){return t===e||t.startsWith(`${e}.`)||e.startsWith(`${t}.`)}export{g as areRoutesRelated,i as endsWithSegment,s as includesSegment,o as startsWithSegment};//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants.ts","../../src/helpers.ts","../../src/routeRelation.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// packages/helpers/modules/constants.ts\n\n/**\n * Maximum allowed segment length (10,000 characters)\n */\nexport const MAX_SEGMENT_LENGTH = 10_000;\n\n/**\n * Pattern for valid segment characters: alphanumeric + dot + dash + underscore\n * Uses explicit character ranges for clarity and portability.\n * Dash is placed at the end to avoid escaping (no range operator confusion).\n */\nexport const SAFE_SEGMENT_PATTERN = /^[\\w.-]+$/;\n\n/**\n * Route segment separator character\n */\nexport const ROUTE_SEGMENT_SEPARATOR = \".\";\n","// packages/helpers/modules/index.ts\n\nimport {\n  MAX_SEGMENT_LENGTH,\n  ROUTE_SEGMENT_SEPARATOR,\n  SAFE_SEGMENT_PATTERN,\n} from \"./constants\";\n\nimport type { SegmentTestFunction } from \"./types\";\nimport type { State } from \"@real-router/core\";\n\n/**\n * Escapes special RegExp characters in a string.\n * Handles all RegExp metacharacters including dash in character classes.\n *\n * @param str - String to escape\n * @returns Escaped string safe for RegExp construction\n * @internal\n */\nconst escapeRegExp = (str: string): string =>\n  str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n\n/**\n * Creates a segment tester function with specified start and end patterns.\n * This is a factory function that produces the actual test functions.\n *\n * @param start - RegExp pattern for start (e.g., \"^\" for startsWith)\n * @param end - RegExp pattern for end (e.g., \"$\" or dotOrEnd for specific matching)\n * @returns A test function that can check if routes match the segment pattern\n * @internal\n */\nconst makeSegmentTester = (start: string, end: string) => {\n  /**\n   * Builds a RegExp for testing segment matches.\n   * Validates length and character pattern. Type and empty checks are done by caller.\n   *\n   * This optimizes performance by avoiding redundant checks - callers verify\n   * type and empty before calling this function.\n   *\n   * @param segment - The segment to build a regex for (non-empty string, pre-validated)\n   * @returns RegExp for testing\n   * @throws {RangeError} If segment exceeds maximum length\n   * @throws {TypeError} If segment contains invalid characters\n   * @internal\n   */\n  const buildRegex = (segment: string): RegExp => {\n    // Type and empty checks are SKIPPED - caller already verified these\n\n    // Length check\n    if (segment.length > MAX_SEGMENT_LENGTH) {\n      throw new RangeError(\n        `Segment exceeds maximum length of ${MAX_SEGMENT_LENGTH} characters`,\n      );\n    }\n\n    // Character pattern check\n    if (!SAFE_SEGMENT_PATTERN.test(segment)) {\n      throw new TypeError(\n        `Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)`,\n      );\n    }\n\n    return new RegExp(start + escapeRegExp(segment) + end);\n  };\n\n  // TypeScript cannot infer conditional return type for curried function with union return.\n  // The function returns either boolean or a tester function based on whether segment is provided.\n  // This is an intentional design pattern for API flexibility.\n  // eslint-disable-next-line sonarjs/function-return-type\n  return (route: State | string, segment?: string | null) => {\n    // Extract route name, handling both string and State object inputs\n    // State.name is always string by real-router type definition\n    const name = typeof route === \"string\" ? route : route.name;\n\n    if (typeof name !== \"string\") {\n      return false;\n    }\n\n    // Empty route name always returns false\n    if (name.length === 0) {\n      return false;\n    }\n\n    // null always returns false (consistent behavior)\n    if (segment === null) {\n      return false;\n    }\n\n    // Currying: if no segment provided, return a tester function\n    if (segment === undefined) {\n      return (localSegment: string) => {\n        // Type check for runtime safety (consistent with direct call)\n        if (typeof localSegment !== \"string\") {\n          throw new TypeError(\n            `Segment must be a string, got ${typeof localSegment}`,\n          );\n        }\n\n        // Empty string returns false (consistent with direct call)\n        if (localSegment.length === 0) {\n          return false;\n        }\n\n        // Use buildRegex (type and empty checks already done above)\n        return buildRegex(localSegment).test(name);\n      };\n    }\n\n    if (typeof segment !== \"string\") {\n      // Runtime protection: TypeScript already narrows to 'string' here,\n      // but we keep this check for defense against unexpected runtime values\n      throw new TypeError(`Segment must be a string, got ${typeof segment}`);\n    }\n\n    // Empty string returns false (consistent behavior)\n    if (segment.length === 0) {\n      return false;\n    }\n\n    // Perform the actual regex test\n    // buildRegex skips type and empty checks (already validated above)\n    return buildRegex(segment).test(name);\n  };\n};\n\n/**\n * Pattern that matches either a dot separator or end of string.\n * Used for prefix/suffix matching that respects segment boundaries.\n */\nconst dotOrEnd = `(?:${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)}|$)`;\n\n/**\n * Tests if a route name starts with the given segment.\n *\n * Supports both direct calls and curried form for flexible usage patterns.\n * All segments are validated for safety (length and character constraints).\n *\n * @param route - Route state object or route name string\n * @param segment - Segment to test. If omitted, returns a tester function.\n *\n * @returns\n * - `boolean` if segment is provided (true if route starts with segment)\n * - `(segment: string) => boolean` if segment is omitted (curried tester function)\n * - `false` if segment is null or empty string\n *\n * @example\n * // Direct call\n * startsWithSegment('users.list', 'users'); // true\n * startsWithSegment('users.list', 'admin'); // false\n * startsWithSegment('admin.panel', 'users'); // false\n *\n * @example\n * // Curried form\n * const tester = startsWithSegment('users.list');\n * tester('users'); // true\n * tester('users.list'); // true\n * tester('admin'); // false\n *\n * @example\n * // With State object\n * const state: State = { name: 'users.list', params: {}, path: '/users/list' };\n * startsWithSegment(state, 'users'); // true\n *\n * @example\n * // Edge cases\n * startsWithSegment('users', ''); // false\n * startsWithSegment('users', null); // false\n * startsWithSegment('', 'users'); // false\n *\n * @throws {TypeError} If segment contains invalid characters or is not a string\n * @throws {RangeError} If segment exceeds maximum length (10,000 characters)\n *\n * @remarks\n * **Validation rules:**\n * - Allowed characters: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)\n * - Maximum segment length: 10,000 characters\n * - Empty segments are rejected\n *\n * **Performance:**\n * - No caching (RegExp compiled on each call)\n * - For high-frequency checks, consider caching results at application level\n *\n * **Segment boundaries:**\n * - Respects dot-separated segments\n * - 'users' matches 'users' and 'users.list'\n * - 'users' does NOT match 'users2' or 'admin.users'\n *\n * @see endsWithSegment for suffix matching\n * @see includesSegment for anywhere matching\n */\nexport const startsWithSegment = makeSegmentTester(\n  \"^\",\n  dotOrEnd,\n) as SegmentTestFunction;\n\n/**\n * Tests if a route name ends with the given segment.\n *\n * Supports both direct calls and curried form for flexible usage patterns.\n * All segments are validated for safety (length and character constraints).\n *\n * @param route - Route state object or route name string\n * @param segment - Segment to test. If omitted, returns a tester function.\n *\n * @returns\n * - `boolean` if segment is provided (true if route ends with segment)\n * - `(segment: string) => boolean` if segment is omitted (curried tester function)\n * - `false` if segment is null or empty string\n *\n * @example\n * // Direct call\n * endsWithSegment('users.list', 'list'); // true\n * endsWithSegment('users.profile.edit', 'edit'); // true\n * endsWithSegment('users.list', 'users'); // false\n *\n * @example\n * // Multi-segment suffix\n * endsWithSegment('a.b.c.d', 'c.d'); // true\n * endsWithSegment('a.b.c.d', 'b.c'); // false\n *\n * @example\n * // Curried form\n * const tester = endsWithSegment('users.list');\n * tester('list'); // true\n * tester('users'); // false\n *\n * @throws {TypeError} If segment contains invalid characters or is not a string\n * @throws {RangeError} If segment exceeds maximum length (10,000 characters)\n *\n * @remarks\n * See {@link startsWithSegment} for detailed validation rules and performance notes.\n *\n * @see startsWithSegment for prefix matching\n * @see includesSegment for anywhere matching\n */\nexport const endsWithSegment = makeSegmentTester(\n  `(?:^|${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)})`,\n  \"$\",\n) as SegmentTestFunction;\n\n/**\n * Tests if a route name includes the given segment anywhere in its path.\n *\n * Supports both direct calls and curried form for flexible usage patterns.\n * All segments are validated for safety (length and character constraints).\n *\n * @param route - Route state object or route name string\n * @param segment - Segment to test. If omitted, returns a tester function.\n *\n * @returns\n * - `boolean` if segment is provided (true if route includes segment)\n * - `(segment: string) => boolean` if segment is omitted (curried tester function)\n * - `false` if segment is null or empty string\n *\n * @example\n * // Direct call\n * includesSegment('users.profile.edit', 'profile'); // true\n * includesSegment('users.profile.edit', 'users'); // true\n * includesSegment('users.profile.edit', 'edit'); // true\n * includesSegment('users.profile.edit', 'admin'); // false\n *\n * @example\n * // Multi-segment inclusion\n * includesSegment('a.b.c.d', 'b.c'); // true\n * includesSegment('a.b.c.d', 'a.c'); // false (must be contiguous)\n *\n * @example\n * // Curried form\n * const tester = includesSegment('users.profile.edit');\n * tester('profile'); // true\n * tester('admin'); // false\n *\n * @throws {TypeError} If segment contains invalid characters or is not a string\n * @throws {RangeError} If segment exceeds maximum length (10,000 characters)\n *\n * @remarks\n * **Important:** Segment must be contiguous in the route path.\n * - 'a.b.c' includes 'a.b' and 'b.c' but NOT 'a.c'\n *\n * See {@link startsWithSegment} for detailed validation rules and performance notes.\n *\n * @see startsWithSegment for prefix matching\n * @see endsWithSegment for suffix matching\n */\nexport const includesSegment = makeSegmentTester(\n  `(?:^|${escapeRegExp(ROUTE_SEGMENT_SEPARATOR)})`,\n  dotOrEnd,\n) as SegmentTestFunction;\n","// packages/helpers/modules/routeRelation.ts\n\n/**\n * Checks if two routes are related in the hierarchy.\n *\n * Routes are related if:\n * - They are exactly the same\n * - One is a parent of the other (e.g., \"users\" and \"users.list\")\n * - One is a child of the other (e.g., \"users.list\" and \"users\")\n *\n * @param route1 - First route name\n * @param route2 - Second route name\n * @returns True if routes are related, false otherwise\n *\n * @example\n * areRoutesRelated(\"users\", \"users.list\");     // true (parent-child)\n * areRoutesRelated(\"users.list\", \"users\");     // true (child-parent)\n * areRoutesRelated(\"users\", \"users\");          // true (same)\n * areRoutesRelated(\"users\", \"admin\");          // false (different branches)\n * areRoutesRelated(\"users.list\", \"users.view\"); // false (siblings)\n */\nexport function areRoutesRelated(route1: string, route2: string): boolean {\n  return (\n    route1 === route2 ||\n    route1.startsWith(`${route2}.`) ||\n    route2.startsWith(`${route1}.`)\n  );\n}\n"]}

package/dist/esm/metafile-esm.json

@@ -0,0 +1 @@
+{"inputs":{"src/constants.ts":{"bytes":515,"imports":[],"format":"esm"},"src/helpers.ts":{"bytes":9955,"imports":[{"path":"src/constants.ts","kind":"import-statement","original":"./constants"}],"format":"esm"},"src/routeRelation.ts":{"bytes":994,"imports":[],"format":"esm"},"src/index.ts":{"bytes":225,"imports":[{"path":"src/helpers.ts","kind":"import-statement","original":"./helpers"},{"path":"src/routeRelation.ts","kind":"import-statement","original":"./routeRelation"}],"format":"esm"}},"outputs":{"dist/esm/index.mjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":13383},"dist/esm/index.mjs":{"imports":[],"exports":["areRoutesRelated","endsWithSegment","includesSegment","startsWithSegment"],"entryPoint":"src/index.ts","inputs":{"src/constants.ts":{"bytesInOutput":105},"src/helpers.ts":{"bytesInOutput":1800},"src/index.ts":{"bytesInOutput":0},"src/routeRelation.ts":{"bytesInOutput":144}},"bytes":2203}}}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@real-router/helpers",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "description": "Helper utilities for comparing and checking routes",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/esm/index.d.mts",
+        "require": "./dist/cjs/index.d.ts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greydragon888/real-router.git"
+  },
+  "keywords": [
+    "real-router",
+    "helpers"
+  ],
+  "author": {
+    "name": "Oleg Ivanov",
+    "email": "greydragon888@gmail.com",
+    "url": "https://github.com/greydragon888"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/greydragon888/real-router/issues"
+  },
+  "homepage": "https://github.com/greydragon888/real-router",
+  "scripts": {
+    "test": "vitest",
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
+    "lint:package": "publint",
+    "lint:types": "attw --pack ."
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "workspace:^"
+  }
+}