@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.80

package/src/search-params/analyze.ts

@@ -1,192 +0,0 @@
-/**
- * Static analyzability checker for search-params.ts files.
- *
- * Validates that a search-params.ts file's default export is statically
- * analyzable — a createSearchParams() call or a chain of .extend()/.pick()
- * calls on a SearchParamsDefinition.
- *
- * Non-analyzable files produce a hard build error with a diagnostic.
- *
- * Design doc: design/09-typescript.md §"Static Analyzability"
- */
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Result of analyzing a search-params.ts file. */
-export interface AnalyzeResult {
-  /** Whether the file is statically analyzable. */
-  valid: boolean;
-  /** Error details when valid is false. */
-  error?: AnalyzeError;
-}
-
-/** Diagnostic error for non-analyzable search-params.ts. */
-export interface AnalyzeError {
-  /** Absolute file path. */
-  filePath: string;
-  /** Description of the non-analyzable expression. */
-  expression: string;
-  /** Suggested fix. */
-  suggestion: string;
-}
-
-// ---------------------------------------------------------------------------
-// AST-free source analysis
-//
-// We use a lightweight regex-based approach to validate the structure of the
-// default export. This avoids requiring a TypeScript compiler instance at
-// build time for the initial validation pass. The full type extraction
-// (reading T from SearchParamsDefinition<T>) still happens via the TypeScript
-// compiler in the codegen step — this module just validates the *shape*.
-// ---------------------------------------------------------------------------
-
-/**
- * Patterns that indicate a valid default export:
- *
- * 1. `export default createSearchParams(...)`
- * 2. `export default someVar.extend(...)`
- * 3. `export default someVar.pick(...)`
- * 4. `export default someVar.extend(...).extend(...)`  (chained)
- * 5. `export default someVar.extend(...).pick(...)`    (chained)
- * 6. `export default createSearchParams(...).extend(...)`
- *
- * Invalid patterns:
- * - `export default someFunction(...)` (arbitrary factory)
- * - `export default condition ? a : b` (runtime conditional)
- * - `export default variable` (opaque reference without call)
- */
-
-/**
- * Analyze a search-params.ts file source for static analyzability.
- *
- * @param source - The file content as a string
- * @param filePath - Absolute path to the file (for diagnostics)
- */
-export function analyzeSearchParams(source: string, filePath: string): AnalyzeResult {
-  // Strip comments to avoid false matches
-  const stripped = stripComments(source);
-
-  // Find the default export
-  const defaultExport = extractDefaultExport(stripped);
-
-  if (!defaultExport) {
-    return {
-      valid: false,
-      error: {
-        filePath,
-        expression: '(no default export found)',
-        suggestion:
-          'search-params.ts must have a default export. Use: export default createSearchParams({ ... })',
-      },
-    };
-  }
-
-  // Validate the expression
-  if (isValidExpression(defaultExport.trim())) {
-    return { valid: true };
-  }
-
-  return {
-    valid: false,
-    error: {
-      filePath,
-      expression: defaultExport.trim(),
-      suggestion:
-        'The default export must be a createSearchParams() call, or a chain of ' +
-        '.extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory ' +
-        'functions and runtime conditionals are not supported.',
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/** Strip single-line and multi-line comments from source. */
-function stripComments(source: string): string {
-  // Remove multi-line comments
-  let result = source.replace(/\/\*[\s\S]*?\*\//g, '');
-  // Remove single-line comments
-  result = result.replace(/\/\/.*$/gm, '');
-  return result;
-}
-
-/**
- * Extract the expression from `export default <expr>`.
- *
- * Handles both:
- *   export default createSearchParams(...)
- *   export default expr\n (terminated by newline or semicolon before next statement)
- */
-function extractDefaultExport(source: string): string | undefined {
-  // Match `export default` followed by the expression
-  const match = source.match(
-    /export\s+default\s+([\s\S]+?)(?:;|\n(?=export|import|const|let|var|function|class|type|interface|declare))/
-  );
-  if (match) {
-    return match[1];
-  }
-
-  // Fallback: match everything after `export default` to end of file
-  const fallback = source.match(/export\s+default\s+([\s\S]+)$/);
-  if (fallback) {
-    return fallback[1].replace(/;\s*$/, '');
-  }
-
-  return undefined;
-}
-
-/**
- * Check if an expression is a valid statically-analyzable pattern.
- *
- * Valid patterns:
- * - Starts with `createSearchParams(`
- * - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)
- * - A variable identifier followed by chaining
- */
-function isValidExpression(expr: string): boolean {
-  // Normalize whitespace
-  const normalized = expr.replace(/\s+/g, ' ').trim();
-
-  // Pattern 1: starts with createSearchParams(
-  if (normalized.startsWith('createSearchParams(')) {
-    return true;
-  }
-
-  // Pattern 2: chain ending with .extend(...) or .pick(...)
-  // This covers: someVar.extend(...), createSearchParams(...).extend(...).pick(...), etc.
-  if (/\.(extend|pick)\s*\(/.test(normalized)) {
-    // Reject ternaries and other conditional patterns
-    if (/\?/.test(normalized) && /:/.test(normalized)) {
-      return false;
-    }
-    // Reject function declarations/expressions
-    if (/^\s*(function|=>|\()/.test(normalized)) {
-      return false;
-    }
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Format an AnalyzeError into a human-readable build error message.
- */
-export function formatAnalyzeError(error: AnalyzeError): string {
-  return [
-    `[timber] Non-analyzable search-params.ts`,
-    ``,
-    `  File: ${error.filePath}`,
-    `  Expression: ${error.expression}`,
-    ``,
-    `  ${error.suggestion}`,
-    ``,
-    `  The framework must be able to statically extract the type from your`,
-    `  search-params.ts at build time. Dynamic values, conditionals, and`,
-    `  arbitrary factory functions prevent this analysis.`,
-  ].join('\n');
-}

package/src/search-params/builtin-codecs.ts

@@ -1,228 +0,0 @@
-/**
- * Built-in search param codecs for common types.
- *
- * These provide zero-dependency alternatives to nuqs parsers for the most
- * common cases: strings, integers, floats, booleans, and string enums.
- *
- * All codecs implement SearchParamCodec<T | null> — returning null when the
- * param is absent or unparseable. Use withDefault() to replace null with a
- * concrete fallback value.
- *
- * Design doc: design/23-search-params.md §"Identified Gaps" #1
- * Task: TIM-362
- */
-
-import type { SearchParamCodec } from './create.js';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Normalize array inputs to a single string (last value wins, matching
- * URLSearchParams.get() semantics). Returns undefined if absent or empty.
- */
-function normalizeInput(value: string | string[] | undefined): string | undefined {
-  if (Array.isArray(value)) {
-    return value.length > 0 ? value[value.length - 1] : undefined;
-  }
-  return value;
-}
-
-// ---------------------------------------------------------------------------
-// parseAsString
-// ---------------------------------------------------------------------------
-
-/**
- * String codec. Returns the raw string value, or null if absent.
- *
- * ```ts
- * import { parseAsString } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ q: parseAsString })
- * // ?q=shoes → { q: 'shoes' }
- * // (absent) → { q: null }
- * ```
- */
-export const parseAsString: SearchParamCodec<string | null> = {
-  parse(value: string | string[] | undefined): string | null {
-    const v = normalizeInput(value);
-    return v !== undefined ? v : null;
-  },
-  serialize(value: string | null): string | null {
-    return value;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsInteger
-// ---------------------------------------------------------------------------
-
-/**
- * Integer codec. Parses a base-10 integer, or returns null if absent or
- * not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.
- *
- * ```ts
- * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })
- * // ?page=2 → { page: 2 }
- * // ?page=abc → { page: 1 }
- * // (absent) → { page: 1 }
- * ```
- */
-export const parseAsInteger: SearchParamCodec<number | null> = {
-  parse(value: string | string[] | undefined): number | null {
-    const v = normalizeInput(value);
-    if (v === undefined || v === '') return null;
-    const n = Number(v);
-    if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
-    return n;
-  },
-  serialize(value: number | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsFloat
-// ---------------------------------------------------------------------------
-
-/**
- * Float codec. Parses a finite number, or returns null if absent or invalid.
- * Rejects NaN and Infinity.
- *
- * ```ts
- * import { parseAsFloat, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })
- * ```
- */
-export const parseAsFloat: SearchParamCodec<number | null> = {
-  parse(value: string | string[] | undefined): number | null {
-    const v = normalizeInput(value);
-    if (v === undefined || v === '') return null;
-    const n = Number(v);
-    if (!Number.isFinite(n)) return null;
-    return n;
-  },
-  serialize(value: number | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsBoolean
-// ---------------------------------------------------------------------------
-
-/**
- * Boolean codec. Accepts "true"/"1" as true, "false"/"0" as false.
- * Returns null for absent or unrecognized values.
- *
- * ```ts
- * import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })
- * // ?debug=true → { debug: true }
- * // ?debug=0 → { debug: false }
- * ```
- */
-export const parseAsBoolean: SearchParamCodec<boolean | null> = {
-  parse(value: string | string[] | undefined): boolean | null {
-    const v = normalizeInput(value);
-    if (v === undefined) return null;
-    if (v === 'true' || v === '1') return true;
-    if (v === 'false' || v === '0') return false;
-    return null;
-  },
-  serialize(value: boolean | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsStringEnum
-// ---------------------------------------------------------------------------
-
-/**
- * String enum codec. Accepts only values in the provided list.
- * Returns null for absent or invalid values.
- *
- * ```ts
- * import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'
- *
- * const sortCodec = withDefault(
- *   parseAsStringEnum(['price', 'name', 'date']),
- *   'date'
- * )
- * ```
- */
-export function parseAsStringEnum<T extends string>(
-  values: readonly T[]
-): SearchParamCodec<T | null> {
-  const allowed = new Set<string>(values);
-  return {
-    parse(value: string | string[] | undefined): T | null {
-      const v = normalizeInput(value);
-      if (v === undefined) return null;
-      return allowed.has(v) ? (v as T) : null;
-    },
-    serialize(value: T | null): string | null {
-      return value;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// parseAsStringLiteral
-// ---------------------------------------------------------------------------
-
-/**
- * String literal codec. Functionally identical to parseAsStringEnum but
- * accepts `as const` tuples for narrower type inference.
- *
- * ```ts
- * import { parseAsStringLiteral } from '@timber-js/app/search-params'
- *
- * const sizes = ['sm', 'md', 'lg', 'xl'] as const
- * const codec = parseAsStringLiteral(sizes)
- * // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>
- * ```
- */
-export function parseAsStringLiteral<const T extends readonly string[]>(
-  values: T
-): SearchParamCodec<T[number] | null> {
-  // Delegates to parseAsStringEnum — same runtime behavior, different type
-  return parseAsStringEnum<T[number]>(values);
-}
-
-// ---------------------------------------------------------------------------
-// withDefault
-// ---------------------------------------------------------------------------
-
-/**
- * Wrap a nullable codec with a default value. When the inner codec returns
- * null, the default is used instead. The output type becomes non-nullable.
- *
- * ```ts
- * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
- *
- * const page = withDefault(parseAsInteger, 1)
- * // page.parse(undefined) → 1 (not null)
- * // page.parse('5') → 5
- * ```
- */
-export function withDefault<T>(
-  codec: SearchParamCodec<T | null>,
-  defaultValue: T
-): SearchParamCodec<T> {
-  return {
-    parse(value: string | string[] | undefined): T {
-      const result = codec.parse(value);
-      return result === null ? defaultValue : result;
-    },
-    serialize(value: T): string | null {
-      return codec.serialize(value);
-    },
-  };
-}