@tanstack/start-client-core 1.126.2 → 1.127.0

package/src/createServerFn.ts

@@ -1,17 +1,20 @@
 import { default as invariant } from 'tiny-invariant'
 import { default as warning } from 'tiny-warning'
 import { isNotFound, isRedirect } from '@tanstack/router-core'
-import { mergeHeaders, tsrSerializer } from '@tanstack/router-core/ssr/client'
+import { mergeHeaders } from '@tanstack/router-core/ssr/client'
 import { globalMiddleware } from './registerGlobalMiddleware'
 
+import { startSerializer } from './serializer'
+import type {
+  SerializerParse,
+  SerializerStringify,
+  SerializerStringifyBy,
+} from './serializer'
 import type {
   AnyValidator,
   Constrain,
   Expand,
   ResolveValidatorInput,
-  SerializerParse,
-  SerializerStringify,
-  SerializerStringifyBy,
   Validator,
 } from '@tanstack/router-core'
 import type { JsonResponse } from '@tanstack/router-core/ssr/client'
@@ -737,7 +740,7 @@ setServerFnStaticCache(() => {
         const [cachedResult, readError] = await fs
           .readFile(filePath, 'utf-8')
           .then((c) => [
-            tsrSerializer.parse(c) as {
+            startSerializer.parse(c) as {
               ctx: unknown
               error: any
             },
@@ -767,7 +770,7 @@ setServerFnStaticCache(() => {
       await fs.mkdir(path.dirname(filePath), { recursive: true })
 
       // Store the result with fs
-      await fs.writeFile(filePath, tsrSerializer.stringify(response))
+      await fs.writeFile(filePath, startSerializer.stringify(response))
     },
     fetchItem: async (ctx) => {
       const hash = jsonToFilenameSafeString(ctx.data)
@@ -780,7 +783,7 @@ setServerFnStaticCache(() => {
           method: 'GET',
         })
           .then((r) => r.text())
-          .then((d) => tsrSerializer.parse(d))
+          .then((d) => startSerializer.parse(d))
 
         staticClientCache?.set(url, result)
       }
@@ -802,7 +805,7 @@ export function extractFormDataContext(formData: FormData) {
   }
 
   try {
-    const context = tsrSerializer.parse(serializedContext)
+    const context = startSerializer.parse(serializedContext)
     return {
       context,
       data: formData,

package/src/index.tsx

@@ -1,21 +1,21 @@
 export type {
   DehydratedRouter,
-  ClientExtractedBaseEntry,
-  TsrSsrGlobal as StartSsrGlobal,
-  ClientExtractedEntry,
   JsonResponse,
-  SsrMatch,
-  ClientExtractedPromise,
-  ClientExtractedStream,
-  ResolvePromiseState,
 } from '@tanstack/router-core/ssr/client'
 
-export {
-  hydrate,
-  json,
-  mergeHeaders,
-  tsrSerializer as startSerializer,
-} from '@tanstack/router-core/ssr/client'
+export { hydrate, json, mergeHeaders } from '@tanstack/router-core/ssr/client'
+
+export { startSerializer } from './serializer'
+
+export type {
+  StartSerializer,
+  Serializable,
+  SerializerParse,
+  SerializerParseBy,
+  SerializerStringify,
+  SerializerStringifyBy,
+  SerializerExtensions,
+} from './serializer'
 
 export {
   createIsomorphicFn,
@@ -60,8 +60,6 @@ export {
   globalMiddleware,
 } from './registerGlobalMiddleware'
 export type {
-  ServerFn as FetchFn,
-  ServerFnCtx as FetchFnCtx,
   CompiledFetcherFnOptions,
   CompiledFetcherFn,
   Fetcher,

package/src/serializer.ts

@@ -0,0 +1,206 @@
+import { isPlainObject } from '@tanstack/router-core'
+
+export interface StartSerializer {
+  stringify: (obj: unknown) => string
+  parse: (str: string) => unknown
+  encode: <T>(value: T) => T
+  decode: <T>(value: T) => T
+}
+
+export type SerializerStringifyBy<T, TSerializable> = T extends TSerializable
+  ? T
+  : T extends (...args: Array<any>) => any
+    ? 'Function is not serializable'
+    : { [K in keyof T]: SerializerStringifyBy<T[K], TSerializable> }
+
+export type SerializerParseBy<T, TSerializable> = T extends TSerializable
+  ? T
+  : unknown extends SerializerExtensions['ReadableStream']
+    ? { [K in keyof T]: SerializerParseBy<T[K], TSerializable> }
+    : T extends SerializerExtensions['ReadableStream']
+      ? ReadableStream
+      : { [K in keyof T]: SerializerParseBy<T[K], TSerializable> }
+
+export interface DefaultSerializerExtensions {
+  ReadableStream: unknown
+}
+
+export interface SerializerExtensions extends DefaultSerializerExtensions {}
+
+export type Serializable = Date | undefined | Error | FormData | bigint
+
+export type SerializerStringify<T> = SerializerStringifyBy<T, Serializable>
+
+export type SerializerParse<T> = SerializerParseBy<T, Serializable>
+export const startSerializer: StartSerializer = {
+  stringify: (value: any) =>
+    JSON.stringify(value, function replacer(key, val) {
+      const ogVal = this[key]
+      const serializer = serializers.find((t) => t.stringifyCondition(ogVal))
+
+      if (serializer) {
+        return serializer.stringify(ogVal)
+      }
+
+      return val
+    }),
+  parse: (value: string) =>
+    JSON.parse(value, function parser(key, val) {
+      const ogVal = this[key]
+      if (isPlainObject(ogVal)) {
+        const serializer = serializers.find((t) => t.parseCondition(ogVal))
+
+        if (serializer) {
+          return serializer.parse(ogVal)
+        }
+      }
+
+      return val
+    }),
+  encode: (value: any) => {
+    // When encoding, dive first
+    if (Array.isArray(value)) {
+      return value.map((v) => startSerializer.encode(v))
+    }
+
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [
+          key,
+          startSerializer.encode(v),
+        ]),
+      )
+    }
+
+    const serializer = serializers.find((t) => t.stringifyCondition(value))
+    if (serializer) {
+      return serializer.stringify(value)
+    }
+
+    return value
+  },
+  decode: (value: any) => {
+    // Attempt transform first
+    if (isPlainObject(value)) {
+      const serializer = serializers.find((t) => t.parseCondition(value))
+      if (serializer) {
+        return serializer.parse(value)
+      }
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((v) => startSerializer.decode(v))
+    }
+
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [
+          key,
+          startSerializer.decode(v),
+        ]),
+      )
+    }
+
+    return value
+  },
+}
+const createSerializer = <TKey extends string, TInput, TSerialized>(
+  key: TKey,
+  check: (value: any) => value is TInput,
+  toValue: (value: TInput) => TSerialized,
+  fromValue: (value: TSerialized) => TInput,
+) => ({
+  key,
+  stringifyCondition: check,
+  stringify: (value: any) => ({ [`$${key}`]: toValue(value) }),
+  parseCondition: (value: any) => Object.hasOwn(value, `$${key}`),
+  parse: (value: any) => fromValue(value[`$${key}`]),
+})
+// Keep these ordered by predicted frequency
+// Make sure to keep DefaultSerializable in sync with these serializers
+// Also, make sure that they are unit tested in serializer.test.tsx
+const serializers = [
+  createSerializer(
+    // Key
+    'undefined',
+    // Check
+    (v): v is undefined => v === undefined,
+    // To
+    () => 0,
+    // From
+    () => undefined,
+  ),
+  createSerializer(
+    // Key
+    'date',
+    // Check
+    (v): v is Date => v instanceof Date,
+    // To
+    (v) => v.toISOString(),
+    // From
+    (v) => new Date(v),
+  ),
+  createSerializer(
+    // Key
+    'error',
+    // Check
+    (v): v is Error => v instanceof Error,
+    // To
+    (v) => ({
+      ...v,
+      message: v.message,
+      stack: process.env.NODE_ENV === 'development' ? v.stack : undefined,
+      cause: v.cause,
+    }),
+    // From
+    (v) => Object.assign(new Error(v.message), v),
+  ),
+  createSerializer(
+    // Key
+    'formData',
+    // Check
+    (v): v is FormData => v instanceof FormData,
+    // To
+    (v) => {
+      const entries: Record<
+        string,
+        Array<FormDataEntryValue> | FormDataEntryValue
+      > = {}
+      v.forEach((value, key) => {
+        const entry = entries[key]
+        if (entry !== undefined) {
+          if (Array.isArray(entry)) {
+            entry.push(value)
+          } else {
+            entries[key] = [entry, value]
+          }
+        } else {
+          entries[key] = value
+        }
+      })
+      return entries
+    },
+    // From
+    (v) => {
+      const formData = new FormData()
+      Object.entries(v).forEach(([key, value]) => {
+        if (Array.isArray(value)) {
+          value.forEach((val) => formData.append(key, val))
+        } else {
+          formData.append(key, value)
+        }
+      })
+      return formData
+    },
+  ),
+  createSerializer(
+    // Key
+    'bigint',
+    // Check
+    (v): v is bigint => typeof v === 'bigint',
+    // To
+    (v) => v.toString(),
+    // From
+    (v) => BigInt(v),
+  ),
+] as const

package/src/tests/serializer.test.tsx

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest'
+import { startSerializer as serializer } from '../serializer'
+
+describe('transformer.stringify', () => {
+  it('should stringify dates', () => {
+    const date = new Date('2021-08-19T20:00:00.000Z')
+    expect(serializer.stringify(date)).toMatchInlineSnapshot(`
+      "{"$date":"2021-08-19T20:00:00.000Z"}"
+    `)
+  })
+
+  it('should stringify undefined', () => {
+    expect(serializer.stringify(undefined)).toMatchInlineSnapshot(
+      `"{"$undefined":0}"`,
+    )
+  })
+
+  it('should stringify object foo="bar"', () => {
+    expect(serializer.stringify({ foo: 'bar' })).toMatchInlineSnapshot(`
+      "{"foo":"bar"}"
+    `)
+  })
+
+  it('should stringify object foo=undefined', () => {
+    expect(serializer.stringify({ foo: undefined })).toMatchInlineSnapshot(
+      `"{"foo":{"$undefined":0}}"`,
+    )
+  })
+
+  it('should stringify object foo=Date', () => {
+    const date = new Date('2021-08-19T20:00:00.000Z')
+    expect(serializer.stringify({ foo: date })).toMatchInlineSnapshot(`
+      "{"foo":{"$date":"2021-08-19T20:00:00.000Z"}}"
+    `)
+  })
+
+  it('should stringify empty FormData', () => {
+    const formData = new FormData()
+    expect(serializer.stringify(formData)).toMatchInlineSnapshot(
+      `"{"$formData":{}}"`,
+    )
+  })
+
+  it('should stringify FormData with key-value pairs of foo="bar",name="Sean"', () => {
+    const formData = new FormData()
+    formData.append('foo', 'bar')
+    formData.append('name', 'Sean')
+    expect(serializer.stringify(formData)).toMatchInlineSnapshot(
+      `"{"$formData":{"foo":"bar","name":"Sean"}}"`,
+    )
+  })
+  it('should stringify FormData with multiple values for the same key', () => {
+    const formData = new FormData()
+    formData.append('foo', 'bar')
+    formData.append('foo', 'baz')
+    expect(serializer.stringify(formData)).toMatchInlineSnapshot(
+      `"{"$formData":{"foo":["bar","baz"]}}"`,
+    )
+  })
+
+  it('should stringify bigint', () => {
+    const bigint = BigInt('9007199254740992')
+    expect(serializer.stringify(bigint)).toMatchInlineSnapshot(
+      `"{"$bigint":"9007199254740992"}"`,
+    )
+  })
+  it('should stringify object foo=bigint', () => {
+    const bigint = BigInt('9007199254740992')
+    expect(serializer.stringify({ foo: bigint })).toMatchInlineSnapshot(
+      `"{"foo":{"$bigint":"9007199254740992"}}"`,
+    )
+  })
+})
+
+describe('transformer.parse', () => {
+  it('should parse dates', () => {
+    const date = new Date('2021-08-19T20:00:00.000Z')
+    const str = serializer.stringify(date)
+    expect(serializer.parse(str)).toEqual(date)
+    expect(serializer.parse(str) instanceof Date).toBe(true)
+  })
+
+  it('should parse undefined', () => {
+    const str = serializer.stringify(undefined)
+    expect(serializer.parse(str)).toBeUndefined()
+  })
+
+  it('should parse object foo="bar"', () => {
+    const obj = { foo: 'bar' }
+    const str = serializer.stringify(obj)
+    expect(serializer.parse(str)).toEqual(obj)
+  })
+
+  it('should parse object foo=undefined', () => {
+    const obj = { foo: undefined }
+    const str = serializer.stringify(obj)
+    expect(serializer.parse(str)).toEqual(obj)
+  })
+
+  it('should parse object foo=Date', () => {
+    const date = new Date('2021-08-19T20:00:00.000Z')
+    const obj = { foo: date }
+    const str = serializer.stringify(obj)
+    expect(serializer.parse(str)).toEqual(obj)
+  })
+
+  it('should parse empty FormData', () => {
+    const formData = new FormData()
+    const str = serializer.stringify(formData)
+    const parsed = serializer.parse(str) as FormData
+    expect(parsed).toBeInstanceOf(FormData)
+    expect([...parsed.entries()]).toEqual([])
+  })
+
+  it('should parse FormData with key-value pairs of foo="bar",name="Sean"', () => {
+    const formData = new FormData()
+    formData.append('foo', 'bar')
+    formData.append('name', 'Sean')
+    const str = serializer.stringify(formData)
+    const parsed = serializer.parse(str) as FormData
+    expect(parsed).toBeInstanceOf(FormData)
+    expect([...parsed.entries()]).toEqual([
+      ['foo', 'bar'],
+      ['name', 'Sean'],
+    ])
+  })
+  it('should parse FormData with multiple values for the same key', () => {
+    const formData = new FormData()
+    formData.append('foo', 'bar')
+    formData.append('foo', 'baz')
+    const str = serializer.stringify(formData)
+    const parsed = serializer.parse(str) as FormData
+    expect(parsed).toBeInstanceOf(FormData)
+    expect([...parsed.entries()]).toEqual([
+      ['foo', 'bar'],
+      ['foo', 'baz'],
+    ])
+  })
+
+  it('should parse bigint', () => {
+    const bigint = BigInt('9007199254740992')
+    const str = serializer.stringify(bigint)
+    expect(serializer.parse(str)).toEqual(bigint)
+  })
+  it('should parse object foo=bigint', () => {
+    const bigint = BigInt('9007199254740992')
+    const obj = { foo: bigint }
+    const str = serializer.stringify(obj)
+    expect(serializer.parse(str)).toEqual(obj)
+  })
+})