How do you do that thin you (sinclair) do?

[jessekrubin]

Hello Sinclair!

Long time to talk! Hope you are doing well! I am back with a few questions for you.

• How do you write/maintain your READMEs? I have now used typebox, smoke, hammer and (your latest) carbon; all have excellent READMEs and I was wondering how do you write/maintain your READMEs, your docs and your changelogs? You are clearly doing something correct!
• Do you have a blog? if so where is it at? if not, you should 100% have a blog; I would/will read your blog!
• In various places around your libs (namely typebox) you use Symbols (eg [Hint]). I am curious how you recommend using symbols, how you recommend NOT using symbols, and if/when/why one should be using symbols.
• typebox questions:
  • Will typebox ever have its own docs website?
  • Will the TypeCompiler ever support coercion? Curious on your thoughts!
  • Will the TypeCompiler ever get an equiv to fast-json-stringify?
  • Will typebox ever get an Enum that uses {"enum": ["red", "amber", "green", null, 42]} instead of the anyOf combo?

Thanks so much!
Regards,
jesse

PS: don't forget to sleep!

[sinclairzx81]

@jessekrubin Heya, sorry for the delay in reply.

How do you write/maintain your READMEs? I have now used typebox, smoke, hammer and (your latest) carbon; all have excellent READMEs and I was wondering how do you write/maintain your READMEs, your docs and your changelogs? You are clearly doing something correct!

I mostly just author them manually. README's usually get updated on minor revisions where I try to provide high level code examples demonstrating new features while maintaining copy written for older features to ensure consistency. I spend quite a bit of time going through each section of the README ensuring what's written is consistent across each section and as concisely written as possible (I assume most readers prefer code examples with small supplementary copy explaining the code)

I don't think I do anything particularly special with the READMEs I manage. I mostly just write what I'd like to see documentation wise :)

Do you have a blog? if so where is it at? if not, you should 100% have a blog; I would/will read your blog!

Unfortunately, I don't keep a blog (mostly because I don't have much time to write blog content). To be honest I wouldn't know what to write even if I did have one!

In various places around your libs (namely typebox) you use Symbols (eg [Hint]). I am curious how you recommend using symbols, how you recommend NOT using symbols, and if/when/why one should be using symbols.

TypeBox uses symbols for a variety of reasons (which is quite a lengthy discussion). But are generally used in TypeBox for the following reasons:

• Prevent name collision for intrinsic properties (Kind, Hint, Optional, Readonly, Recursive, etc)
• Ensure version parity where multiple installed versions of TypeBox will conflict if combining types from different versions.
• Ensure intrinsic properties are omitted on serialization (Symbols can't be serialized as Json)
• To optimize compilation on known schematics (which full schematics can be derived from a Kind descriptor)
• To provide a differentiation mechanism for types with the same schematics (any and unknown are defined as {})

In terms of scenarios where you might use Symbols, mostly they are used to ensure value uniqueness and that a value can be distinctly differentiable from another value. There's quite a few places where this is useful, but in terms of common usage, you may see Symbols assigned to objects where the Symbol describes some attribute or behavior of an object that is leveraged by auxiliary infrastructure, and where the infrastructure is dependent on that attribute being uniquely distinguishable.

This is a bit of an abstract description, but the following shows the concept in practice.

const T = Type.String()          // { [Kind]: 'String' } // unique intrinsic symbol

Value.Check(T, ...)              // symbol read via dependent infrastructure...

class Iter {
  * [Symbol.iterator]() {        // unique intrinsic symbol
      yield 1
      yield 2
      yield 3
  }
}

for(const value of new Iter()) { // symbol invoked via dependent infrastructure...
  console.log(value)
}

Will typebox ever have its own docs website?

Hopefully one day :)

Will the TypeCompiler ever support coercion? Curious on your thoughts!

Uncertain. Currently the TypeCompiler only produces a very fast boolean result and nothing more. Most of the advanced value handling is done dynamically via the Value.* module (and where Value.Convert handles coercion). However should the Value.* fully stabilize, there may be potential there to optimize dynamic handling of values through JIT compilation. As TypeBox prefers users programmatically create value pipelines over configuration, should the compiler be enhanced to support JIT Value.* processing, it would need to support a similar programmatic model. This would be an area of research for the future.

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

// TODO: Figure out a way to compile the following routines
function Parse<T extends TSchema, R = StaticDecode<T>>(schema: T, value: unknown): R {
  const converted = Value.Convert(schema, value)
  const cleaned = Value.Clean(schema, converted)
  const defaulted = Value.Default(schema, cleaned)
  return Value.Decode(schema, defaulted)
}

Will the TypeCompiler ever get an equiv to fast-json-stringify

I feel serialization (encode and decode) is a domain unto itself and probably best handled by other libraries.

Will typebox ever get an Enum that uses {"enum": ["red", "amber", "green", null, 42]} instead of the anyOf combo?

Yes, eventually :) (stay tuned)

Hope this brings some insights!
Cheers
S