@ereo/client 0.1.6

package/dist/typed-navigate.d.ts

@@ -0,0 +1,238 @@
+/**
+ * @ereo/client - Type-Safe Navigation Utilities
+ *
+ * Navigate and redirect functions with compile-time route validation.
+ *
+ * @example
+ * ```typescript
+ * // Client-side navigation
+ * await typedNavigate('/users/[id]', { params: { id: '123' } });
+ *
+ * // Server-side redirect
+ * return typedRedirect('/login', { search: { returnTo: '/dashboard' } });
+ *
+ * // With search and hash params (Ereo exclusive)
+ * await typedNavigate('/posts/[slug]', {
+ *   params: { slug: 'hello' },
+ *   search: { page: 1 },
+ *   hash: { section: 'comments' },
+ * });
+ * ```
+ */
+import type { TypedRoutes, RouteParamsFor, SearchParamsFor, HashParamsFor } from '@ereo/core';
+/**
+ * Check if params object is empty (no required params).
+ */
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+/**
+ * Check if all properties in T are optional.
+ */
+type AllOptional<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? true : false;
+}[keyof T] extends true ? true : false;
+/**
+ * Navigation options with conditional params requirement.
+ */
+export type TypedNavigateOptions<Path extends TypedRoutes> = (IsEmptyObject<RouteParamsFor<Path>> extends true ? {
+    params?: never;
+} : AllOptional<RouteParamsFor<Path>> extends true ? {
+    params?: RouteParamsFor<Path>;
+} : {
+    params: RouteParamsFor<Path>;
+}) & {
+    /** Search params */
+    search?: Partial<SearchParamsFor<Path>>;
+    /** Hash params - unique to Ereo */
+    hash?: Partial<HashParamsFor<Path>>;
+    /** Replace history instead of push */
+    replace?: boolean;
+    /** State to pass to the location */
+    state?: unknown;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+};
+/**
+ * Redirect options with conditional params requirement.
+ */
+export type TypedRedirectOptions<Path extends TypedRoutes> = (IsEmptyObject<RouteParamsFor<Path>> extends true ? {
+    params?: never;
+} : AllOptional<RouteParamsFor<Path>> extends true ? {
+    params?: RouteParamsFor<Path>;
+} : {
+    params: RouteParamsFor<Path>;
+}) & {
+    /** Search params */
+    search?: Partial<SearchParamsFor<Path>>;
+    /** Hash params - unique to Ereo */
+    hash?: Partial<HashParamsFor<Path>>;
+    /** HTTP status code (default: 302) */
+    status?: 301 | 302 | 303 | 307 | 308;
+    /** Custom headers */
+    headers?: HeadersInit;
+};
+/**
+ * Build a complete URL from pattern, params, search, and hash.
+ */
+export declare function buildTypedUrl<Path extends TypedRoutes>(pattern: Path, options?: {
+    params?: RouteParamsFor<Path>;
+    search?: Partial<SearchParamsFor<Path>>;
+    hash?: Partial<HashParamsFor<Path>>;
+}): string;
+/**
+ * Type-safe client-side navigation.
+ *
+ * Validates that:
+ * 1. The route path exists in your route definitions
+ * 2. Required params are provided with correct types
+ * 3. Search params match the route's search schema
+ * 4. Hash params match the route's hash schema (Ereo exclusive)
+ *
+ * @example
+ * ```typescript
+ * // Navigate to a static route
+ * await typedNavigate('/about');
+ *
+ * // Navigate with params
+ * await typedNavigate('/users/[id]', { params: { id: '123' } });
+ *
+ * // Navigate with all options
+ * await typedNavigate('/posts/[slug]', {
+ *   params: { slug: 'hello-world' },
+ *   search: { page: 1, sort: 'asc' },
+ *   hash: { section: 'comments' },
+ *   replace: true,
+ *   state: { fromDashboard: true },
+ * });
+ *
+ * // Error - missing required params
+ * await typedNavigate('/users/[id]'); // TypeScript error!
+ * ```
+ */
+export declare function typedNavigate<Path extends TypedRoutes>(path: Path, options?: TypedNavigateOptions<Path>): Promise<void>;
+/**
+ * Type-safe navigation function returned by useTypedNavigate.
+ */
+export interface TypedNavigateFunction {
+    /**
+     * Navigate to a typed route.
+     */
+    <Path extends TypedRoutes>(path: Path, options?: TypedNavigateOptions<Path>): Promise<void>;
+    /**
+     * Navigate by delta (back/forward).
+     */
+    (delta: number): void;
+}
+/**
+ * Hook that returns a type-safe navigate function.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const navigate = useTypedNavigate();
+ *
+ *   const handleClick = () => {
+ *     navigate('/users/[id]', { params: { id: '123' } });
+ *   };
+ *
+ *   const handleBack = () => {
+ *     navigate(-1);
+ *   };
+ *
+ *   return <button onClick={handleClick}>Go to user</button>;
+ * }
+ * ```
+ */
+export declare function useTypedNavigate(): TypedNavigateFunction;
+/**
+ * Type-safe server-side redirect.
+ *
+ * Creates a Response with redirect status and Location header.
+ * Use this in loaders and actions for server-side redirects.
+ *
+ * @example
+ * ```typescript
+ * // In a loader or action
+ * export const loader = async ({ request, context }) => {
+ *   const user = context.get<User>('user');
+ *
+ *   if (!user) {
+ *     return typedRedirect('/login', {
+ *       search: { returnTo: new URL(request.url).pathname },
+ *     });
+ *   }
+ *
+ *   return { user };
+ * };
+ *
+ * // Redirect to a route with params
+ * return typedRedirect('/users/[id]', {
+ *   params: { id: user.id },
+ *   status: 303,
+ * });
+ * ```
+ */
+export declare function typedRedirect<Path extends TypedRoutes>(path: Path, options?: TypedRedirectOptions<Path>): Response;
+/**
+ * Alias for typedRedirect for familiarity.
+ */
+export declare const redirect: typeof typedRedirect;
+/**
+ * Parse search params from a URL using a route's schema.
+ * Returns typed search params for the given route.
+ *
+ * @example
+ * ```typescript
+ * const url = new URL(request.url);
+ * const searchParams = parseTypedSearchParams<'/posts'>(url);
+ * // searchParams is typed as SearchParamsFor<'/posts'>
+ * ```
+ */
+export declare function parseTypedSearchParams<Path extends TypedRoutes>(url: URL | string): Partial<SearchParamsFor<Path>>;
+/**
+ * Parse hash params from a URL using a route's schema.
+ * Returns typed hash params for the given route.
+ * This is UNIQUE to Ereo - TanStack has no hash param support.
+ *
+ * @example
+ * ```typescript
+ * const url = new URL(request.url);
+ * const hashParams = parseTypedHashParams<'/posts/[slug]'>(url);
+ * // hashParams is typed as HashParamsFor<'/posts/[slug]'>
+ * ```
+ */
+export declare function parseTypedHashParams<Path extends TypedRoutes>(url: URL | string): Partial<HashParamsFor<Path>>;
+/**
+ * Go back in history.
+ */
+export declare function goBack(): void;
+/**
+ * Go forward in history.
+ */
+export declare function goForward(): void;
+/**
+ * Go to a specific history entry.
+ */
+export declare function go(delta: number): void;
+/**
+ * Check if a path is the current location.
+ */
+export declare function isCurrentPath<Path extends TypedRoutes>(path: Path, options?: {
+    params?: RouteParamsFor<Path>;
+    exact?: boolean;
+}): boolean;
+/**
+ * Preload a route's data before navigation.
+ * Useful for preparing data in advance.
+ *
+ * @example
+ * ```typescript
+ * // Preload on hover
+ * onMouseEnter={() => preloadRoute('/users/[id]', { params: { id: '123' } })}
+ * ```
+ */
+export declare function preloadRoute<Path extends TypedRoutes>(path: Path, options?: {
+    params?: RouteParamsFor<Path>;
+    search?: Partial<SearchParamsFor<Path>>;
+}): Promise<void>;
+export type { TypedRoutes, RouteParamsFor, SearchParamsFor, HashParamsFor };
+//# sourceMappingURL=typed-navigate.d.ts.map

package/dist/typed-navigate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-navigate.d.ts","sourceRoot":"","sources":["../src/typed-navigate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ereo/client",
+  "version": "0.1.6",
+  "license": "MIT",
+  "author": "Ereo Team",
+  "homepage": "https://ereo.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ereojs/ereo.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/ereojs/ereo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target browser --external @ereo/core --external react --external react-dom && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "dev": "bun build ./src/index.ts --outdir ./dist --target browser --watch",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ereo/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}