@lovrozagar/flare 0.4.2 → 0.5.0

package/README.md

@@ -321,7 +321,7 @@ Chain order (typical): `intercept` → `cache` → `authenticate` → `input`
 | Method                                                                                        | Role                                                             |
 | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | `.cache(config)`                                                                              | Client / SSR / ISR / SSG / CDN                                   |
-| `.authenticate()` / `.authenticate("optional")`                                               | Auth gate                                                        |
+| `.authenticate()` / `.authenticateOptional()`                                                 | Auth gate                                                        |
 | `.authorize(fn)`                                                                              | Role check; inherits parent unless overridden                    |
 | `.input({ params, searchParams })`                                                            | Standard Schema or parse fn                                      |
 | `.effects({ loaderDeps, shouldRefetch })`                                                     | When to rerun the loader on search change                        |
@@ -462,10 +462,9 @@ export const route = createPage("_root_/dashboard")
 ```
 
 - `.authenticate()` — required; null user → `UnauthenticatedError` (401).
-- `.authenticate("optional")` — user may be null; `ctx.auth` is `null` for anonymous requests.
-- Other arguments are callerData for `authenticateFn`: `.authenticate("admin")` is required, `.authenticate("optional", "viewer")` is optional.
+- `.authenticateOptional()` — user may be null; `ctx.auth` is `null` for anonymous requests.
+- The method is the mode. Arguments are only callerData for `authenticateFn`: `.authenticate("admin")` is required, `.authenticateOptional("viewer")` is optional. A leading `"optional"` argument does not compile and throws at definition — use `.authenticateOptional()`.
 - A required layout gates every route below it; a child cannot loosen it.
-- `.authenticateOptional()` is a deprecated alias of `.authenticate("optional")`.
 - `createServer(router).authenticateFn(fn)` is the app-wide hook (cookie, header, JWT).
 
 Throw helpers: `ctx.notFound()`, `ctx.redirect({ to, params, search, status, replace })`, `ctx.unauthenticated()`, `ctx.unauthorized()`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lovrozagar/flare",
-	"version": "0.4.2",
+	"version": "0.5.0",
 	"description": "Solid meta-framework. Server-driven, NDJSON streaming, renderToStream.",
 	"keywords": [
 		"flare",

package/src/generators/index.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync,
 import { dirname, extname, join, posix, relative, resolve } from "node:path";
 import { parse as babelParse } from "@babel/parser";
 import { parseSeconds } from "../duration/index.ts";
-import type { AuthenticateMode } from "../route-builder/types.ts";
+import { AUTHENTICATE_OPTIONAL_ARGUMENT_ERROR, type AuthenticateMode } from "../route-builder/types.ts";
 import { extractLayoutKey } from "../router-primitives/paths.ts";
 
 export type PrefetchStrategy = false | "intent" | "render" | "viewport";
@@ -638,10 +638,15 @@ function relativeImportPath(from: string, to: string): string {
 	return `${prefix}/${downs.join("/")}`;
 }
 
-/** Auth mode of a builder chain; mirrors `resolveAuthenticateArgs` in the route builder. */
+/**
+ * Auth mode of a builder chain. The mode is the method name, so this never evaluates an argument; the removed
+ * `.authenticate("optional")` form fails codegen the same way `assertCallerData` fails the builder.
+ */
 export function detectAuthenticateMode(chainText: string): AuthenticateMode {
+	if (/\.authenticate\s*\(\s*(["'`])optional\1\s*[,)]/.test(chainText)) {
+		throw new Error(AUTHENTICATE_OPTIONAL_ARGUMENT_ERROR);
+	}
 	if (/\.authenticateOptional\s*\(/.test(chainText)) return "optional";
-	if (/\.authenticate\s*\(\s*(["'`])optional\1\s*[,)]/.test(chainText)) return "optional";
 	return /\.authenticate\s*\(/.test(chainText);
 }
 

package/src/route-builder/create-layout.ts

@@ -12,7 +12,7 @@ import type {
 } from "./register.ts";
 import {
 	type AuthenticateMode,
-	type AuthenticateModeFromArgs,
+	type CallerDataGuard,
 	BUILDER_MARKER,
 	type CacheConfig,
 	type DeferFn,
@@ -26,7 +26,7 @@ import {
 	type SearchParamsValidator,
 	type ServerThrowHelpers,
 	type ServerUrlHelpers,
-	resolveAuthenticateArgs,
+	assertCallerData,
 } from "./types.ts";
 
 /* ── callback context types ─────────────────────────────────────── */
@@ -317,11 +317,11 @@ interface LayoutBuilderAfterInput<
 	TAuth extends AuthenticateMode,
 	TPreloaderContext,
 > extends LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
-	/** Required by default; `.authenticate("optional")` lets anonymous requests through with `ctx.auth === null`. Other arguments are callerData for `authenticateFn`. */
+	/** Requires a user; anonymous requests get the unauthenticated boundary. Arguments are callerData for `authenticateFn`. */
 	authenticate<const TArgs extends readonly unknown[]>(
-		...args: TArgs
-	): LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>, TPreloaderContext>;
-	/** @deprecated Use `.authenticate("optional", ...callerData)`. */
+		...args: TArgs & CallerDataGuard<TArgs>
+	): LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>;
+	/** Lets anonymous requests through with `ctx.auth === null`. Arguments are callerData for `authenticateFn`. */
 	authenticateOptional(
 		...args: unknown[]
 	): LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>;
@@ -607,14 +607,12 @@ function createBuilderAfterInput<
 >(state: BuilderStateInternal): LayoutBuilderAfterInput<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
 	return {
 		...createBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext>(state),
-		authenticate<const TArgs extends readonly unknown[]>(...args: TArgs) {
-			return createBuilderAfterAuthenticate<
-				TPath,
-				TParams,
-				TSearch,
-				AuthenticateModeFromArgs<TArgs>,
-				TPreloaderContext
-			>({ ...state, ...resolveAuthenticateArgs(args) });
+		authenticate(...args: readonly unknown[]) {
+			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>({
+				...state,
+				authenticate: assertCallerData(args),
+				authenticateMode: true,
+			});
 		},
 		authenticateOptional(...args: unknown[]) {
 			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>({

package/src/route-builder/create-page.ts

@@ -11,7 +11,7 @@ import type {
 } from "./register.ts";
 import {
 	type AuthenticateMode,
-	type AuthenticateModeFromArgs,
+	type CallerDataGuard,
 	BUILDER_MARKER,
 	type CacheConfig,
 	type DeferFn,
@@ -25,7 +25,7 @@ import {
 	type SearchParamsValidator,
 	type ServerThrowHelpers,
 	type ServerUrlHelpers,
-	resolveAuthenticateArgs,
+	assertCallerData,
 } from "./types.ts";
 
 /* ── callback context types ─────────────────────────────────────── */
@@ -387,11 +387,11 @@ interface PageBuilderAfterInput<
 	TAuth extends AuthenticateMode,
 	TPreloaderContext,
 > extends PageBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
-	/** Required by default; `.authenticate("optional")` lets anonymous requests through with `ctx.auth === null`. Other arguments are callerData for `authenticateFn`. */
+	/** Requires a user; anonymous requests get the unauthenticated boundary. Arguments are callerData for `authenticateFn`. */
 	authenticate<const TArgs extends readonly unknown[]>(
-		...args: TArgs
-	): PageBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>, TPreloaderContext>;
-	/** @deprecated Use `.authenticate("optional", ...callerData)`. */
+		...args: TArgs & CallerDataGuard<TArgs>
+	): PageBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>;
+	/** Lets anonymous requests through with `ctx.auth === null`. Arguments are callerData for `authenticateFn`. */
 	authenticateOptional(
 		...args: unknown[]
 	): PageBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>;
@@ -732,14 +732,12 @@ function createBuilderAfterInput<
 >(state: BuilderStateInternal): PageBuilderAfterInput<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
 	return {
 		...createBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext>(state),
-		authenticate<const TArgs extends readonly unknown[]>(...args: TArgs) {
-			return createBuilderAfterAuthenticate<
-				TPath,
-				TParams,
-				TSearch,
-				AuthenticateModeFromArgs<TArgs>,
-				TPreloaderContext
-			>({ ...state, ...resolveAuthenticateArgs(args) });
+		authenticate(...args: readonly unknown[]) {
+			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>({
+				...state,
+				authenticate: assertCallerData(args),
+				authenticateMode: true,
+			});
 		},
 		authenticateOptional(...args: unknown[]) {
 			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>({

package/src/route-builder/create-root-layout.ts

@@ -4,7 +4,7 @@ import type { Location } from "../router-primitives/index.ts";
 import type { ResolvedAuth, ResolvedEnv, ResolvedQueryClient, ResolvedServerContext } from "./register.ts";
 import {
 	type AuthenticateMode,
-	type AuthenticateModeFromArgs,
+	type CallerDataGuard,
 	BUILDER_MARKER,
 	type CacheConfig,
 	type DeferFn,
@@ -18,7 +18,7 @@ import {
 	type SearchParamsValidator,
 	type ServerThrowHelpers,
 	type ServerUrlHelpers,
-	resolveAuthenticateArgs,
+	assertCallerData,
 } from "./types.ts";
 
 /* ── callback context types (root-specific) ─────────────────────── */
@@ -304,11 +304,11 @@ interface RootBuilderAfterInput<TPath extends string, TParams, TSearch> extends
 	TSearch,
 	false
 > {
-	/** Required by default; `.authenticate("optional")` lets anonymous requests through with `ctx.auth === null`. Other arguments are callerData for `authenticateFn`. */
+	/** Requires a user; anonymous requests get the unauthenticated boundary. Arguments are callerData for `authenticateFn`. */
 	authenticate<const TArgs extends readonly unknown[]>(
-		...args: TArgs
-	): RootBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>>;
-	/** @deprecated Use `.authenticate("optional", ...callerData)`. */
+		...args: TArgs & CallerDataGuard<TArgs>
+	): RootBuilderAfterAuthenticate<TPath, TParams, TSearch, true>;
+	/** Lets anonymous requests through with `ctx.auth === null`. Arguments are callerData for `authenticateFn`. */
 	authenticateOptional(...args: unknown[]): RootBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional">;
 }
 
@@ -575,10 +575,11 @@ function createBuilderAfterInput<TPath extends string, TParams, TSearch>(
 ): RootBuilderAfterInput<TPath, TParams, TSearch> {
 	return {
 		...createBuilderAfterAuthenticate<TPath, TParams, TSearch, false>(state),
-		authenticate<const TArgs extends readonly unknown[]>(...args: TArgs) {
-			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>>({
+		authenticate(...args: readonly unknown[]) {
+			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, true>({
 				...state,
-				...resolveAuthenticateArgs(args),
+				authenticate: assertCallerData(args),
+				authenticateMode: true,
 			});
 		},
 		authenticateOptional(...args: unknown[]) {

package/src/route-builder/types.ts

@@ -8,22 +8,21 @@ export type { FlareStore, FlareStoreEntry, StaticEntryData };
 
 export type AuthenticateMode = false | "optional" | true;
 
-/** `.authenticate("optional", ...callerData)` is optional; any other argument list is callerData for a required gate. */
-export type AuthenticateModeFromArgs<TArgs extends readonly unknown[]> = TArgs extends readonly [
-	"optional",
-	...unknown[],
-]
-	? "optional"
-	: true;
-
-/** Runtime half of `AuthenticateModeFromArgs`: splits the mode from the callerData forwarded to `authenticateFn`. */
-export function resolveAuthenticateArgs(args: readonly unknown[]): {
-	authenticate: unknown[];
-	authenticateMode: "optional" | true;
-} {
-	return args[0] === "optional"
-		? { authenticate: args.slice(1), authenticateMode: "optional" }
-		: { authenticate: [...args], authenticateMode: true };
+/**
+ * Arguments to `.authenticate()` / `.authenticateOptional()` are callerData for `authenticateFn`; the auth mode is
+ * the method name, never an argument. A leading `"optional"` is the old mode form, which once compiled to a
+ * required route: it does not type-check (`never`), and `assertCallerData` throws at definition.
+ */
+export type CallerDataGuard<TArgs extends readonly unknown[]> = TArgs extends readonly ["optional", ...unknown[]]
+	? never
+	: unknown;
+
+export const AUTHENTICATE_OPTIONAL_ARGUMENT_ERROR =
+	'.authenticate("optional") is not an auth mode: arguments are callerData for authenticateFn. Use .authenticateOptional(...callerData) for optional auth.';
+
+export function assertCallerData(args: readonly unknown[]): unknown[] {
+	if (args[0] === "optional") throw new Error(AUTHENTICATE_OPTIONAL_ARGUMENT_ERROR);
+	return [...args];
 }
 
 /**