cleanup code and add comments

lib/schema-to-drizzle.js → lib/schema/schema-to-drizzle.js

@@ -1,6 +1,7 @@
 import { text, integer, real, customType } from 'drizzle-orm/sqlite-core'
 
 /**
+Convert a readonly array/object to writeable
 @template T
 @typedef {{ -readonly [P in keyof T]: T[P] }} Writable
  */
@@ -64,6 +65,7 @@ Type returned by integer(columnName)
  */
 
 /**
+Type returned by the `customJson` custom type
 @template {string} TName
 @template {unknown} TData
 @template {boolean} TNotNull
@@ -90,23 +92,6 @@ const customJson = customType({
   },
 })
 
-/**
-@template {object} T
-@template {keyof T} U
-@typedef {
-  T[U] extends null | undefined
-  ? true
-  : import('./types').OptionalKeysOf<T> extends U
-  ? true
-  : false
-} IsOptional
- */
-
-/**
-@template {boolean} T
-@typedef {T extends true ? false : true} Not
- */
-
 /**
 @typedef {import('type-fest').ReadonlyDeep<import('json-schema').JSONSchema7>} JSONSchema7
  */
@@ -124,7 +109,9 @@ const customJson = customType({
  */
 
 /**
-Get the type of a JSONSchema string: array of constants for an enum, otherwise string[]
+Get the type of a JSONSchema string: array of constants for an enum, otherwise
+string[]. Strangeness is to convert it into the format expected by drizzle,
+which results in the correct type for the field from SQLite
 @template {JSONSchema7['enum']} T
 @typedef {
   T extends readonly [string, ...string[]]
@@ -142,7 +129,7 @@ True if JSONSchema object has a default
 /**
 True if JSONSchema value is required
 @template {JSONSchema7WithProps} T
-@template {string} U
+@template {string} U properties key
 @template {JSONSchema7['required']} [V=T['required']]
 @typedef {
   V extends readonly any[]
@@ -152,6 +139,12 @@ True if JSONSchema value is required
  */
 
 /**
+Convert a JSONSchema to a Drizzle Columns map (e.g. parameter for
+`sqliteTable()`). All top-level properties map to SQLite columns, with
+`required` properties marked as `NOT NULL`, and JSONSchema `default` will map to
+SQLite defaults. Any properties that are of type `object` or `array` in the
+JSONSchema will be mapped to a text field, which drizzle will parse and
+stringify. Types for parsed JSON will be derived from MapeoDoc types.
 @template {JSONSchema7WithProps} T
 @template {{ [K in keyof U]?: any }} [TObjectType=any]
 @template {JsonSchema7Properties} [U=T['properties']]
@@ -177,10 +170,13 @@ True if JSONSchema value is required
  */
 
 /**
-@typedef {{ [K in MapeoDoc['schemaName']]: Extract<MapeoDoc, { schemaName: K }> }} SchemaNameMap
- */
+Convert a JSONSchema definition to a Drizzle Columns Map (the parameter for
+`sqliteTable()`).
 
-/**
+**NOTE**: The return of this function is _not_ type-checked (it is coerced with
+`as`, because it's not possible to type-check what this function is doing), but
+the return type _should_ be correct when using this function. TODO: tests for
+the return type of this function.
 @template {JSONSchema7WithProps} TSchema
 @template {TSchema extends { properties: { schemaName: { enum: readonly string[] }}} ? TSchema['properties']['schemaName']['enum'][0] extends MapeoDoc['schemaName'] ? TSchema['properties']['schemaName']['enum'][0] : never : never} TSchemaName
 @template {Extract<MapeoDoc, TSchemaName>} TObjectType