TmMolStar/docs/cif-schemas.md

How CIF schemas work

CIF representation (simplified):

type Block = (name: string) => Category | undefined
type Category = (name: string) => CIFField | undefined
type CIFField = { getNumber: (row) => number, getString: (row) => string }

This is obviously not strongly typed + the "fields" dont know what type they are. To solve this, we create a type to describe what a field contains and how to map it to a column (which is "typed"):

type FieldSchema<T> = { T: T /* remember the type */, createColumn: CIFField => Column<T> }

where column is just a function that for a given row returns a value of T:

type Column<T> = (row: number) => T

Category schema is just an object whose properties are all instances of "field schemas", its "shape" has the type:

type CategorySchema = { [fieldName: string]: FieldSchema<any> }

We can declare our first category "schema":

const my_category = {
  num_field: { T: 0 as number, createColumn: f => f.getNumber }
  str_field: { T: '' as string, createColumn: f => f.getString }
}

Notice that the type of my_category is not specified. Assigning it explictly would hide the actual property names which we do not want. Moreover, the names of the properties must match the names of the fields in the actual category (optionally, a field alias can be added to the field schema).

Given a category schema, we need to construct a type that defines the typed category itself:

type TypedCategory<Schema extends CategorySchema> = { [F in keyof Schema]: Column<Schema[F]['T']> }

In other words, the type TypedCategory has a property of type Column<_> for each property of the schema. Schema[F]['T'] just says: extract type of property called T from property F in Schema. Schema extends CategorySchema says that all properties of Schema must be of type FieldSchema<any>.

Finally, we just define a mapping, toTypedCategory:

function toTypedCategory<Schema extends CategorySchema>(schema: Schema, category: Category): TypedCategory<Shape> {
    const typedCategory: any = {};
    for (const key in Object.keys(schema)) {
        // remember a category is just a function that assigns a Field to a name
        const field = category(key);
        typedCategory[key] = field 
            ? schema[key].createFolumn(field)
            : UndefinedColumn(schema[key].T); // a column that always returns 0 or empty string depending on type
    }
    return typedCategory;
}

This transforms the ''untyped'' Category to some typed category and gives us code-completion for CIF files:

const typed = toTypedCategory(my_category, ...);
typed.n /* shows code completion for num_field */

And that's all there is to it. Extending the types to the "block" level is left as an exercise to the reader.

---

Note: To create a type alias for a category defined this way we can do:

type MyCategory = TypedCategory<typeof my_category>
function makeMyTypedCategory(c: Category): MyCategory { return toTypedCategory(my_category, c); }