@teardown/navigation 2.0.43

package/src/types/type-utils.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from "bun:test";
+import type { ExtractAllParams, ExtractParam, HasRequiredParams, InferParams, Simplify } from "./type-utils";
+
+/**
+ * Type-level tests for template literal type utilities
+ * These tests verify that the type utilities correctly extract and infer route params
+ */
+
+// Helper type for testing - checks if two types are exactly equal
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+// Type assertion helper
+function assertType<T>(_value: T): void {}
+
+describe("Type Utils", () => {
+	describe("ExtractParam", () => {
+		it("should extract required param from [param]", () => {
+			// Test: [userId] should produce { userId: string }
+			type Result = ExtractParam<"[userId]">;
+			type Expected = { userId: string };
+
+			// Type-level assertion
+			const isEqual: Equals<Result, Expected> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("should extract optional param from [param]?", () => {
+			// Test: [section]? should produce { section?: string }
+			type Result = ExtractParam<"[section]?">;
+			type Expected = { section?: string };
+
+			const isEqual: Equals<Result, Expected> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("should extract catch-all param from [...slug]", () => {
+			// Test: [...slug] should produce { slug: string[] }
+			type Result = ExtractParam<"[...slug]">;
+			type Expected = { slug: string[] };
+
+			const isEqual: Equals<Result, Expected> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("should return empty object for static segment", () => {
+			// Test: about should produce Record<string, never>
+			type Result = ExtractParam<"about">;
+			type Expected = Record<string, never>;
+
+			const isEqual: Equals<Result, Expected> = true;
+			expect(isEqual).toBe(true);
+		});
+	});
+
+	describe("ExtractAllParams", () => {
+		it("should extract single param from path", () => {
+			type Result = ExtractAllParams<"/users/[userId]">;
+			// Should have userId: string
+			assertType<Result>({ userId: "123" });
+			expect(true).toBe(true);
+		});
+
+		it("should extract multiple params from nested path", () => {
+			type Result = ExtractAllParams<"/users/[userId]/posts/[postId]">;
+			// Should have both userId and postId
+			assertType<Result>({ userId: "123", postId: "456" });
+			expect(true).toBe(true);
+		});
+
+		it("should handle mixed static and dynamic segments", () => {
+			type Result = ExtractAllParams<"/blog/[year]/[month]/[day]/[slug]">;
+			assertType<Result>({ year: "2025", month: "01", day: "28", slug: "hello" });
+			expect(true).toBe(true);
+		});
+	});
+
+	describe("InferParams", () => {
+		it("should return empty object for static path", () => {
+			type Result = InferParams<"/about">;
+			// For static paths, params should be essentially empty
+			const result: Result = {};
+			expect(Object.keys(result).length).toBe(0);
+		});
+
+		it("should infer required param", () => {
+			type Result = InferParams<"/users/[userId]">;
+			const result: Result = { userId: "123" };
+			expect(result.userId).toBe("123");
+		});
+
+		it("should infer optional param", () => {
+			type Result = InferParams<"/settings/[section]?">;
+			// Should allow undefined for optional params
+			const withParam: Result = { section: "profile" };
+			const withoutParam: Result = {};
+			expect(withParam.section).toBe("profile");
+			expect(withoutParam.section).toBeUndefined();
+		});
+
+		it("should infer catch-all param as string array", () => {
+			type Result = InferParams<"/docs/[...slug]">;
+			const result: Result = { slug: ["a", "b", "c"] };
+			expect(result.slug).toEqual(["a", "b", "c"]);
+		});
+
+		it("should infer multiple params from complex path", () => {
+			type Result = InferParams<"/users/[userId]/posts/[postId]">;
+			const result: Result = { userId: "123", postId: "456" };
+			expect(result.userId).toBe("123");
+			expect(result.postId).toBe("456");
+		});
+	});
+
+	describe("HasRequiredParams", () => {
+		it("should return false for undefined params", () => {
+			type Result = HasRequiredParams<undefined>;
+			const result: Result = false;
+			expect(result).toBe(false);
+		});
+
+		it("should return false for empty object", () => {
+			type Result = HasRequiredParams<Record<string, never>>;
+			const result: Result = false;
+			expect(result).toBe(false);
+		});
+
+		it("should return true for object with required keys", () => {
+			type Result = HasRequiredParams<{ userId: string }>;
+			const result: Result = true;
+			expect(result).toBe(true);
+		});
+	});
+
+	describe("Simplify", () => {
+		it("should flatten intersection types", () => {
+			type Complex = { a: string } & { b: number };
+			type Result = Simplify<Complex>;
+			const result: Result = { a: "test", b: 42 };
+			expect(result.a).toBe("test");
+			expect(result.b).toBe(42);
+		});
+	});
+
+	describe("NavigateArgs", () => {
+		// Define a mock RouteParams for testing
+		type MockRouteParams = {
+			"/": undefined;
+			"/about": undefined;
+			"/users/[userId]": { userId: string };
+			"/users/[userId]/posts/[postId]": { userId: string; postId: string };
+			"/settings/[section]?": { section?: string };
+		};
+
+		type MockRoutePath = keyof MockRouteParams;
+		type MockParamsFor<T extends MockRoutePath> = MockRouteParams[T];
+
+		// Test NavigateArgs type behavior
+		it("should allow calling without params for static routes", () => {
+			// For routes with undefined params, should be [path] or [path, undefined]
+			type Args = MockParamsFor<"/"> extends undefined ? [path: "/"] : [path: "/", params: MockParamsFor<"/">];
+
+			const args: Args = ["/"];
+			expect(args[0]).toBe("/");
+		});
+
+		it("should require params for dynamic routes", () => {
+			// For routes with params, must include params object
+			type Args = [path: "/users/[userId]", params: MockParamsFor<"/users/[userId]">];
+
+			const args: Args = ["/users/[userId]", { userId: "123" }];
+			expect(args[0]).toBe("/users/[userId]");
+			expect(args[1].userId).toBe("123");
+		});
+	});
+});

package/src/types/type-utils.ts

@@ -0,0 +1,91 @@
+/**
+ * Type utilities for extracting route parameters from path strings
+ * Uses template literal types to provide compile-time type inference
+ */
+
+/**
+ * Simplifies intersection types for better IDE display
+ * Converts { a: string } & { b: number } to { a: string; b: number }
+ */
+export type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * Extracts parameter from a single path segment
+ *
+ * - [userId] -> { userId: string }
+ * - [...slug] -> { slug: string[] }
+ * - [section]? -> { section?: string }
+ * - about -> Record<string, never>
+ */
+export type ExtractParam<Segment extends string> = Segment extends `[...${infer Rest}]`
+	? { [K in Rest]: string[] }
+	: Segment extends `[${infer Param}]?`
+		? { [K in Param]?: string }
+		: Segment extends `[${infer Param}]`
+			? { [K in Param]: string }
+			: Record<string, never>;
+
+/**
+ * Recursively extracts all params from a path
+ *
+ * /users/[userId]/posts/[postId] -> { userId: string; postId: string }
+ */
+export type ExtractAllParams<Path extends string> = Path extends `${infer Segment}/${infer Rest}`
+	? ExtractParam<Segment> & ExtractAllParams<Rest>
+	: ExtractParam<Path>;
+
+/**
+ * Final param extraction with simplification
+ * Cleans up intersection types for better IDE display
+ */
+export type InferParams<Path extends string> = Simplify<ExtractAllParams<Path>>;
+
+/**
+ * Checks if a type has required (non-optional) keys
+ * Returns true if the type has at least one required key
+ */
+export type HasRequiredParams<T> = T extends undefined
+	? false
+	: T extends Record<string, never>
+		? false
+		: keyof T extends never
+			? false
+			: true;
+
+/**
+ * Navigation argument type - params required only when route has params
+ * Allows calling navigate('/about') without params
+ * But requires navigate('/users/[userId]', { userId: '123' })
+ */
+export type NavigateArgs<TPath extends string, TParams> = HasRequiredParams<TParams> extends true
+	? [path: TPath, params: TParams]
+	: [path: TPath] | [path: TPath, params?: undefined];
+
+/**
+ * Helper type to check if a segment is dynamic
+ */
+export type IsDynamicSegment<Segment extends string> = Segment extends `[${string}]` ? true : false;
+
+/**
+ * Helper type to check if a segment is optional
+ */
+export type IsOptionalSegment<Segment extends string> = Segment extends `[${string}]?` ? true : false;
+
+/**
+ * Helper type to check if a segment is catch-all
+ */
+export type IsCatchAllSegment<Segment extends string> = Segment extends `[...${string}]` ? true : false;
+
+/**
+ * Extracts the parameter name from a segment
+ * [userId] -> "userId"
+ * [...slug] -> "slug"
+ * [section]? -> "section"
+ */
+export type ExtractParamName<Segment extends string> = Segment extends `[...${infer Name}]`
+	? Name
+	: Segment extends `[${infer Name}]?`
+		? Name
+		: Segment extends `[${infer Name}]`
+			? Name
+			: never;

package/src/utils/build-url.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "bun:test";
+import { buildUrl, matchPath, parsePath, pathToScreenName } from "./build-url";
+
+describe("URL Utilities", () => {
+	describe("buildUrl", () => {
+		it("should build static path without params", () => {
+			expect(buildUrl("/about")).toBe("/about");
+		});
+
+		it("should build root path", () => {
+			expect(buildUrl("/")).toBe("/");
+		});
+
+		it("should build path with single required param", () => {
+			expect(buildUrl("/users/:userId", { userId: "123" })).toBe("/users/123");
+		});
+
+		it("should build path with multiple params", () => {
+			expect(buildUrl("/users/:userId/posts/:postId", { userId: "123", postId: "456" })).toBe("/users/123/posts/456");
+		});
+
+		it("should handle optional param when provided", () => {
+			expect(buildUrl("/settings/:section?", { section: "profile" })).toBe("/settings/profile");
+		});
+
+		it("should handle optional param when omitted", () => {
+			expect(buildUrl("/settings/:section?", {})).toBe("/settings");
+		});
+
+		it("should handle catch-all param with array", () => {
+			expect(buildUrl("/docs/*", { slug: ["a", "b", "c"] })).toBe("/docs/a/b/c");
+		});
+
+		it("should remove route groups from URL", () => {
+			expect(buildUrl("/(tabs)/home")).toBe("/home");
+		});
+
+		it("should encode special characters in params", () => {
+			expect(buildUrl("/search/:query", { query: "hello world" })).toBe("/search/hello%20world");
+		});
+
+		it("should handle empty params object", () => {
+			expect(buildUrl("/about", {})).toBe("/about");
+		});
+	});
+
+	describe("parsePath", () => {
+		it("should parse static path", () => {
+			const result = parsePath("/about");
+			expect(result.segments).toEqual(["about"]);
+			expect(result.params).toEqual([]);
+		});
+
+		it("should parse path with required param", () => {
+			const result = parsePath("/users/:userId");
+			expect(result.segments).toEqual(["users", ":userId"]);
+			expect(result.params).toEqual([{ name: "userId", optional: false, catchAll: false }]);
+		});
+
+		it("should parse path with optional param", () => {
+			const result = parsePath("/settings/:section?");
+			expect(result.params).toEqual([{ name: "section", optional: true, catchAll: false }]);
+		});
+
+		it("should parse path with catch-all param", () => {
+			const result = parsePath("/docs/*");
+			expect(result.params).toEqual([{ name: "slug", optional: false, catchAll: true }]);
+		});
+
+		it("should parse complex path with multiple params", () => {
+			const result = parsePath("/users/:userId/posts/:postId");
+			expect(result.params.length).toBe(2);
+			expect(result.params[0].name).toBe("userId");
+			expect(result.params[1].name).toBe("postId");
+		});
+	});
+
+	describe("matchPath", () => {
+		it("should match static path", () => {
+			const result = matchPath("/about", "/about");
+			expect(result).toEqual({ matched: true, params: {} });
+		});
+
+		it("should not match different static paths", () => {
+			const result = matchPath("/about", "/home");
+			expect(result.matched).toBe(false);
+		});
+
+		it("should match path with param and extract value", () => {
+			const result = matchPath("/users/:userId", "/users/123");
+			expect(result).toEqual({ matched: true, params: { userId: "123" } });
+		});
+
+		it("should match path with multiple params", () => {
+			const result = matchPath("/users/:userId/posts/:postId", "/users/123/posts/456");
+			expect(result).toEqual({ matched: true, params: { userId: "123", postId: "456" } });
+		});
+
+		it("should match optional param when present", () => {
+			const result = matchPath("/settings/:section?", "/settings/profile");
+			expect(result).toEqual({ matched: true, params: { section: "profile" } });
+		});
+
+		it("should match optional param when absent", () => {
+			const result = matchPath("/settings/:section?", "/settings");
+			expect(result).toEqual({ matched: true, params: {} });
+		});
+
+		it("should match catch-all and extract array", () => {
+			const result = matchPath("/docs/*", "/docs/a/b/c");
+			expect(result).toEqual({ matched: true, params: { slug: ["a", "b", "c"] } });
+		});
+
+		it("should not match when path is too short", () => {
+			const result = matchPath("/users/:userId/posts", "/users/123");
+			expect(result.matched).toBe(false);
+		});
+	});
+
+	describe("pathToScreenName", () => {
+		it("should convert path to screen name", () => {
+			expect(pathToScreenName("/users/:userId")).toBe("users/:userId");
+		});
+
+		it("should handle root path", () => {
+			expect(pathToScreenName("/")).toBe("");
+		});
+
+		it("should preserve params in screen name", () => {
+			expect(pathToScreenName("/users/:userId/posts/:postId")).toBe("users/:userId/posts/:postId");
+		});
+	});
+});

package/src/utils/build-url.ts

@@ -0,0 +1,164 @@
+/**
+ * URL building and parsing utilities for @teardown/navigation
+ */
+
+export interface ParsedPath {
+	segments: string[];
+	params: Array<{
+		name: string;
+		optional: boolean;
+		catchAll: boolean;
+	}>;
+}
+
+export interface MatchResult {
+	matched: boolean;
+	params: Record<string, string | string[]>;
+}
+
+/**
+ * Builds a URL from a route path and params
+ * Handles required params, optional params, and catch-all routes
+ */
+export function buildUrl(path: string, params: Record<string, string | string[] | undefined> = {}): string {
+	// Remove route groups from path
+	let url = path.replace(/\/\([^)]+\)/g, "");
+
+	// Replace optional params :param? FIRST (before required params)
+	url = url.replace(/:(\w+)\?/g, (_, paramName) => {
+		const value = params[paramName];
+		if (value !== undefined && value !== "") {
+			return encodeURIComponent(String(value));
+		}
+		return "";
+	});
+
+	// Replace required params :param (now that optional ones are handled)
+	url = url.replace(/:(\w+)/g, (_, paramName) => {
+		const value = params[paramName];
+		if (value !== undefined) {
+			if (Array.isArray(value)) {
+				return value.map(encodeURIComponent).join("/");
+			}
+			return encodeURIComponent(String(value));
+		}
+		return "";
+	});
+
+	// Replace catch-all params *
+	url = url.replace(/\*/g, () => {
+		// Catch-all params are typically named 'slug' by convention
+		const value = params.slug;
+		if (value !== undefined) {
+			if (Array.isArray(value)) {
+				return value.map(encodeURIComponent).join("/");
+			}
+			return encodeURIComponent(String(value));
+		}
+		return "";
+	});
+
+	// Clean up double slashes and trailing slashes (except root)
+	url = url.replace(/\/+/g, "/").replace(/\/$/, "");
+
+	// Ensure leading slash
+	if (!url.startsWith("/")) {
+		url = `/${url}`;
+	}
+
+	return url || "/";
+}
+
+/**
+ * Parses a route path into segments and param definitions
+ */
+export function parsePath(path: string): ParsedPath {
+	const segments = path.split("/").filter(Boolean);
+	const params: ParsedPath["params"] = [];
+
+	for (const segment of segments) {
+		if (segment === "*") {
+			params.push({ name: "slug", optional: false, catchAll: true });
+		} else if (segment.endsWith("?")) {
+			const name = segment.slice(1, -1); // Remove : and ?
+			params.push({ name, optional: true, catchAll: false });
+		} else if (segment.startsWith(":")) {
+			const name = segment.slice(1);
+			params.push({ name, optional: false, catchAll: false });
+		}
+	}
+
+	return { segments, params };
+}
+
+/**
+ * Attempts to match a URL against a route pattern
+ * Returns the extracted params if matched
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: path matching branches
+export function matchPath(pattern: string, url: string): MatchResult {
+	const patternParts = pattern.split("/").filter(Boolean);
+	const urlParts = url.split("/").filter(Boolean);
+
+	const params: Record<string, string | string[]> = {};
+
+	let patternIndex = 0;
+	let urlIndex = 0;
+
+	while (patternIndex < patternParts.length) {
+		const patternPart = patternParts[patternIndex];
+
+		// Handle catch-all
+		if (patternPart === "*") {
+			// Consume all remaining URL parts
+			params.slug = urlParts.slice(urlIndex);
+			return { matched: true, params };
+		}
+
+		// Handle optional param
+		if (patternPart.endsWith("?")) {
+			const paramName = patternPart.slice(1, -1);
+			if (urlIndex < urlParts.length) {
+				params[paramName] = urlParts[urlIndex];
+				urlIndex++;
+			}
+			patternIndex++;
+			continue;
+		}
+
+		// Handle required param
+		if (patternPart.startsWith(":")) {
+			if (urlIndex >= urlParts.length) {
+				return { matched: false, params: {} };
+			}
+			const paramName = patternPart.slice(1);
+			params[paramName] = urlParts[urlIndex];
+			urlIndex++;
+			patternIndex++;
+			continue;
+		}
+
+		// Handle static segment
+		if (urlIndex >= urlParts.length || patternPart !== urlParts[urlIndex]) {
+			return { matched: false, params: {} };
+		}
+
+		patternIndex++;
+		urlIndex++;
+	}
+
+	// Check if we consumed all URL parts (unless pattern has optional params)
+	if (urlIndex < urlParts.length) {
+		return { matched: false, params: {} };
+	}
+
+	return { matched: true, params };
+}
+
+/**
+ * Converts a route path to a React Navigation screen name
+ */
+export function pathToScreenName(path: string): string {
+	// Remove leading slash
+	return path.replace(/^\//, "");
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility functions for @teardown/navigation
+ */
+
+export { buildUrl, type MatchResult, matchPath, type ParsedPath, parsePath, pathToScreenName } from "./build-url";