trailbase-db-collection: optional `parse` and `serialize` arguemtns crash module if not provided

[MentalGear]

• I've validated the bug against the latest version of DB packages

Bug Report: trailbase-db-collection Documentation Issue

Summary

The @tanstack/trailbase-db-collection package documentation incorrectly marks parse and serialize properties as optional in the TrailBaseCollectionConfig interface, but the implementation requires these properties to be defined (even if empty) to avoid runtime errors.

Problem Description

Issue

When using trailBaseCollectionOptions without providing parse and serialize properties, the application crashes with:

Uncaught (in promise) TypeError: can't access property "some_collection", c is undefined

Root Cause

In the trailbase.ts file, the convert function (line 62) and convertPartial function (line 120) expect the conversions parameter to be defined, but when parse and serialize are not provided in the configuration, they become undefined, causing the error when trying to access properties on the undefined object.

Code Location

• File: node_modules/@tanstack/trailbase-db-collection/src/trailbase.ts
• Functions: convert() (line 62), convertPartial() (line 120)
• Error path: convert → parse → initialFetch → trailBaseCollectionOptions

Reproduction Steps

1. Create a collection using trailBaseCollectionOptions without parse and serialize properties:

trailBaseCollectionOptions({
    id: 'some_collection',
    recordApi: trailbase.records('some_collection') as any,
    getKey: (item) => item.id,
    schema: someSchema,
    // Missing parse and serialize properties
})

2. Attempt to fetch data from the collection
3. Error occurs when the convert function is called with undefined conversions

Expected Behavior

According to the documentation/type definitions, parse and serialize should be optional. If not provided, the library should handle this gracefully by using identity conversions (returning the input as-is).

Current Behavior

The application crashes with a TypeError when trying to access properties on the undefined conversions object.

Suggested Fix

Option 1: Make parse/serialize truly optional

Modify the convert and convertPartial functions to handle undefined conversions:

function convert<InputType, OutputType>(
  conversions: Conversions<InputType, OutputType> | undefined,
  input: InputType
): OutputType {
  const c = conversions ?? {}
  // ... rest of the function
}

Option 2: Update documentation

If the properties are required, update the documentation/type definitions to reflect this requirement.

Option 3: Provide default empty objects

Modify the trailBaseCollectionOptions function to provide default empty objects:

export function trailBaseCollectionOptions<TItem, TRecord, TKey>(
  config: TrailBaseCollectionConfig<TItem, TRecord, TKey>
): CollectionConfig<TItem, TKey> & { utils: TrailBaseCollectionUtils } {
  const parseConfig = config.parse ?? {}
  const serializeConfig = config.serialize ?? {}

  const parse = (record: TRecord) =>
    convert<TRecord, TItem>(parseConfig, record)
  // ... rest of the function
}

Workaround

Users must provide empty objects for parse and serialize even when no conversions are needed:

trailBaseCollectionOptions({
    id: 'some_collection',
    recordApi: trailbase.records('some_collection') as any,
    getKey: (item) => item.id,
    schema: someSchema,
    parse: {},      // Required workaround
    serialize: {},  // Required workaround
})

Impact

This issue affects all users of the @tanstack/trailbase-db-collection package who follow the documented API and omit the parse and serialize properties when no field conversions are needed.

Additional Context

• Package version: @tanstack/trailbase-db-collection@0.1.55
• Related to: @tanstack/db integration with TrailBase
• Error properties observed: "some_collection", (varies based on the record being processed)

[MentalGear]

Pinging the main author here @ignatz

[ignatz]

Thanks and thanks for pining me, I'll take a look.

[ignatz]

Reproduction Steps

1. Create a collection using `trailBaseCollectionOptions` without `parse` and `serialize` properties:

trailBaseCollectionOptions({
id: 'some_collection',
recordApi: trailbase.records('some_collection') as any,
getKey: (item) => item.id,
schema: someSchema,
// Missing parse and serialize properties
})

2. Attempt to fetch data from the collection

3. Error occurs when the `convert` function is called with `undefined` conversions

Disclaimer, I'm type gymnast but not a TS expert, so I'd love to learn...

I had a look. At first I was puzzled since TrailbaseCollectionConfig most certainly does not declare parse/serialize as optional:

db/packages/trailbase-db-collection/src/trailbase.ts

Lines 100 to 101 in 997fbae

	parse: Conversions<TRecord, TItem>
	serialize: Conversions<TItem, TRecord>

.

However, it also doesn't expect a schema property. It looks like the unexpected extra argument throws the TS compiler/linter off enough that it doesn't complain about missing arguments? 🤷‍♀️
At least for me, if I remove schema: someSchema I'm told to provide schema and or parse.

I do think that there's maybe an opportunity to actually make the arguments optional when no conversation is needed as opposed to having to specify parse = {} 🤷‍♀️ .

I'll send a PR to remove the misleading argument from the examples