route-sprout 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Piotr Siatkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,350 @@
+![Render Slot Image](./image-small.png)
+
+# route-sprout 🌱 (typed API route builder DSL)
+
+[![npm version](https://img.shields.io/npm/v/route-sprout?color=blue)](https://www.npmjs.com/package/route-sprout)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/route-sprout)](https://bundlephobia.com/package/route-sprout)
+[![license](https://img.shields.io/npm/l/route-sprout)](./LICENSE)
+[![Types](https://img.shields.io/badge/TypeScript-ready-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![GitHub stars](https://img.shields.io/github/stars/PiotrSiatkowski/route-sprout?style=social)](https://github.com/PiotrSiatkowski/route-sprout)
+
+A tiny, cute DSL that grows **type-safe, composable URL builders** from a declarative route tree.
+
+- ✅ Strong TypeScript inference from your route definition
+- ✅ Nested resources with `slot('id')` parameters
+- ✅ Optional path gates with `wrap('admin', predicate, …)`
+- ✅ Ad‑hoc conditional segments anywhere with `.when(cond, segments) and join(segments)`
+- ✅ Search params supported (`string` or `URLSearchParams`)
+
+> Think of it as a little route bonsai: you shape the tree once, then pluck URLs from any branch.
+
+---
+
+## Install
+
+```bash
+npm i route-sprout
+# or
+pnpm add route-sprout
+# or
+yarn add route-sprout
+```
+
+## Quick start
+
+```ts
+import { root, path, slot, keep } from "route-sprout";
+
+const Api = root([
+  path("invoices", [
+    keep(),
+    slot("id", [
+      path("price"), 
+      path("customers")
+    ]),
+    path("statistics"),
+  ]),
+]);
+
+Api.invoices();                          // "/invoices"
+Api.invoices("page=1");                  // "/invoices?page=1"
+Api.invoices.id("abc")("a=1");           // "/invoices/abc?a=1"
+Api.invoices.id("abc").customers();      // "/invoices/abc/customers"
+```
+
+---
+
+## Why this exists
+
+When you have lots of endpoints, you usually end up with:
+
+- string concatenation sprinkled everywhere
+- duplicated base paths
+- typos that compile fine and fail at runtime
+- route refactors that turn into treasure hunts
+
+This DSL gives you:
+
+- a single, declarative source of truth
+- fluent, discoverable usage (`Api.invoices.id("x").customers()`)
+- TypeScript autocomplete and type checking from **usage**, not comments
+
+---
+
+## Concepts
+
+### `path(name, children?)`
+
+A **static** path segment.
+
+- `path("invoices")` → `/invoices`
+- Nested paths compose: `path("a", [path("b")])` → `/a/b`
+
+Leaf paths (no children) are callable and return a URL:
+
+```ts
+path("health"); // Api.health() -> "/health"
+```
+
+### `keep()`
+
+Marks a path (or slot/wrap subtree) as **callable** at that position.
+
+```ts
+path("orders", [keep(), path("export")]);
+// Api.orders() -> "/orders"
+// Api.orders.export() -> "/orders/export"
+```
+
+### `slot(name, children?)`
+
+A **parameterized** segment, typically used for IDs.
+
+The `name` is only the **property key**. It is **not** inserted into the path.
+
+```ts
+path("invoices", [slot("id")]);
+// Api.invoices.id("abc")() -> "/invoices/abc"
+```
+
+With children:
+
+```ts
+path("invoices", [
+  slot("id", [
+    path("price"), 
+    path("customers")
+  ]),
+]);
+
+// Api.invoices.id("abc").customers() -> "/invoices/abc/customers"
+```
+
+### `wrap(name, predicate, children?)`
+
+A conditional segment *defined in the tree*.
+
+If `predicate(arg)` is `true`, `name` becomes a real path segment.
+If `false`, it’s a pass-through (does not change the path).
+
+```ts
+type User = { isAdmin: boolean } | null;
+
+path("core", [
+  wrap("admin", (u: User) => !!u?.isAdmin, [
+    path("invoices", [keep()]),
+  ]),
+]);
+
+Api.core.admin({ isAdmin: true }).invoices();  // "/core/admin/invoices"
+Api.core.admin({ isAdmin: false }).invoices(); // "/core/invoices"
+```
+
+> `wrap` is ideal for *well-known*, reusable gates: `admin`, `v2`, `tenant`, etc.
+
+### `.when(cond, segment | segment[])`
+
+Ad‑hoc conditional segment insertion at **runtime**, anywhere in the chain.
+
+```ts
+Api.core.when(isAdmin, "admin").invoices();
+Api.core.when(true, ["tenant", tenantId]).invoices();
+Api.invoices.id("abc").when(flags.preview, "preview").activities();
+```
+
+- `cond = false` → no-op
+- `segment` can be a single segment or an array of segments
+- empty segments are ignored (your `url()` filters them out)
+
+> `.when()` is ideal when you don’t want to bake a wrapper into the route tree.
+
+---
+
+## Search params
+
+All callable endpoints accept an optional `search` parameter:
+
+- `string` (already encoded)
+- `URLSearchParams` (will be coerced to string via template interpolation)
+- `object` (will be coerced into URLSearchParams)
+
+```ts
+Api.invoices("page=2&size=25");
+
+const sp = new URLSearchParams({ page: "2", size: "25" });
+Api.invoices(sp);
+```
+
+---
+
+## Full example
+
+```ts
+import { root, path, slot, keep, wrap } from "route-sprout";
+
+type PortalUser = { isAdmin?: boolean } | null;
+
+export const Api = root([
+  path("core", [
+    wrap("admin", (u: PortalUser) => !!u?.isAdmin, [
+      path("invoices", [
+        keep()
+      ]),
+      path("customers", [
+        slot("id"), 
+        keep()
+      ]),
+    ]),
+  ]),
+  path("invoices", [
+    keep(),
+    slot("id", [
+      path("price"), 
+      path("customers")
+    ]),
+    path("statistics"),
+  ]),
+]);
+
+// usage
+Api.invoices(); // "/invoices"
+Api.invoices.id("123").customers(); // "/invoices/123/customers"
+
+// runtime insert
+Api.core.when(true, "v2").invoices(); // "/core/v2/invoices"
+Api.core.admin({ isAdmin: true }).when(true, "v2").invoices(); // "/core/admin/v2/invoices"
+```
+
+### Autocomplete-friendly patterns
+Because everything is computed from the definition tree, your editor can autocomplete:
+
+- paths (`Api.invoices`, `Api.orders.export`)
+- slots (`Api.invoices.id(…)`)
+- nested children (`…id("x").customers()`)
+
+---
+
+## API reference
+
+### Exports
+
+- `root(defs)`
+- `path(name, rest?)`
+- `slot(name, rest?)`
+- `wrap(name, when, rest?)`
+- `keep()`
+
+### Types
+
+- `Segment = string | number`
+- `SParams = string | URLSearchParams`
+
+---
+
+## Dialects
+
+If you like your DSLs with different “flavors”, route-sprout ships **dialects** as subpath exports.
+Each dialect is the same engine, just different helper names.
+
+Import a dialect like this:
+
+```ts
+import { grow, tree, seed, leaf, nest } from "route-sprout/dialect-tree";
+```
+
+### Available dialects
+
+#### `route-sprout/dialect-path` (default)
+- **root / path / slot / keep / wrap**
+
+```ts
+import { root, path, slot, keep, wrap } from "route-sprout/dialect-path";
+
+const Api = root([
+  path("invoices", [keep(), slot("id")]),
+]);
+
+Api.invoices.id("123")(); // "/invoices/123"
+```
+
+#### `route-sprout/dialect-step`
+- **make / step / item / self / gate**
+
+```ts
+import { make, step, item, self, gate } from "route-sprout/dialect-step";
+
+const Api = make([
+  step("orders", [self(), item("id"), step("export")]),
+]);
+
+Api.orders.export(); // "/orders/export"
+```
+
+#### `route-sprout/dialect-tree`
+- **grow / tree / seed / twig / nest**
+
+```ts
+import { grow, tree, seed, twig, nest } from "route-sprout/dialect-tree";
+
+const Api = grow([
+  tree("core", [
+    nest("admin", (u: { isAdmin?: boolean } | null) => !!u?.isAdmin, [
+      tree("jobs", [twig()]),
+    ]),
+  ]),
+]);
+
+Api.core.admin({ isAdmin: true }).jobs(); // "/core/admin/jobs"
+```
+
+#### `route-sprout/dialect-node`
+- **link / node / bind / base / mask**
+
+```ts
+import { link, node, bind, base, mask } from "route-sprout/dialect-graph";
+
+const Api = link([
+  node("tasks", [base(), bind("id", [node("logs")])]),
+]);
+
+Api.tasks.id("x").logs(); // "/tasks/x/logs"
+```
+
+### Mix-and-match?
+
+Dialects are meant to be **all-in** per codebase/file. Technically you can mix imports, but future-you will sigh loudly.
+
+## Gotchas & design notes
+
+- `slot("id")` uses `"id"` **only as a property name**, not a URL segment.
+  - ✅ `/invoices/123`
+  - ❌ `/invoices/id/123`
+- `.when()` rebuilds a subtree and returns a new object/function.
+  - It does **not** mutate the original branch.
+- Empty segments are ignored in the final URL (because `url()` does `filter()`).
+  - If you want stricter behavior (throw on empty segment), enforce it in your own `.when` wrapper.
+
+---
+
+## Testing
+
+This library is friendly to unit tests because the output is just strings.
+
+Example (Vitest):
+
+```ts
+import { expect, test } from "vitest";
+import { root, path, slot, keep } from "route-sprout";
+
+test("builds routes", () => {
+  const Api = root([path("invoices", [keep(), slot("id")])] as const);
+  expect(Api.invoices()).toBe("/invoices");
+  expect(Api.invoices.id("x")()).toBe("/invoices/x");
+});
+```
+
+---
+
+## License
+
+MIT

package/dist/api.cjs

@@ -0,0 +1,2 @@
+"use strict";var S=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var y=Object.prototype.hasOwnProperty;var g=(n,e)=>{for(var o in e)S(n,o,{get:e[o],enumerable:!0})},k=(n,e,o,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of h(e))!y.call(n,a)&&a!==o&&S(n,a,{get:()=>e[a],enumerable:!(s=u(e,a))||s.enumerable});return n};var D=n=>k(S({},"__esModule",{value:!0}),n);var A={};g(A,{keep:()=>P,path:()=>d,root:()=>x,slot:()=>R,wrap:()=>w});module.exports=D(A);var P=()=>({kind:"keep"}),d=(n,e)=>({kind:"path",name:n,rest:e??[]}),R=(n,e)=>({kind:"slot",name:n,rest:e??[]}),w=(n,e,o)=>({kind:"wrap",name:n,when:e,rest:o??[]}),l=(n,e)=>`${n.filter(Boolean).join("/")}${e?`?${e}`:""}`.replace("//","/");function x(n){return m([],d("/",n))}function m(n,e){let o=t=>t.rest.some(r=>r.kind==="keep"),s=e.kind==="slot"||e.kind==="wrap"?n:e.name?[...n,e.name]:n,a=o(e)?t=>l(s,t):{};for(let t of e.rest)t.kind==="slot"?t.rest.length===0?a[t.name]=r=>i=>l([...s,r],i):a[t.name]=r=>{let i=m([...s,r],t);return Object.assign(o(t)?c=>l([...s,r],c):{},i)}:t.kind==="path"?t.rest.length===0?a[t.name]=r=>l([...s,t.name],r):a[t.name]=m(s,t):t.kind==="wrap"&&(a[t.name]=r=>{let c=t.when(r)?[...s,t.name]:s,p=m(c,t);return Object.assign(o(t)?f=>l(c,f):{},p)});return N(a,s,e.rest)}function N(n,e,o){return n.when=(s,a)=>m(s?[...e,...Array.isArray(a)?a:[a]]:e,d("",o)),n.join=s=>m([...e,...Array.isArray(s)?s:[s]],d("",o)),n}0&&(module.exports={keep,path,root,slot,wrap});
+//# sourceMappingURL=api.cjs.map

package/dist/api.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api.ts"],"sourcesContent":["import { Keep, Path, Wrap, Slot, PathDef, SlotDef, Segment, SParams, RoutesFromDefs } from './dsl'\n\n// ---------- DSL helpers (typed) ----------\nexport const keep = (): Keep => ({ kind: 'keep' })\n\nexport const path = <\n\tconst Name extends string,\n\tconst Rest extends readonly PathDef[] = readonly [],\n>(\n\tname: Name,\n\trest?: Rest\n): Path<Name, Rest> => ({ kind: 'path', name, rest: (rest ?? []) as Rest })\n\nexport const slot = <\n\tconst Name extends string,\n\tconst Rest extends readonly PathDef[] = readonly [],\n>(\n\tname: Name,\n\trest?: Rest\n): Slot<Name, Rest> => ({ kind: 'slot', name, rest: (rest ?? []) as Rest })\n\nexport const wrap = <\n\tconst Name extends string,\n\tconst Rest extends readonly PathDef[] = readonly [],\n\tArgs = unknown,\n>(\n\tname: Name,\n\twhen: (args: Args) => boolean,\n\trest?: Rest\n): Wrap<Name, Rest, Args> => ({ kind: 'wrap', name, when, rest: (rest ?? []) as Rest })\n\n// ---------- Runtime implementation ----------\nconst url = (path: Segment[], search?: SParams) =>\n\t`${path.filter(Boolean).join('/')}${search ? `?${search}` : ''}`.replace('//', '/')\n\n// ---------- Typed root signature ----------\nexport function root<const Defs extends readonly PathDef[]>(\n\tdefs: Defs\n): RoutesFromDefs<Defs> {\n\treturn buildPath([], path('/', defs)) as unknown as RoutesFromDefs<Defs>\n}\n\nfunction buildPath(prefix: Segment[], def: SlotDef) {\n\tconst hasKeep = (pathDef: SlotDef) => pathDef.rest.some((c) => c.kind === 'keep')\n\tconst allPath =\n\t\tdef.kind === 'slot' || def.kind === 'wrap'\n\t\t\t? prefix\n\t\t\t: def.name\n\t\t\t\t? [...prefix, def.name]\n\t\t\t\t: prefix\n\n\t// If there is a keep(), the path itself is callable and acts as \"keep\"\n\tconst target: any = hasKeep(def) ? (search?: SParams) => url(allPath, search) : {}\n\n\tfor (const child of def.rest) {\n\t\tif (child.kind === 'slot') {\n\t\t\tif (child.rest.length === 0) {\n\t\t\t\ttarget[child.name] = (param: Segment) => (search?: SParams) =>\n\t\t\t\t\turl([...allPath, param], search)\n\t\t\t} else {\n\t\t\t\ttarget[child.name] = (param: Segment) => {\n\t\t\t\t\t// Build subtree for nested parts under :id\n\t\t\t\t\t// Synthetic path with empty name so we don't add extra segment.\n\t\t\t\t\tconst subTree = buildPath([...allPath, param], child)\n\n\t\t\t\t\t// Attach children (info, activities, etc.) to that function\n\t\t\t\t\treturn Object.assign(\n\t\t\t\t\t\thasKeep(child)\n\t\t\t\t\t\t\t? (search?: SParams) => url([...allPath, param], search)\n\t\t\t\t\t\t\t: {},\n\t\t\t\t\t\tsubTree\n\t\t\t\t\t)\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (child.kind === 'path') {\n\t\t\tif (child.rest.length === 0) {\n\t\t\t\ttarget[child.name] = (search?: SParams) => url([...allPath, child.name], search)\n\t\t\t} else {\n\t\t\t\ttarget[child.name] = buildPath(allPath, child)\n\t\t\t}\n\t\t} else if (child.kind === 'wrap') {\n\t\t\ttarget[child.name] = (arg: unknown) => {\n\t\t\t\tconst enabled = child.when(arg)\n\t\t\t\tconst wrapped = enabled ? [...allPath, child.name] : allPath\n\t\t\t\tconst subTree = buildPath(wrapped, child as any)\n\n\t\t\t\treturn Object.assign(\n\t\t\t\t\t// if wrap has keep(), it becomes callable at that point\n\t\t\t\t\thasKeep(child as any) ? (search?: SParams) => url(wrapped, search) : {},\n\t\t\t\t\tsubTree\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn attachWhenAndJoin(target, allPath, def.rest)\n}\n\nfunction attachWhenAndJoin(target: any, basePath: Segment[], rest: readonly PathDef[]) {\n\ttarget.when = (cond: boolean, seg: Segment | readonly Segment[]) => {\n\t\t// Rebuild \"same subtree\" at a new prefix:\n\t\t// Use a synthetic path '' so we don't append an extra segment name.\n\t\treturn buildPath(\n\t\t\tcond ? [...basePath, ...(Array.isArray(seg) ? seg : [seg])] : basePath,\n\t\t\tpath('', rest)\n\t\t)\n\t}\n\ttarget.join = (seg: Segment | readonly Segment[]) => {\n\t\treturn buildPath([...basePath, ...(Array.isArray(seg) ? seg : [seg])], path('', rest))\n\t}\n\n\treturn target\n}\n"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,UAAAE,EAAA,SAAAC,EAAA,SAAAC,EAAA,SAAAC,EAAA,SAAAC,IAAA,eAAAC,EAAAP,GAGO,IAAME,EAAO,KAAa,CAAE,KAAM,MAAO,GAEnCC,EAAO,CAInBK,EACAC,KACuB,CAAE,KAAM,OAAQ,KAAAD,EAAM,KAAOC,GAAQ,CAAC,CAAW,GAE5DJ,EAAO,CAInBG,EACAC,KACuB,CAAE,KAAM,OAAQ,KAAAD,EAAM,KAAOC,GAAQ,CAAC,CAAW,GAE5DH,EAAO,CAKnBE,EACAE,EACAD,KAC6B,CAAE,KAAM,OAAQ,KAAAD,EAAM,KAAAE,EAAM,KAAOD,GAAQ,CAAC,CAAW,GAG/EE,EAAM,CAACR,EAAiBS,IAC7B,GAAGT,EAAK,OAAO,OAAO,EAAE,KAAK,GAAG,CAAC,GAAGS,EAAS,IAAIA,CAAM,GAAK,EAAE,GAAG,QAAQ,KAAM,GAAG,EAG5E,SAASR,EACfS,EACuB,CACvB,OAAOC,EAAU,CAAC,EAAGX,EAAK,IAAKU,CAAI,CAAC,CACrC,CAEA,SAASC,EAAUC,EAAmBC,EAAc,CACnD,IAAMC,EAAWC,GAAqBA,EAAQ,KAAK,KAAMC,GAAMA,EAAE,OAAS,MAAM,EAC1EC,EACLJ,EAAI,OAAS,QAAUA,EAAI,OAAS,OACjCD,EACAC,EAAI,KACH,CAAC,GAAGD,EAAQC,EAAI,IAAI,EACpBD,EAGCM,EAAcJ,EAAQD,CAAG,EAAKJ,GAAqBD,EAAIS,EAASR,CAAM,EAAI,CAAC,EAEjF,QAAWU,KAASN,EAAI,KACnBM,EAAM,OAAS,OACdA,EAAM,KAAK,SAAW,EACzBD,EAAOC,EAAM,IAAI,EAAKC,GAAoBX,GACzCD,EAAI,CAAC,GAAGS,EAASG,CAAK,EAAGX,CAAM,EAEhCS,EAAOC,EAAM,IAAI,EAAKC,GAAmB,CAGxC,IAAMC,EAAUV,EAAU,CAAC,GAAGM,EAASG,CAAK,EAAGD,CAAK,EAGpD,OAAO,OAAO,OACbL,EAAQK,CAAK,EACTV,GAAqBD,EAAI,CAAC,GAAGS,EAASG,CAAK,EAAGX,CAAM,EACrD,CAAC,EACJY,CACD,CACD,EAESF,EAAM,OAAS,OACrBA,EAAM,KAAK,SAAW,EACzBD,EAAOC,EAAM,IAAI,EAAKV,GAAqBD,EAAI,CAAC,GAAGS,EAASE,EAAM,IAAI,EAAGV,CAAM,EAE/ES,EAAOC,EAAM,IAAI,EAAIR,EAAUM,EAASE,CAAK,EAEpCA,EAAM,OAAS,SACzBD,EAAOC,EAAM,IAAI,EAAKG,GAAiB,CAEtC,IAAMC,EADUJ,EAAM,KAAKG,CAAG,EACJ,CAAC,GAAGL,EAASE,EAAM,IAAI,EAAIF,EAC/CI,EAAUV,EAAUY,EAASJ,CAAY,EAE/C,OAAO,OAAO,OAEbL,EAAQK,CAAY,EAAKV,GAAqBD,EAAIe,EAASd,CAAM,EAAI,CAAC,EACtEY,CACD,CACD,GAIF,OAAOG,EAAkBN,EAAQD,EAASJ,EAAI,IAAI,CACnD,CAEA,SAASW,EAAkBN,EAAaO,EAAqBnB,EAA0B,CACtF,OAAAY,EAAO,KAAO,CAACQ,EAAeC,IAGtBhB,EACNe,EAAO,CAAC,GAAGD,EAAU,GAAI,MAAM,QAAQE,CAAG,EAAIA,EAAM,CAACA,CAAG,CAAE,EAAIF,EAC9DzB,EAAK,GAAIM,CAAI,CACd,EAEDY,EAAO,KAAQS,GACPhB,EAAU,CAAC,GAAGc,EAAU,GAAI,MAAM,QAAQE,CAAG,EAAIA,EAAM,CAACA,CAAG,CAAE,EAAG3B,EAAK,GAAIM,CAAI,CAAC,EAG/EY,CACR","names":["api_exports","__export","keep","path","root","slot","wrap","__toCommonJS","name","rest","when","url","search","defs","buildPath","prefix","def","hasKeep","pathDef","c","allPath","target","child","param","subTree","arg","wrapped","attachWhenAndJoin","basePath","cond","seg"]}

package/dist/api.d.cts

@@ -0,0 +1,96 @@
+// ---------- Shared public types ----------
+type Segment = string | number
+type SParams = string | URLSearchParams
+
+// ---------- DSL definition types ----------
+type Keep = { kind: 'keep' }
+
+type Path<
+	Name extends string = string,
+	Rest extends readonly PathDef[] = readonly PathDef[],
+> = { kind: 'path'; name: Name; rest: Rest }
+
+type Slot<
+	Name extends string = string,
+	Rest extends readonly PathDef[] = readonly PathDef[],
+> = { kind: 'slot'; name: Name; rest: Rest }
+
+type Wrap<
+	Name extends string = string,
+	Rest extends readonly PathDef[] = readonly PathDef[],
+	Args = unknown,
+> = { kind: 'wrap'; name: Name; rest: Rest; when: (args: Args) => boolean }
+
+type SlotDef =
+	| Path<string, readonly PathDef[]>
+	| Slot<string, readonly PathDef[]>
+	| Wrap<string, readonly PathDef[], any>
+type PathDef = SlotDef | Keep
+
+// ---------- Type-level route builder ----------
+interface Whenable {
+	when(cond: boolean, seg: Segment | readonly Segment[]): this
+	join(seg: Segment | readonly Segment[]): this
+}
+
+type HasKeep<Rest extends readonly PathDef[]> =
+	Extract<Rest[number], Keep> extends never ? false : true
+
+type NonKeepChildren<Rest extends readonly PathDef[]> = Exclude<Rest[number], Keep>
+
+type PropsFromChildren<Rest extends readonly PathDef[]> = {
+	[C in NonKeepChildren<Rest> as C extends { name: infer N extends string }
+		? N
+		: never]: C extends Path<any, any>
+		? RouteFromPath<C>
+		: C extends Slot<any, any>
+			? RouteFromSlot<C>
+			: C extends Wrap<any, any, any>
+				? RouteFromWrap<C>
+				: never
+}
+
+type WithWhen<T> = T & Whenable
+
+// Example: apply it to the outputs
+type RouteFromPath<N extends Path<any, any>> = WithWhen<
+	N['rest'] extends readonly []
+		? (search?: SParams) => string
+		: HasKeep<N['rest']> extends true
+			? ((search?: SParams) => string) & PropsFromChildren<N['rest']>
+			: PropsFromChildren<N['rest']>
+>
+
+type SlotResult<Rest extends readonly PathDef[]> = WithWhen<
+	Rest extends readonly []
+		? (search?: SParams) => string
+		: HasKeep<Rest> extends true
+			? ((search?: SParams) => string) & PropsFromChildren<Rest>
+			: PropsFromChildren<Rest>
+>
+
+type RouteFromSlot<I extends Slot<any, any>> = (param: Segment) => SlotResult<I['rest']>
+
+type WrapArg<W extends Wrap<any, any, any>> = Parameters<W['when']>[0]
+
+type WrapResult<Rest extends readonly PathDef[]> = WithWhen<
+	HasKeep<Rest> extends true
+		? ((search?: SParams) => string) & PropsFromChildren<Rest>
+		: PropsFromChildren<Rest>
+>
+
+type RouteFromWrap<W extends Wrap<any, any, any>> = (arg: WrapArg<W>) => WrapResult<W['rest']>
+
+type RoutesFromDefs<Defs extends readonly PathDef[]> = WithWhen<
+	HasKeep<Defs> extends true
+		? ((search?: SParams) => string) & PropsFromChildren<Defs>
+		: PropsFromChildren<Defs>
+>
+
+declare const keep: () => Keep;
+declare const path: <const Name extends string, const Rest extends readonly PathDef[] = readonly []>(name: Name, rest?: Rest) => Path<Name, Rest>;
+declare const slot: <const Name extends string, const Rest extends readonly PathDef[] = readonly []>(name: Name, rest?: Rest) => Slot<Name, Rest>;
+declare const wrap: <const Name extends string, const Rest extends readonly PathDef[] = readonly [], Args = unknown>(name: Name, when: (args: Args) => boolean, rest?: Rest) => Wrap<Name, Rest, Args>;
+declare function root<const Defs extends readonly PathDef[]>(defs: Defs): RoutesFromDefs<Defs>;
+
+export { keep, path, root, slot, wrap };

package/dist/api.d.ts

@@ -0,0 +1,96 @@
+// ---------- Shared public types ----------
+type Segment = string | number
+type SParams = string | URLSearchParams
+
+// ---------- DSL definition types ----------
+type Keep = { kind: 'keep' }
+
+type Path<
+	Name extends string = string,
+	Rest extends readonly PathDef[] = readonly PathDef[],
+> = { kind: 'path'; name: Name; rest: Rest }
+
+type Slot<
+	Name extends string = string,
+	Rest extends readonly PathDef[] = readonly PathDef[],
+> = { kind: 'slot'; name: Name; rest: Rest }
+
+type Wrap<
+	Name extends string = string,
+	Rest extends readonly PathDef[] = readonly PathDef[],
+	Args = unknown,
+> = { kind: 'wrap'; name: Name; rest: Rest; when: (args: Args) => boolean }
+
+type SlotDef =
+	| Path<string, readonly PathDef[]>
+	| Slot<string, readonly PathDef[]>
+	| Wrap<string, readonly PathDef[], any>
+type PathDef = SlotDef | Keep
+
+// ---------- Type-level route builder ----------
+interface Whenable {
+	when(cond: boolean, seg: Segment | readonly Segment[]): this
+	join(seg: Segment | readonly Segment[]): this
+}
+
+type HasKeep<Rest extends readonly PathDef[]> =
+	Extract<Rest[number], Keep> extends never ? false : true
+
+type NonKeepChildren<Rest extends readonly PathDef[]> = Exclude<Rest[number], Keep>
+
+type PropsFromChildren<Rest extends readonly PathDef[]> = {
+	[C in NonKeepChildren<Rest> as C extends { name: infer N extends string }
+		? N
+		: never]: C extends Path<any, any>
+		? RouteFromPath<C>
+		: C extends Slot<any, any>
+			? RouteFromSlot<C>
+			: C extends Wrap<any, any, any>
+				? RouteFromWrap<C>
+				: never
+}
+
+type WithWhen<T> = T & Whenable
+
+// Example: apply it to the outputs
+type RouteFromPath<N extends Path<any, any>> = WithWhen<
+	N['rest'] extends readonly []
+		? (search?: SParams) => string
+		: HasKeep<N['rest']> extends true
+			? ((search?: SParams) => string) & PropsFromChildren<N['rest']>
+			: PropsFromChildren<N['rest']>
+>
+
+type SlotResult<Rest extends readonly PathDef[]> = WithWhen<
+	Rest extends readonly []
+		? (search?: SParams) => string
+		: HasKeep<Rest> extends true
+			? ((search?: SParams) => string) & PropsFromChildren<Rest>
+			: PropsFromChildren<Rest>
+>
+
+type RouteFromSlot<I extends Slot<any, any>> = (param: Segment) => SlotResult<I['rest']>
+
+type WrapArg<W extends Wrap<any, any, any>> = Parameters<W['when']>[0]
+
+type WrapResult<Rest extends readonly PathDef[]> = WithWhen<
+	HasKeep<Rest> extends true
+		? ((search?: SParams) => string) & PropsFromChildren<Rest>
+		: PropsFromChildren<Rest>
+>
+
+type RouteFromWrap<W extends Wrap<any, any, any>> = (arg: WrapArg<W>) => WrapResult<W['rest']>
+
+type RoutesFromDefs<Defs extends readonly PathDef[]> = WithWhen<
+	HasKeep<Defs> extends true
+		? ((search?: SParams) => string) & PropsFromChildren<Defs>
+		: PropsFromChildren<Defs>
+>
+
+declare const keep: () => Keep;
+declare const path: <const Name extends string, const Rest extends readonly PathDef[] = readonly []>(name: Name, rest?: Rest) => Path<Name, Rest>;
+declare const slot: <const Name extends string, const Rest extends readonly PathDef[] = readonly []>(name: Name, rest?: Rest) => Slot<Name, Rest>;
+declare const wrap: <const Name extends string, const Rest extends readonly PathDef[] = readonly [], Args = unknown>(name: Name, when: (args: Args) => boolean, rest?: Rest) => Wrap<Name, Rest, Args>;
+declare function root<const Defs extends readonly PathDef[]>(defs: Defs): RoutesFromDefs<Defs>;
+
+export { keep, path, root, slot, wrap };

package/dist/api.js

@@ -0,0 +1,2 @@
+var u=()=>({kind:"keep"}),d=(t,n)=>({kind:"path",name:t,rest:n??[]}),h=(t,n)=>({kind:"slot",name:t,rest:n??[]}),y=(t,n,r)=>({kind:"wrap",name:t,when:n,rest:r??[]}),l=(t,n)=>`${t.filter(Boolean).join("/")}${n?`?${n}`:""}`.replace("//","/");function g(t){return m([],d("/",t))}function m(t,n){let r=e=>e.rest.some(o=>o.kind==="keep"),s=n.kind==="slot"||n.kind==="wrap"?t:n.name?[...t,n.name]:t,a=r(n)?e=>l(s,e):{};for(let e of n.rest)e.kind==="slot"?e.rest.length===0?a[e.name]=o=>i=>l([...s,o],i):a[e.name]=o=>{let i=m([...s,o],e);return Object.assign(r(e)?c=>l([...s,o],c):{},i)}:e.kind==="path"?e.rest.length===0?a[e.name]=o=>l([...s,e.name],o):a[e.name]=m(s,e):e.kind==="wrap"&&(a[e.name]=o=>{let c=e.when(o)?[...s,e.name]:s,S=m(c,e);return Object.assign(r(e)?p=>l(c,p):{},S)});return f(a,s,n.rest)}function f(t,n,r){return t.when=(s,a)=>m(s?[...n,...Array.isArray(a)?a:[a]]:n,d("",r)),t.join=s=>m([...n,...Array.isArray(s)?s:[s]],d("",r)),t}export{u as keep,d as path,g as root,h as slot,y as wrap};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api.ts"],"sourcesContent":["import { Keep, Path, Wrap, Slot, PathDef, SlotDef, Segment, SParams, RoutesFromDefs } from './dsl'\n\n// ---------- DSL helpers (typed) ----------\nexport const keep = (): Keep => ({ kind: 'keep' })\n\nexport const path = <\n\tconst Name extends string,\n\tconst Rest extends readonly PathDef[] = readonly [],\n>(\n\tname: Name,\n\trest?: Rest\n): Path<Name, Rest> => ({ kind: 'path', name, rest: (rest ?? []) as Rest })\n\nexport const slot = <\n\tconst Name extends string,\n\tconst Rest extends readonly PathDef[] = readonly [],\n>(\n\tname: Name,\n\trest?: Rest\n): Slot<Name, Rest> => ({ kind: 'slot', name, rest: (rest ?? []) as Rest })\n\nexport const wrap = <\n\tconst Name extends string,\n\tconst Rest extends readonly PathDef[] = readonly [],\n\tArgs = unknown,\n>(\n\tname: Name,\n\twhen: (args: Args) => boolean,\n\trest?: Rest\n): Wrap<Name, Rest, Args> => ({ kind: 'wrap', name, when, rest: (rest ?? []) as Rest })\n\n// ---------- Runtime implementation ----------\nconst url = (path: Segment[], search?: SParams) =>\n\t`${path.filter(Boolean).join('/')}${search ? `?${search}` : ''}`.replace('//', '/')\n\n// ---------- Typed root signature ----------\nexport function root<const Defs extends readonly PathDef[]>(\n\tdefs: Defs\n): RoutesFromDefs<Defs> {\n\treturn buildPath([], path('/', defs)) as unknown as RoutesFromDefs<Defs>\n}\n\nfunction buildPath(prefix: Segment[], def: SlotDef) {\n\tconst hasKeep = (pathDef: SlotDef) => pathDef.rest.some((c) => c.kind === 'keep')\n\tconst allPath =\n\t\tdef.kind === 'slot' || def.kind === 'wrap'\n\t\t\t? prefix\n\t\t\t: def.name\n\t\t\t\t? [...prefix, def.name]\n\t\t\t\t: prefix\n\n\t// If there is a keep(), the path itself is callable and acts as \"keep\"\n\tconst target: any = hasKeep(def) ? (search?: SParams) => url(allPath, search) : {}\n\n\tfor (const child of def.rest) {\n\t\tif (child.kind === 'slot') {\n\t\t\tif (child.rest.length === 0) {\n\t\t\t\ttarget[child.name] = (param: Segment) => (search?: SParams) =>\n\t\t\t\t\turl([...allPath, param], search)\n\t\t\t} else {\n\t\t\t\ttarget[child.name] = (param: Segment) => {\n\t\t\t\t\t// Build subtree for nested parts under :id\n\t\t\t\t\t// Synthetic path with empty name so we don't add extra segment.\n\t\t\t\t\tconst subTree = buildPath([...allPath, param], child)\n\n\t\t\t\t\t// Attach children (info, activities, etc.) to that function\n\t\t\t\t\treturn Object.assign(\n\t\t\t\t\t\thasKeep(child)\n\t\t\t\t\t\t\t? (search?: SParams) => url([...allPath, param], search)\n\t\t\t\t\t\t\t: {},\n\t\t\t\t\t\tsubTree\n\t\t\t\t\t)\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (child.kind === 'path') {\n\t\t\tif (child.rest.length === 0) {\n\t\t\t\ttarget[child.name] = (search?: SParams) => url([...allPath, child.name], search)\n\t\t\t} else {\n\t\t\t\ttarget[child.name] = buildPath(allPath, child)\n\t\t\t}\n\t\t} else if (child.kind === 'wrap') {\n\t\t\ttarget[child.name] = (arg: unknown) => {\n\t\t\t\tconst enabled = child.when(arg)\n\t\t\t\tconst wrapped = enabled ? [...allPath, child.name] : allPath\n\t\t\t\tconst subTree = buildPath(wrapped, child as any)\n\n\t\t\t\treturn Object.assign(\n\t\t\t\t\t// if wrap has keep(), it becomes callable at that point\n\t\t\t\t\thasKeep(child as any) ? (search?: SParams) => url(wrapped, search) : {},\n\t\t\t\t\tsubTree\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn attachWhenAndJoin(target, allPath, def.rest)\n}\n\nfunction attachWhenAndJoin(target: any, basePath: Segment[], rest: readonly PathDef[]) {\n\ttarget.when = (cond: boolean, seg: Segment | readonly Segment[]) => {\n\t\t// Rebuild \"same subtree\" at a new prefix:\n\t\t// Use a synthetic path '' so we don't append an extra segment name.\n\t\treturn buildPath(\n\t\t\tcond ? [...basePath, ...(Array.isArray(seg) ? seg : [seg])] : basePath,\n\t\t\tpath('', rest)\n\t\t)\n\t}\n\ttarget.join = (seg: Segment | readonly Segment[]) => {\n\t\treturn buildPath([...basePath, ...(Array.isArray(seg) ? seg : [seg])], path('', rest))\n\t}\n\n\treturn target\n}\n"],"mappings":"AAGO,IAAMA,EAAO,KAAa,CAAE,KAAM,MAAO,GAEnCC,EAAO,CAInBC,EACAC,KACuB,CAAE,KAAM,OAAQ,KAAAD,EAAM,KAAOC,GAAQ,CAAC,CAAW,GAE5DC,EAAO,CAInBF,EACAC,KACuB,CAAE,KAAM,OAAQ,KAAAD,EAAM,KAAOC,GAAQ,CAAC,CAAW,GAE5DE,EAAO,CAKnBH,EACAI,EACAH,KAC6B,CAAE,KAAM,OAAQ,KAAAD,EAAM,KAAAI,EAAM,KAAOH,GAAQ,CAAC,CAAW,GAG/EI,EAAM,CAACN,EAAiBO,IAC7B,GAAGP,EAAK,OAAO,OAAO,EAAE,KAAK,GAAG,CAAC,GAAGO,EAAS,IAAIA,CAAM,GAAK,EAAE,GAAG,QAAQ,KAAM,GAAG,EAG5E,SAASC,EACfC,EACuB,CACvB,OAAOC,EAAU,CAAC,EAAGV,EAAK,IAAKS,CAAI,CAAC,CACrC,CAEA,SAASC,EAAUC,EAAmBC,EAAc,CACnD,IAAMC,EAAWC,GAAqBA,EAAQ,KAAK,KAAMC,GAAMA,EAAE,OAAS,MAAM,EAC1EC,EACLJ,EAAI,OAAS,QAAUA,EAAI,OAAS,OACjCD,EACAC,EAAI,KACH,CAAC,GAAGD,EAAQC,EAAI,IAAI,EACpBD,EAGCM,EAAcJ,EAAQD,CAAG,EAAKL,GAAqBD,EAAIU,EAAST,CAAM,EAAI,CAAC,EAEjF,QAAWW,KAASN,EAAI,KACnBM,EAAM,OAAS,OACdA,EAAM,KAAK,SAAW,EACzBD,EAAOC,EAAM,IAAI,EAAKC,GAAoBZ,GACzCD,EAAI,CAAC,GAAGU,EAASG,CAAK,EAAGZ,CAAM,EAEhCU,EAAOC,EAAM,IAAI,EAAKC,GAAmB,CAGxC,IAAMC,EAAUV,EAAU,CAAC,GAAGM,EAASG,CAAK,EAAGD,CAAK,EAGpD,OAAO,OAAO,OACbL,EAAQK,CAAK,EACTX,GAAqBD,EAAI,CAAC,GAAGU,EAASG,CAAK,EAAGZ,CAAM,EACrD,CAAC,EACJa,CACD,CACD,EAESF,EAAM,OAAS,OACrBA,EAAM,KAAK,SAAW,EACzBD,EAAOC,EAAM,IAAI,EAAKX,GAAqBD,EAAI,CAAC,GAAGU,EAASE,EAAM,IAAI,EAAGX,CAAM,EAE/EU,EAAOC,EAAM,IAAI,EAAIR,EAAUM,EAASE,CAAK,EAEpCA,EAAM,OAAS,SACzBD,EAAOC,EAAM,IAAI,EAAKG,GAAiB,CAEtC,IAAMC,EADUJ,EAAM,KAAKG,CAAG,EACJ,CAAC,GAAGL,EAASE,EAAM,IAAI,EAAIF,EAC/CI,EAAUV,EAAUY,EAASJ,CAAY,EAE/C,OAAO,OAAO,OAEbL,EAAQK,CAAY,EAAKX,GAAqBD,EAAIgB,EAASf,CAAM,EAAI,CAAC,EACtEa,CACD,CACD,GAIF,OAAOG,EAAkBN,EAAQD,EAASJ,EAAI,IAAI,CACnD,CAEA,SAASW,EAAkBN,EAAaO,EAAqBtB,EAA0B,CACtF,OAAAe,EAAO,KAAO,CAACQ,EAAeC,IAGtBhB,EACNe,EAAO,CAAC,GAAGD,EAAU,GAAI,MAAM,QAAQE,CAAG,EAAIA,EAAM,CAACA,CAAG,CAAE,EAAIF,EAC9DxB,EAAK,GAAIE,CAAI,CACd,EAEDe,EAAO,KAAQS,GACPhB,EAAU,CAAC,GAAGc,EAAU,GAAI,MAAM,QAAQE,CAAG,EAAIA,EAAM,CAACA,CAAG,CAAE,EAAG1B,EAAK,GAAIE,CAAI,CAAC,EAG/Ee,CACR","names":["keep","path","name","rest","slot","wrap","when","url","search","root","defs","buildPath","prefix","def","hasKeep","pathDef","c","allPath","target","child","param","subTree","arg","wrapped","attachWhenAndJoin","basePath","cond","seg"]}

package/package.json

@@ -0,0 +1,77 @@
+{
+	"name": "route-sprout",
+	"version": "1.0.0",
+	"description": "A tiny, cute DSL that grows type-safe, composable URL builders from a declarative route tree.",
+	"author": "Piotr Siatkowski <p.siatkowski@gmail.com>",
+	"license": "MIT",
+	"keywords": [
+		"routing",
+		"tiny",
+		"api",
+		"tree",
+		"DSL",
+		"typed",
+		"no-boilerplate",
+		"flexibility"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git://github.com/PiotrSiatkowski/route-sprout.git",
+		"web": "https://github.com/PiotrSiatkowski/route-sprout"
+	},
+	"bugs": {
+		"url": "https://github.com/PiotrSiatkowski/route-sprout/issues"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist/**/*"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/dsl.d.ts",
+			"import": "./dist/api.js",
+			"require": "./dist/api.cjs",
+			"default": "./dist/api.js"
+		},
+		"./dialect-path": {
+			"types": "./dist/dsl.d.ts",
+			"import": "./dist/dialect-path.js",
+			"require": "./dist/dialect-path.cjs",
+			"default": "./dist/dialect-path.js"
+		},
+		"./dialect-node": {
+			"types": "./dist/dsl.d.ts",
+			"import": "./dist/dialect-node.js",
+			"require": "./dist/dialect-node.cjs",
+			"default": "./dist/dialect-node.js"
+		},
+		"./dialect-step": {
+			"types": "./dist/dsl.d.ts",
+			"import": "./dist/dialect-step.js",
+			"require": "./dist/dialect-step.cjs",
+			"default": "./dist/dialect-step.js"
+		},
+		"./dialect-tree": {
+			"types": "./dist/dsl.d.ts",
+			"import": "./dist/dialect-tree.js",
+			"require": "./dist/dialect-tree.cjs",
+			"default": "./dist/dialect-tree.js"
+		}
+	},
+	"scripts": {
+		"build": "vitest && tsup src/api.ts --format esm,cjs --dts --clean --sourcemap --minify",
+		"publish": "npm publish --access public",
+		"test": "vitest"
+	},
+	"devDependencies": {
+		"prettier": "^3.5.3",
+		"tsup": "^8.5.0",
+		"typescript": "5.8.3",
+		"vitest": "^4.0.16"
+	},
+	"private": false
+}