Questions around Value.Default(), Encode(), Decode(), and Cast()

[igniscyan]

First, forgive me if this question comes across as overly novice. I'm learning TypeScript the 'trial by fire' way, so this might be obvious to others but I am really struggling to understand what's going on here.

I switched from Zod to TypeBox due to getting 'exactOptionalPropertyTypes' errors I kept running into with the former, and I really felt like I was doing the wrong thing by disabling it...

I was using Zod (or rather, a boilerplate get started repo I used had been using it) to extend process.env with environment variables I needed. I am doing the same with TypeBox now, without using AJV. This is what I came up with -

import { Type } from "@sinclair/typebox";
import { Value } from "@sinclair/typebox/value"
import "dotenv/config";

/* eslint-disable @typescript-eslint/naming-convention */
// eslint-disable-next-line import/no-unassigned-import

const envSchema = Type.Object({
  DATABASE_URL: Type.String({ default: "to_be_determined" }),
  // REDIS_URL: Type.String({ default: "to_be_determined" }),
  PORT: Type.Number({ default: 8080 }),
  HOST: Type.String({ default: "127.0.0.1" }),
});


export const env = Value.Default(envSchema, process.env);
console.log(process.env);
let testEnv = Value.Cast(envSchema, process.env);
console.log(testEnv);

The first thing I find interesting: If I use Value.Default() on process.env, everything ends up being a string. I know this is how environment variables are stored, but I was actually expecting an error from this. Why does it end up being a string?

The second thing I am trying to figure out: Is how I'm then decoding this correct? I defaulted in a string somehow, and as a result using Value.Decode() causes an error. The only way I could pull those values back out reliably was Value.Cast(), which to me feels a bit like a cheat? Is it a cheat? Is it unsafe?

The third thing I'm wondering: Is there generally a better way to do this? Or am I on the right track here?

[sinclairzx81]

@igniscyan Hi,

You're mostly on the right track. I've put together a quick example of how you might approach configuration / environment loading with TB. It's using the Clone, Clean, Convert, Default and Decode to construct a Parse function.

import { Type, TSchema, StaticDecode } from '@sinclair/typebox'
import { Value } from '@sinclair/typebox/value'

export function Parse<T extends TSchema, R = StaticDecode<T>>(schema: T, value: unknown): R {
  const cloned = Value.Clone(value)                     // clone because value ops can be mutable
  const defaulted = Value.Default(schema, cloned)       // initialize defaults for value
  const converted = Value.Convert(schema, defaulted)    // convert mismatched types for value
  const cleaned = Value.Clean(schema, converted)        // remove unknown properties
  return Value.Decode(schema, cleaned)                  // run decode transforms (optional)
}

// ---------------------------

const Environment = Type.Object({
  DATABASE_URL: Type.String({ default: "to_be_determined" }),
  REDIS_URL: Type.String({ default: "to_be_determined" }),
  PORT: Type.Number({ default: 8080 }),
  HOST: Type.String({ default: '127.0.0.1' }),
})

const environment = Parse(Environment, {
  // environent (required)
  ...process.env, 
  // override (optional)
  DATABASE_URL: 'mongodb://...'
})

console.log(environment)

The above should handle value conversion, default property initialization and provide a means for you override if required. In a typical application, you would pass the Parse function a process.env as a parameter (as above) rather than have the function use process.env internally as this makes things a bit easier to test. Also, I would avoid the use of Cast in this scenario, as Cast was mostly written as a data migration function (it's quite specialized)

Give the above a try, let me know if this helps
Cheers
S

[igniscyan]

@sinclairzx81

Thank you so much for such a thorough example and explanation! I really appreciate it!

I'll take a whack at this after work today and report back. Thanks!