How can I use codecs with a potentially unsafe data type?

[0-CAT]

Let's say I have a database (SQLite) that I am fetching data from. The schema is simple:

CREATE TABLE IF NOT EXISTS "test" (
	"id"	INTEGER,
	"label"	TEXT UNIQUE,
	"date"	TEXT,
	PRIMARY KEY("id" AUTOINCREMENT)
);

On the service side, I want to read this row and get a strongly typed object from it. Normally, I'd just do something like this:

However, let's say that I want to use a codec like the one in the documentation that transforms my ISO date text field into a Date object. As mentioned in the documentation, this works fine if you already have the object strongly typed when it is passed to decode. However, seemingly by design, you can't do that if the object is of type unknown—which my row is (since we don't know the data shape from the query yet).

As a result, this doesn't work:

And, since my conversion is using two different data types (string and Date), I can't do this, either:

I had hoped that codecs would help me avoid using two schemas + a conversion method, but so far it doesn't seem like it can. Is this an expected limitation of codecs? What is the ideal way to handle this situation?

[dosubot[bot]]

Yes, this is an intentional and documented aspect of Zod codecs: the .decode() method expects a strongly typed input, not unknown. This means you can't safely decode a raw database row (which is unknown) directly with a codec. Instead, the recommended approach is to first validate and parse the unknown data using a schema, then apply your transformation (e.g., with a codec or a custom function). This often means you need two schemas (one for the raw data, one for the transformed data) or a schema plus a conversion step—this is the expected and supported pattern in Zod.

Here's a concise example for your use case:

// 1. Schema for raw DB row (all fields as strings)
const dbRowSchema = z.object({
  id: z.number(),
  label: z.string(),
  date: z.string(), // ISO string from DB
});

// 2. Codec for date transformation
const stringToDate = z.codec(
  z.string(),
  z.date(),
  {
    decode: (iso) => new Date(iso),
    encode: (date) => date.toISOString(),
  }
);

// 3. Schema for your strongly typed object
const appRowSchema = z.object({
  id: z.number(),
  label: z.string(),
  date: stringToDate, // Date object in your app
});

// Usage:
const rawRow = await fetchRowFromDb(); // unknown
const parsedRow = dbRowSchema.parse(rawRow);
const appRow = appRowSchema.parse({ ...parsedRow, date: parsedRow.date });
// Now appRow.date is a Date object

Alternatively, you can use .preprocess() or .transform() for unidirectional transformations if you don't need bidirectional encoding/decoding.

For more details, see the official Zod codecs documentation and the API reference. This pattern is also discussed in related issues.

If this answers your question, feel free to close the issue! If you need more details or examples, let me know.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}