spiceflow 1.17.11 → 1.18.0

package/src/spiceflow.test.ts

@@ -1,6 +1,6 @@
 import { test, describe, expect } from 'vitest'
 
-import { bfs, cloneDeep, Spiceflow } from './spiceflow.ts'
+import { bfs, cloneDeep, createSafePath, Spiceflow } from './spiceflow.ts'
 import { z } from 'zod'
 import { createSpiceflowClient } from './client/index.ts'
 
@@ -1257,6 +1257,320 @@ describe('safePath', () => {
     expect(res.status).toBe(200)
     expect(await res.json()).toBe('/target')
   })
+
+  test('safePath appends query params', () => {
+    const app = new Spiceflow()
+      .get('/search', () => 'results', {
+        query: z.object({ q: z.string(), page: z.coerce.number() }),
+      })
+      .get('/users/:id', ({ params }) => params.id, {
+        query: z.object({ fields: z.string() }),
+      })
+
+    expect(app.safePath('/search', { q: 'hello', page: 1 })).toBe(
+      '/search?q=hello&page=1',
+    )
+    expect(
+      app.safePath('/users/:id', { id: '42', fields: 'name' }),
+    ).toBe('/users/42?fields=name')
+
+    // @ts-expect-error - invalid query key 'invalid' not in schema
+    app.safePath('/search', { invalid: 'x' })
+
+    // @ts-expect-error - invalid query key 'nonexistent' not in schema
+    app.safePath('/users/:id', { id: '1', nonexistent: 'x' })
+  })
+
+  test('safePath with query params and no path params', () => {
+    const app = new Spiceflow().get('/items', () => 'items', {
+      query: z.object({ sort: z.string(), limit: z.coerce.number() }),
+    })
+
+    expect(
+      app.safePath('/items', { sort: 'date', limit: 10 }),
+    ).toBe('/items?sort=date&limit=10')
+
+    // @ts-expect-error - wrong query key
+    app.safePath('/items', { order: 'asc' })
+  })
+
+  test('safePath without query still works', () => {
+    const app = new Spiceflow()
+      .get('/simple', () => 'simple')
+      .get('/with-query', () => 'q', {
+        query: z.object({ x: z.string() }),
+      })
+
+    expect(app.safePath('/simple')).toBe('/simple')
+    expect(app.safePath('/with-query')).toBe('/with-query')
+  })
+
+  test('safePath with .route and query', () => {
+    const app = new Spiceflow().route({
+      method: 'GET',
+      path: '/api/search',
+      query: z.object({ term: z.string() }),
+      handler: () => 'search',
+    })
+
+    expect(
+      app.safePath('/api/search', { term: 'test' }),
+    ).toBe('/api/search?term=test')
+
+    // @ts-expect-error - invalid query key for .route-based route
+    app.safePath('/api/search', { wrong: 'x' })
+  })
+
+  test('safePath skips undefined/null query values', () => {
+    const app = new Spiceflow().get('/filter', () => 'filter', {
+      query: z.object({ a: z.string(), b: z.string().optional() }),
+    })
+
+    expect(
+      app.safePath('/filter', { a: 'yes', b: undefined }),
+    ).toBe('/filter?a=yes')
+  })
+
+  test('safePath query with basePath', () => {
+    const app = new Spiceflow({ basePath: '/api' }).get(
+      '/search',
+      () => 'search',
+      {
+        query: z.object({ q: z.string() }),
+      },
+    )
+
+    expect(
+      app.safePath('/api/search', { q: 'hello' }),
+    ).toBe('/api/search?q=hello')
+
+    // @ts-expect-error - invalid query key with basePath
+    app.safePath('/api/search', { wrong: 'x' })
+  })
+
+  test('safePath query with all HTTP method shorthands', () => {
+    const app = new Spiceflow()
+      .put('/put-q', () => 'put', {
+        query: z.object({ x: z.string() }),
+      })
+      .patch('/patch-q', () => 'patch', {
+        query: z.object({ y: z.coerce.number() }),
+      })
+      .delete('/del-q', () => 'del', {
+        query: z.object({ confirm: z.boolean() }),
+      })
+
+    expect(app.safePath('/put-q', { x: 'val' })).toBe(
+      '/put-q?x=val',
+    )
+    expect(app.safePath('/patch-q', { y: 5 })).toBe(
+      '/patch-q?y=5',
+    )
+    expect(app.safePath('/del-q', { confirm: true })).toBe(
+      '/del-q?confirm=true',
+    )
+
+    // @ts-expect-error - wrong query key on put
+    app.safePath('/put-q', { wrong: 'x' })
+
+    // @ts-expect-error - wrong query key on patch
+    app.safePath('/patch-q', { wrong: 1 })
+
+    // @ts-expect-error - wrong query key on delete
+    app.safePath('/del-q', { wrong: true })
+  })
+
+  test('safePath routes without query schema accept arbitrary query at runtime', () => {
+    const app = new Spiceflow().get('/no-schema', () => 'ok')
+
+    expect(
+      app.safePath('/no-schema', { anything: 'works' }),
+    ).toBe('/no-schema?anything=works')
+  })
+})
+
+describe('createSafePath', () => {
+  test('works with simple paths', () => {
+    const app = new Spiceflow()
+      .get('/users', () => 'users')
+      .get('/posts', () => 'posts')
+
+    const safePath = createSafePath(app)
+    expect(safePath('/users')).toBe('/users')
+    expect(safePath('/posts')).toBe('/posts')
+    // @ts-expect-error - invalid path
+    safePath('/nonexistent')
+  })
+
+  test('works with path params', () => {
+    const app = new Spiceflow()
+      .get('/users/:id', ({ params }) => params.id)
+      .get('/posts/:postId/comments/:commentId', ({ params }) => params)
+
+    const safePath = createSafePath(app)
+    expect(safePath('/users/:id', { id: '123' })).toBe('/users/123')
+    expect(
+      safePath('/posts/:postId/comments/:commentId', {
+        postId: 'abc',
+        commentId: '456',
+      }),
+    ).toBe('/posts/abc/comments/456')
+    // @ts-expect-error - wrong path
+    safePath('/wrong/:id', { id: '1' })
+  })
+
+  test('works with query params and rejects invalid keys', () => {
+    const app = new Spiceflow()
+      .get('/search', () => 'results', {
+        query: z.object({ q: z.string(), page: z.coerce.number() }),
+      })
+
+    const safePath = createSafePath(app)
+    expect(safePath('/search', { q: 'hello', page: 1 })).toBe(
+      '/search?q=hello&page=1',
+    )
+
+    // @ts-expect-error - invalid query key
+    safePath('/search', { invalid: 'x' })
+  })
+
+  test('works with both path and query params', () => {
+    const app = new Spiceflow()
+      .get('/users/:id', ({ params }) => params.id, {
+        query: z.object({ fields: z.string() }),
+      })
+
+    const safePath = createSafePath(app)
+    expect(
+      safePath('/users/:id', { id: '42', fields: 'name' }),
+    ).toBe('/users/42?fields=name')
+
+    // @ts-expect-error - invalid query key with path params
+    safePath('/users/:id', { id: '1', wrong: 'x' })
+  })
+
+  test('works with wildcard paths', () => {
+    const app = new Spiceflow().get('/files/*', () => 'files')
+
+    const safePath = createSafePath(app)
+    expect(safePath('/files/*', { '*': 'a/b.txt' })).toBe('/files/a/b.txt')
+  })
+
+  test('rejects invalid query keys across multiple routes', () => {
+    const app = new Spiceflow()
+      .get('/items', () => 'items', {
+        query: z.object({ sort: z.string(), limit: z.coerce.number() }),
+      })
+      .post('/create', () => 'created', {
+        query: z.object({ dryRun: z.boolean() }),
+      })
+
+    const safePath = createSafePath(app)
+
+    expect(safePath('/items', { sort: 'name', limit: 10 })).toBe(
+      '/items?sort=name&limit=10',
+    )
+    expect(safePath('/create', { dryRun: true })).toBe(
+      '/create?dryRun=true',
+    )
+
+    // @ts-expect-error - 'order' not in /items query schema
+    safePath('/items', { order: 'asc' })
+
+    // @ts-expect-error - 'verbose' not in /create query schema
+    safePath('/create', { verbose: true })
+  })
+
+  test('works with .route and rejects invalid query keys', () => {
+    const app = new Spiceflow().route({
+      method: 'GET',
+      path: '/api/data',
+      query: z.object({ format: z.string() }),
+      handler: () => 'data',
+    })
+
+    const safePath = createSafePath(app)
+    expect(safePath('/api/data', { format: 'json' })).toBe(
+      '/api/data?format=json',
+    )
+
+    // @ts-expect-error - invalid query key on .route
+    safePath('/api/data', { type: 'csv' })
+
+    // @ts-expect-error - invalid path
+    safePath('/api/other')
+  })
+
+  test('works with basePath and rejects invalid query keys', () => {
+    const app = new Spiceflow({ basePath: '/v2' }).get(
+      '/users',
+      () => 'users',
+      {
+        query: z.object({ active: z.boolean() }),
+      },
+    )
+
+    const safePath = createSafePath(app)
+    expect(safePath('/v2/users', { active: true })).toBe(
+      '/v2/users?active=true',
+    )
+
+    // @ts-expect-error - invalid query key
+    safePath('/v2/users', { status: 'active' })
+
+    // @ts-expect-error - path without basePath prefix
+    safePath('/users')
+  })
+
+  test('without query schema allows arbitrary query', () => {
+    const app = new Spiceflow().get('/free', () => 'ok')
+
+    const safePath = createSafePath(app)
+    expect(
+      safePath('/free', { any: 'value', works: 'here' }),
+    ).toBe('/free?any=value&works=here')
+  })
+
+  test('partial query params are accepted', () => {
+    const app = new Spiceflow().get('/filter', () => 'filter', {
+      query: z.object({ a: z.string(), b: z.string(), c: z.string() }),
+    })
+
+    const safePath = createSafePath(app)
+    expect(safePath('/filter', { a: 'only-a' })).toBe(
+      '/filter?a=only-a',
+    )
+    expect(safePath('/filter', { a: '1', c: '3' })).toBe(
+      '/filter?a=1&c=3',
+    )
+  })
+
+  test('mixed routes with and without query schemas', () => {
+    const app = new Spiceflow()
+      .get('/typed', () => 'typed', {
+        query: z.object({ x: z.string() }),
+      })
+      .get('/untyped', () => 'untyped')
+      .get('/also-typed/:id', ({ params }) => params.id, {
+        query: z.object({ verbose: z.boolean() }),
+      })
+
+    const safePath = createSafePath(app)
+
+    expect(safePath('/typed', { x: 'val' })).toBe('/typed?x=val')
+    expect(safePath('/untyped', { anything: 'goes' })).toBe(
+      '/untyped?anything=goes',
+    )
+    expect(
+      safePath('/also-typed/:id', { id: '1', verbose: true }),
+    ).toBe('/also-typed/1?verbose=true')
+
+    // @ts-expect-error - wrong key on typed route
+    safePath('/typed', { wrong: 'x' })
+
+    // @ts-expect-error - wrong key on also-typed route
+    safePath('/also-typed/:id', { id: '1', wrong: true })
+  })
 })
 
 test('composition with .use() works with state and onError - child app gets same state, errors caught by root', async () => {

package/src/spiceflow.ts

@@ -101,6 +101,7 @@ export class Spiceflow<
   },
   const out ClientRoutes extends RouteBase = {},
   const out RoutePaths extends string = '',
+  const in out RouteQuerySchemas extends Record<string, unknown> = {},
 > {
   private id: number = globalIndex++
   private router: MedleyRouter = new OriginalRouter()
@@ -116,6 +117,7 @@ export class Spiceflow<
     Prefix: '' as BasePath,
     ClientRoutes: {} as ClientRoutes,
     RoutePaths: '' as RoutePaths,
+    RouteQuerySchemas: {} as RouteQuerySchemas,
     Scoped: false as Scoped,
     Singleton: {} as Singleton,
     Definitions: {} as Definitions,
@@ -274,7 +276,8 @@ export class Spiceflow<
     Definitions,
     Metadata,
     ClientRoutes,
-    RoutePaths
+    RoutePaths,
+    RouteQuerySchemas
   > {
     this.defaultState[name] = value
     return this as any
@@ -350,7 +353,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'POST', path, handler: handler, hooks: hook })
 
@@ -400,7 +404,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'GET', path, handler: handler, hooks: hook })
     return this as any
