[Feature Request] Split schema into selectSchema, insertSchema, updateSchema for granular control

[kvnwolf]

Problem

Currently, the schema property is used for both validation (on mutations) and type inference, but transformations are not applied to data coming from sync (e.g., ElectricSQL).

This was previously reported in #396 - the schema transforms work for insert/update but not for data received from the sync stream.

Example:

const schema = z.object({
  id: z.string(),
  createdAt: z.string().transform(val => new Date(val)), // Transform string → Date
});

// Expected: createdAt is Date
// Actual: createdAt is still string (from Electric sync)

Proposal

Replace the single schema property with granular schemas:

electricCollectionOptions({
  // Schema for transforming/validating data FROM sync (select/read)
  selectSchema: z.object({
    id: z.string(),
    message: z.string(),
    createdAt: z.string().transform(val => new Date(val)),
  }),
  
  // Schema for validating data on insert (with defaults)
  insertSchema: z.object({
    id: z.string().default(() => crypto.randomUUID()),
    message: z.string().min(1),
    createdAt: z.date().default(() => new Date()),
  }),
  
  // Schema for validating data on update (optional, falls back to insertSchema)
  updateSchema: z.object({
    message: z.string().min(1).optional(),
  }),
})

Benefits

1. selectSchema would actually transform sync data (solving Types are incorrect for schema, where input & output are different #396)
2. insertSchema can have stricter validation (required fields, defaults)
3. updateSchema can have partial/optional fields for updates
4. Clear separation of concerns
5. Similar pattern to PowerSync's deserializationSchema

Alternative

If splitting into 3 schemas is too complex, at minimum add deserializationSchema (like PowerSync has) to transform data from the sync stream.

[KyleAMathews]

The electric client has ways to apply transforms — https://electric-sql.com/docs/api/clients/typescript#parsing-and-custom-parsing btw.

[kvnwolf]

Should this be implemented within the createCollection function? Also, what do you think about adding different schemas for different operation types? It can be helpful for applying transforms e.g. for computed fields.

[KyleAMathews]

Did you read this? https://tanstack.com/db/latest/docs/guides/schemas

[joshuadutton]

@KyleAMathews jumping in here because I have similar questions. I have ready about transforms using Zod, which seems to apply well for cases where input objects don't require certain fields. But I'm also dealing with a case where I'm using a GraphQL API and the data returned includes relationships, which I don't want present in my input objects. I'm not very familiar with Zod transforms; does it even support a case like that?

Apart from the support with transforms, my opinion is that the API would be more straight forward and easier to learn to just support multiple schemas. That said, the complexity on your end may be untenable (let me know).

Speaking of my relational GraphQL data. It's working well enough for me right now, but I may move away from relational data directly from my API once the hierarchical collection support is done (#288). It may be much easier to sync data by separating it out.