@mindees/router 0.1.0

package/dist/search.js

@@ -0,0 +1,112 @@
+import { RouterError } from "./errors.js";
+//#region src/search.ts
+/**
+* Search (query) params — parsing, serializing, and **typed, validated** access.
+*
+* Search params are first-class typed state in Quantum. A route declares a
+* {@link StandardSchemaV1} schema; reads are validated and fully typed via
+* {@link StandardSchemaV1.InferOutput}. This is the capability Expo Router and
+* React Router lack (they return raw, untyped strings). See ADR-0003.
+*
+* Conventions:
+* - repeated keys (`?tag=a&tag=b`) parse to a `string[]`; single keys to a `string`;
+* - coercion (string → number/boolean/date) is delegated to the schema
+*   (e.g. `z.coerce.number()`), so this module never guesses types.
+*
+* @module
+*/
+/**
+* Parse a query string into a record. Accepts an optional leading `?`. Repeated
+* keys collapse into an array, preserving order.
+*
+* @example
+* parseQuery('?page=2&tag=a&tag=b') // { page: '2', tag: ['a', 'b'] }
+*/
+function parseQuery(search) {
+	const out = Object.create(null);
+	const query = search.startsWith("?") ? search.slice(1) : search;
+	if (query.length === 0) return out;
+	for (const pair of query.split("&")) {
+		if (pair.length === 0) continue;
+		const eq = pair.indexOf("=");
+		const rawKey = eq === -1 ? pair : pair.slice(0, eq);
+		const rawValue = eq === -1 ? "" : pair.slice(eq + 1);
+		const key = safeDecode(rawKey);
+		const value = safeDecode(rawValue);
+		const existing = out[key];
+		if (existing === void 0) out[key] = value;
+		else if (Array.isArray(existing)) existing.push(value);
+		else out[key] = [existing, value];
+	}
+	return out;
+}
+/**
+* Serialize a record into a query string (no leading `?`). `null`/`undefined`
+* values are skipped; arrays emit one `key=value` pair each. Keys are sorted for
+* deterministic, cache-friendly output.
+*
+* @example
+* stringifyQuery({ page: 2, tag: ['a', 'b'] }) // 'page=2&tag=a&tag=b'
+*/
+function stringifyQuery(query) {
+	const parts = [];
+	for (const key of Object.keys(query).sort()) {
+		const value = query[key];
+		if (value === null || value === void 0) continue;
+		const encKey = encodeURIComponent(key);
+		if (Array.isArray(value)) for (const item of value) parts.push(`${encKey}=${encodeURIComponent(String(item))}`);
+		else parts.push(`${encKey}=${encodeURIComponent(String(value))}`);
+	}
+	return parts.join("&");
+}
+/**
+* Validate `input` against a Standard Schema, **without throwing** on invalid
+* input — returns a discriminated result. Throws {@link RouterError}
+* (`ASYNC_SCHEMA`) only for the programming error of passing an async schema,
+* since navigation-time parsing must be synchronous.
+*/
+function safeValidateSearch(schema, input) {
+	const result = schema["~standard"].validate(input);
+	if (result instanceof Promise) throw new RouterError("ASYNC_SCHEMA", "Asynchronous schemas are not supported for synchronous search-param validation.");
+	if (result.issues) return {
+		ok: false,
+		issues: result.issues
+	};
+	return {
+		ok: true,
+		value: result.value
+	};
+}
+/**
+* Validate `input` against a Standard Schema, returning the typed output or
+* throwing {@link RouterError} (`VALIDATE_SEARCH` with the issues, or
+* `ASYNC_SCHEMA`).
+*
+* @example
+* const schema = z.object({ page: z.coerce.number() }) // Zod, Valibot, ArkType…
+* validateSearch(schema, { page: '2' }) // { page: 2 }
+*/
+function validateSearch(schema, input) {
+	const result = safeValidateSearch(schema, input);
+	if (!result.ok) throw new RouterError("VALIDATE_SEARCH", formatIssues(result.issues), result.issues);
+	return result.value;
+}
+/** Render Standard Schema issues into a single readable message. */
+function formatIssues(issues) {
+	return `Search validation failed: ${issues.map((issue) => {
+		const path = issue.path?.map((seg) => typeof seg === "object" ? seg.key : seg).join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ")}`;
+}
+/** Decode a URI component, falling back to the raw value on malformed input. */
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value.replace(/\+/g, " "));
+	} catch {
+		return value;
+	}
+}
+//#endregion
+export { parseQuery, safeValidateSearch, stringifyQuery, validateSearch };
+
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","names":[],"sources":["../src/search.ts"],"sourcesContent":["/**\n * Search (query) params — parsing, serializing, and **typed, validated** access.\n *\n * Search params are first-class typed state in Quantum. A route declares a\n * {@link StandardSchemaV1} schema; reads are validated and fully typed via\n * {@link StandardSchemaV1.InferOutput}. This is the capability Expo Router and\n * React Router lack (they return raw, untyped strings). See ADR-0003.\n *\n * Conventions:\n * - repeated keys (`?tag=a&tag=b`) parse to a `string[]`; single keys to a `string`;\n * - coercion (string → number/boolean/date) is delegated to the schema\n *   (e.g. `z.coerce.number()`), so this module never guesses types.\n *\n * @module\n */\n\nimport { RouterError } from './errors'\nimport type { StandardSchemaV1 } from './standard-schema'\n\n/** A value accepted when serializing a query string. */\nexport type QueryValue =\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | ReadonlyArray<string | number | boolean>\n\n/**\n * Parse a query string into a record. Accepts an optional leading `?`. Repeated\n * keys collapse into an array, preserving order.\n *\n * @example\n * parseQuery('?page=2&tag=a&tag=b') // { page: '2', tag: ['a', 'b'] }\n */\nexport function parseQuery(search: string): Record<string, string | string[]> {\n  // Null-prototype accumulator: a normal `{}` inherits Object.prototype, so a key\n  // like `constructor`/`toString`/`__proto__` would resolve to a builtin on the\n  // `out[key]` existence probe (leaking a function into a bogus array) or hit the\n  // `__proto__` setter (mutating the result's prototype). With no prototype, every\n  // key — including those — is an ordinary absent-then-own data property.\n  const out: Record<string, string | string[]> = Object.create(null)\n  const query = search.startsWith('?') ? search.slice(1) : search\n  if (query.length === 0) return out\n\n  for (const pair of query.split('&')) {\n    if (pair.length === 0) continue\n    const eq = pair.indexOf('=')\n    const rawKey = eq === -1 ? pair : pair.slice(0, eq)\n    const rawValue = eq === -1 ? '' : pair.slice(eq + 1)\n    const key = safeDecode(rawKey)\n    const value = safeDecode(rawValue)\n\n    const existing = out[key]\n    if (existing === undefined) {\n      out[key] = value\n    } else if (Array.isArray(existing)) {\n      existing.push(value)\n    } else {\n      out[key] = [existing, value]\n    }\n  }\n  return out\n}\n\n/**\n * Serialize a record into a query string (no leading `?`). `null`/`undefined`\n * values are skipped; arrays emit one `key=value` pair each. Keys are sorted for\n * deterministic, cache-friendly output.\n *\n * @example\n * stringifyQuery({ page: 2, tag: ['a', 'b'] }) // 'page=2&tag=a&tag=b'\n */\nexport function stringifyQuery(query: Record<string, QueryValue>): string {\n  const parts: string[] = []\n  for (const key of Object.keys(query).sort()) {\n    const value = query[key]\n    if (value === null || value === undefined) continue\n    const encKey = encodeURIComponent(key)\n    if (Array.isArray(value)) {\n      for (const item of value) parts.push(`${encKey}=${encodeURIComponent(String(item))}`)\n    } else {\n      parts.push(`${encKey}=${encodeURIComponent(String(value))}`)\n    }\n  }\n  return parts.join('&')\n}\n\n/** The result of a non-throwing validation. */\nexport type ValidationResult<T> =\n  | { readonly ok: true; readonly value: T }\n  | { readonly ok: false; readonly issues: ReadonlyArray<StandardSchemaV1.Issue> }\n\n/**\n * Validate `input` against a Standard Schema, **without throwing** on invalid\n * input — returns a discriminated result. Throws {@link RouterError}\n * (`ASYNC_SCHEMA`) only for the programming error of passing an async schema,\n * since navigation-time parsing must be synchronous.\n */\nexport function safeValidateSearch<S extends StandardSchemaV1>(\n  schema: S,\n  input: unknown,\n): ValidationResult<StandardSchemaV1.InferOutput<S>> {\n  const result = schema['~standard'].validate(input)\n  if (result instanceof Promise) {\n    throw new RouterError(\n      'ASYNC_SCHEMA',\n      'Asynchronous schemas are not supported for synchronous search-param validation.',\n    )\n  }\n  // Discriminate on `issues` (truthiness): a schema may legitimately yield a\n  // success value of `undefined`, so `value` is not a reliable discriminant.\n  if (result.issues) {\n    return { ok: false, issues: result.issues }\n  }\n  return { ok: true, value: result.value }\n}\n\n/**\n * Validate `input` against a Standard Schema, returning the typed output or\n * throwing {@link RouterError} (`VALIDATE_SEARCH` with the issues, or\n * `ASYNC_SCHEMA`).\n *\n * @example\n * const schema = z.object({ page: z.coerce.number() }) // Zod, Valibot, ArkType…\n * validateSearch(schema, { page: '2' }) // { page: 2 }\n */\nexport function validateSearch<S extends StandardSchemaV1>(\n  schema: S,\n  input: unknown,\n): StandardSchemaV1.InferOutput<S> {\n  const result = safeValidateSearch(schema, input)\n  if (!result.ok) {\n    throw new RouterError('VALIDATE_SEARCH', formatIssues(result.issues), result.issues)\n  }\n  return result.value\n}\n\n/** Render Standard Schema issues into a single readable message. */\nfunction formatIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string {\n  const lines = issues.map((issue) => {\n    const path = issue.path?.map((seg) => (typeof seg === 'object' ? seg.key : seg)).join('.')\n    return path ? `${path}: ${issue.message}` : issue.message\n  })\n  return `Search validation failed: ${lines.join('; ')}`\n}\n\n/** Decode a URI component, falling back to the raw value on malformed input. */\nfunction safeDecode(value: string): string {\n  try {\n    return decodeURIComponent(value.replace(/\\+/g, ' '))\n  } catch {\n    return value\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,WAAW,QAAmD;CAM5E,MAAM,MAAyC,OAAO,OAAO,IAAI;CACjE,MAAM,QAAQ,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI;CACzD,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,KAAK,MAAM,QAAQ,MAAM,MAAM,GAAG,GAAG;EACnC,IAAI,KAAK,WAAW,GAAG;EACvB,MAAM,KAAK,KAAK,QAAQ,GAAG;EAC3B,MAAM,SAAS,OAAO,KAAK,OAAO,KAAK,MAAM,GAAG,EAAE;EAClD,MAAM,WAAW,OAAO,KAAK,KAAK,KAAK,MAAM,KAAK,CAAC;EACnD,MAAM,MAAM,WAAW,MAAM;EAC7B,MAAM,QAAQ,WAAW,QAAQ;EAEjC,MAAM,WAAW,IAAI;EACrB,IAAI,aAAa,KAAA,GACf,IAAI,OAAO;OACN,IAAI,MAAM,QAAQ,QAAQ,GAC/B,SAAS,KAAK,KAAK;OAEnB,IAAI,OAAO,CAAC,UAAU,KAAK;CAE/B;CACA,OAAO;AACT;;;;;;;;;AAUA,SAAgB,eAAe,OAA2C;CACxE,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,EAAE,KAAK,GAAG;EAC3C,MAAM,QAAQ,MAAM;EACpB,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW;EAC3C,MAAM,SAAS,mBAAmB,GAAG;EACrC,IAAI,MAAM,QAAQ,KAAK,GACrB,KAAK,MAAM,QAAQ,OAAO,MAAM,KAAK,GAAG,OAAO,GAAG,mBAAmB,OAAO,IAAI,CAAC,GAAG;OAEpF,MAAM,KAAK,GAAG,OAAO,GAAG,mBAAmB,OAAO,KAAK,CAAC,GAAG;CAE/D;CACA,OAAO,MAAM,KAAK,GAAG;AACvB;;;;;;;AAaA,SAAgB,mBACd,QACA,OACmD;CACnD,MAAM,SAAS,OAAO,aAAa,SAAS,KAAK;CACjD,IAAI,kBAAkB,SACpB,MAAM,IAAI,YACR,gBACA,iFACF;CAIF,IAAI,OAAO,QACT,OAAO;EAAE,IAAI;EAAO,QAAQ,OAAO;CAAO;CAE5C,OAAO;EAAE,IAAI;EAAM,OAAO,OAAO;CAAM;AACzC;;;;;;;;;;AAWA,SAAgB,eACd,QACA,OACiC;CACjC,MAAM,SAAS,mBAAmB,QAAQ,KAAK;CAC/C,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,YAAY,mBAAmB,aAAa,OAAO,MAAM,GAAG,OAAO,MAAM;CAErF,OAAO,OAAO;AAChB;;AAGA,SAAS,aAAa,QAAuD;CAK3E,OAAO,6BAJO,OAAO,KAAK,UAAU;EAClC,MAAM,OAAO,MAAM,MAAM,KAAK,QAAS,OAAO,QAAQ,WAAW,IAAI,MAAM,GAAI,EAAE,KAAK,GAAG;EACzF,OAAO,OAAO,GAAG,KAAK,IAAI,MAAM,YAAY,MAAM;CACpD,CACwC,EAAE,KAAK,IAAI;AACrD;;AAGA,SAAS,WAAW,OAAuB;CACzC,IAAI;EACF,OAAO,mBAAmB,MAAM,QAAQ,OAAO,GAAG,CAAC;CACrD,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/standard-schema.d.ts

@@ -0,0 +1,90 @@
+//#region src/standard-schema.d.ts
+/**
+ * Standard Schema — the validator-agnostic interface (types only, vendored).
+ *
+ * Quantum validates search/route params through {@link StandardSchemaV1}, the
+ * common interface co-designed by the authors of Zod, Valibot, and ArkType. Any
+ * compliant validator (Zod ≥ 3.24 / all of 4.x, Valibot ≥ 1, ArkType ≥ 2, and
+ * 20+ others) exposes a `~standard` property and is accepted **directly** — no
+ * per-library adapters, no lock-in.
+ *
+ * These ~60 lines are **vendored on purpose** (the spec FAQ explicitly blesses
+ * copy/paste; the project guarantees no breaking change without a major version
+ * bump). Vendoring means `@mindees/router` takes **zero runtime dependency** to
+ * support every validator — the "batteries included, dependencies excluded"
+ * doctrine.
+ *
+ * This is the spec's **v1 validation interface** (`StandardSchemaV1`). `validate`
+ * is typed single-argument — the subset Quantum needs; a spec 1.1.0 validator's
+ * optional second `options` argument remains assignable (fewer-params rule), so
+ * Zod 4 / Valibot 1 / ArkType 2 schemas are accepted directly.
+ *
+ * Portions adapted from `@standard-schema/spec`, MIT License,
+ * Copyright (c) 2024 Colin McDonnell. Permission is hereby granted, free of
+ * charge, to any person obtaining a copy of this software and associated
+ * documentation files, to deal in the Software without restriction. The above
+ * copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * @see https://standardschema.dev
+ * @see https://github.com/standard-schema/standard-schema
+ * @module
+ */
+/** A schema that conforms to the Standard Schema specification. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. May be synchronous or asynchronous. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema (present only at the type level). */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard Schema types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Schema. */
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+  /** Infers the output type of a Standard Schema. */
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+//#endregion
+export { StandardSchemaV1 };
+//# sourceMappingURL=standard-schema.d.ts.map

package/dist/standard-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.d.ts","names":[],"sources":["../src/standard-schema.ts"],"mappings":";;AAiCA;;;;;;;;;;;;;;;;;;AAE4D;AAG5D;;;;;;;;;;;;UALiB,gBAAA,2BAA2C,KAAA;EAmB7B;EAAA,SAjBpB,WAAA,EAAa,gBAAA,CAAiB,KAAA,CAAM,KAAA,EAAO,MAAA;AAAA;AAAA,kBAGrC,gBAAA;EA2BI;EAAA,UAzBF,KAAA,2BAAgC,KAAA;IAiCH;IAAA,SA/BnC,OAAA;IAqCK;IAAA,SAnCL,MAAA;IAyCO;IAAA,SAvCP,QAAA,GAAW,KAAA,cAAmB,MAAA,CAAO,MAAA,IAAU,OAAA,CAAQ,MAAA,CAAO,MAAA;IA6CnC;IAAA,SA3C3B,KAAA,GAAQ,KAAA,CAAM,KAAA,EAAO,MAAA;EAAA;EAgDO;EAAA,KA5C3B,MAAA,WAAiB,aAAA,CAAc,MAAA,IAAU,aAAA;EA4CM;EAAA,UAzC1C,aAAA;IAyCqD;IAAA,SAvC3D,KAAA,EAAO,MAAA;IAjBK;IAAA,SAmBZ,MAAA;EAAA;EAjBA;EAAA,UAqBM,aAAA;IAjBN;IAAA,SAmBA,MAAA,EAAQ,aAAA,CAAc,KAAA;EAAA;EAnBe;EAAA,UAuB/B,KAAA;IAvBiD;IAAA,SAyBvD,OAAA;IAvBA;IAAA,SAyBA,IAAA,GAAO,aAAA,CAAc,WAAA,GAAc,WAAA;EAAA;EAzBd;EAAA,UA6Bf,WAAA;IAzBE;IAAA,SA2BR,GAAA,EAAK,WAAA;EAAA;EA3BqC;EAAA,UA+BpC,KAAA,2BAAgC,KAAA;IA5BlB;IAAA,SA8BpB,KAAA,EAAO,KAAA;IA5BA;IAAA,SA8BP,MAAA,EAAQ,MAAA;EAAA;EAtBR;EAAA,KA0BC,UAAA,gBAA0B,gBAAA,IAAoB,WAAA,CACxD,MAAA;EA3B+B;EAAA,KA+BrB,WAAA,gBAA2B,gBAAA,IAAoB,WAAA,CACzD,MAAA;AAAA"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mindees/router",
+  "version": "0.1.0",
+  "description": "Quantum — the typed, signals-native router for MindeesNative: codegen-free typed path params, Standard Schema validated search params, and selector-isolated reactive route state.",
+  "keywords": [
+    "router",
+    "typed-router",
+    "type-safe-routing",
+    "typescript",
+    "signals",
+    "standard-schema",
+    "search-params",
+    "cross-platform",
+    "react-native-alternative",
+    "expo-router-alternative"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindees/mindees.git",
+    "directory": "packages/router"
+  },
+  "dependencies": {
+    "@mindees/core": "0.1.0"
+  },
+  "devDependencies": {
+    "happy-dom": "20.9.0",
+    "valibot": "1.4.1",
+    "zod": "4.4.3",
+    "@mindees/renderer": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}