@@ -448,7 +453,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'PUT', path, handler: handler, hooks: hook })
 
@@ -501,7 +507,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     // If options.request is defined, disallow for GET and HEAD (methods that don't support a body)
     const methodsWithNoBody = ['GET', 'HEAD']
@@ -611,7 +618,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'PATCH', path, handler: handler, hooks: hook })
 
@@ -660,7 +668,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'DELETE', path, handler: handler, hooks: hook })
 
@@ -709,7 +718,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'OPTIONS', path, handler: handler, hooks: hook })
 
@@ -758,7 +768,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     for (const method of METHODS) {
       this.add({ method, path, handler: handler, hooks: hook })
@@ -809,7 +820,8 @@ export class Spiceflow<
           }
         }
       >,
-    RoutePaths | JoinPath<BasePath, Path>
+    RoutePaths | JoinPath<BasePath, Path>,
+    RouteQuerySchemas & Record<JoinPath<BasePath, Path>, Schema['query']>
   > {
     this.add({ method: 'HEAD', path, handler: handler, hooks: hook })
 
@@ -832,7 +844,8 @@ export class Spiceflow<
           ? ClientRoutes & NewSpiceflow['_types']['ClientRoutes']
           : ClientRoutes &
               CreateClient<BasePath, NewSpiceflow['_types']['ClientRoutes']>,
-        RoutePaths | NewSpiceflow['_types']['RoutePaths']
+        RoutePaths | NewSpiceflow['_types']['RoutePaths'],
+        RouteQuerySchemas & NewSpiceflow['_types']['RouteQuerySchemas']
       >
   use<const Schema extends RouteSchema>(
     handler: MiddlewareHandler<Schema, Singleton>,
@@ -1399,31 +1412,92 @@ export class Spiceflow<
   }
   safePath<
     const Path extends RoutePaths,
-    const Params extends ExtractParamsFromPath<Path>,
   >(
     path: Path,
-    ...rest: [Params] extends [undefined]
-      ? [] | [params?: Params]
-      : [params: Params]
+    ...rest: [ExtractParamsFromPath<Path>] extends [undefined]
+      ? Path extends keyof RouteQuerySchemas
+        ? unknown extends RouteQuerySchemas[Path]
+          ? [] | [allParams?: Record<string, string | number | boolean>]
+          : [] | [allParams?: Partial<RouteQuerySchemas[Path]>]
+        : [] | [allParams?: Record<string, string | number | boolean>]
+      : Path extends keyof RouteQuerySchemas
+        ? unknown extends RouteQuerySchemas[Path]
+          ? [allParams: ExtractParamsFromPath<Path> & Record<string, string | number | boolean>]
+          : [allParams: MergeParamsAndQuery<ExtractParamsFromPath<Path>, RouteQuerySchemas[Path]>]
+        : [allParams: ExtractParamsFromPath<Path>] | [allParams: ExtractParamsFromPath<Path> & Record<string, string | number | boolean>]
   ): string {
-    let params = (rest.length > 0 ? rest[0] : undefined) as Params | undefined
-    let result = path as string
-
-    // Handle all provided parameters
-    if (params && typeof params === 'object') {
-      Object.entries(params).forEach(([key, value]) => {
-        if (key === '*') {
-          // Replace wildcard
-          result = result.replace(/\*/, String(value))
-        } else {
-          // Replace named parameters as before
-          const regex = new RegExp(`:${key}`, 'g')
-          result = result.replace(regex, String(value))
-        }
-      })
+    return buildSafePath(path, rest[0] as Record<string, any> | undefined)
+  }
+}
+
+type MergeParamsAndQuery<P, Q> = P extends Record<string, any>
+  ? { [K in keyof (P & Omit<Partial<Q>, keyof P>)]: (P & Omit<Partial<Q>, keyof P>)[K] }
+  : Partial<Q>
+
+function buildSafePath(path: string, allParams: Record<string, any> | undefined): string {
+  let result = path
+  if (!allParams || typeof allParams !== 'object') return result
+
+  const pathParamNames = new Set<string>()
+  const paramMatches = path.matchAll(/:(\w+)/g)
+  for (const m of paramMatches) {
+    pathParamNames.add(m[1])
+  }
+  const hasWildcard = path.includes('*')
+  if (hasWildcard) pathParamNames.add('*')
+
+  const searchParams = new URLSearchParams()
+  for (const [key, value] of Object.entries(allParams)) {
+    if (value === undefined || value === null) continue
+    if (key === '*' && hasWildcard) {
+      result = result.replace(/\*/, String(value))
+    } else if (pathParamNames.has(key)) {
+      result = result.replace(new RegExp(`:${key}`, 'g'), String(value))
+    } else {
+      searchParams.set(key, String(value))
     }
+  }
 
-    return result
+  const qs = searchParams.toString()
+  if (qs) result += '?' + qs
+  return result
+}
+
+/**
+ * Create a standalone type-safe path builder. Pass your app instance for automatic
+ * type inference, or call with explicit type params. The app value is not used at runtime.
+ *
+ * ```ts
+ * const app = new Spiceflow()
+ *   .get('/users/:id', handler, { query: z.object({ page: z.number() }) })
+ *
+ * const safePath = createSafePath(app)
+ * safePath('/users/:id', { id: '123', page: 1 })
+ * ```
+ */
+export function createSafePath<
+  const Paths extends string,
+  const QS extends Record<string, unknown>,
+>(
+  _app?: { _types: { RoutePaths: Paths; RouteQuerySchemas: QS } },
+) {
+  return <
+    const Path extends Paths,
+  >(
+    path: Path,
+    ...rest: [ExtractParamsFromPath<Path>] extends [undefined]
+      ? Path extends keyof QS
+        ? unknown extends QS[Path]
+          ? [] | [allParams?: Record<string, string | number | boolean>]
+          : [] | [allParams?: Partial<QS[Path]>]
+        : [] | [allParams?: Record<string, string | number | boolean>]
+      : Path extends keyof QS
+        ? unknown extends QS[Path]
+          ? [allParams: ExtractParamsFromPath<Path> & Record<string, string | number | boolean>]
+          : [allParams: MergeParamsAndQuery<ExtractParamsFromPath<Path>, QS[Path]>]
+        : [allParams: ExtractParamsFromPath<Path>] | [allParams: ExtractParamsFromPath<Path> & Record<string, string | number | boolean>]
+  ): string => {
+    return buildSafePath(path, rest[0] as Record<string, any> | undefined)
   }
 }
 
@@ -1489,7 +1563,7 @@ export function bfs(tree: AnySpiceflow) {
 }
 
 
-export type AnySpiceflow = Spiceflow<any, any, any, any, any, any, any>
+export type AnySpiceflow = Spiceflow<any, any, any, any, any, any, any, any>
 
 export function isZodSchema(value: unknown): value is ZodType {
   return (

package/src/stream.test.ts

@@ -468,7 +468,7 @@ describe('Stream', () => {
     let streamError: Error | undefined
 
     try {
-      const stream = streamSSEResponse(response, (x) => x.data)
+      const stream = streamSSEResponse({ response, map: (x) => x.data })
       for await (const value of stream) {
         values.push(value)
       }