@strictly/define 0.0.1

package/types/builders.ts

@@ -0,0 +1,284 @@
+import {
+  type IsFieldReadonly,
+} from '@strictly/base'
+import {
+  type ListTypeDef,
+  type LiteralTypeDef,
+  type ObjectFieldKey,
+  type ObjectTypeDef,
+  type RecordKeyType,
+  type RecordTypeDef,
+  type Type,
+  type TypeDef,
+  TypeDefType,
+  type UnionKey,
+  type UnionTypeDef,
+} from './definitions'
+
+class TypeDefBuilder<T extends TypeDef> implements Type<T> {
+  constructor(readonly definition: T) {
+  }
+
+  // returns just the relevant types, which can help typescript
+  // from complaining about infinitely deep data structures
+  get narrow(): Type<T> {
+    return {
+      definition: this.definition,
+    }
+  }
+}
+
+class LiteralTypeDefBuilder<T> extends TypeDefBuilder<LiteralTypeDef<T>> {
+}
+
+class ListTypeDefBuilder<
+  T extends ListTypeDef,
+> extends TypeDefBuilder<T> {
+  readonly(): ListTypeDefBuilder<{
+    readonly type: TypeDefType.List,
+    readonly elements: T['elements'],
+  }> {
+    return this
+  }
+}
+
+class RecordTypeDefBuilder<T extends RecordTypeDef> extends TypeDefBuilder<T> {
+  partial(): IsFieldReadonly<T, 'valueTypeDef'> extends true ? RecordTypeDefBuilder<{
+      readonly type: TypeDefType.Record,
+      readonly keyPrototype: T['keyPrototype'],
+      readonly valueTypeDef: T['valueTypeDef'] | undefined,
+    }>
+    : RecordTypeDefBuilder<{
+      readonly type: TypeDefType.Record,
+      readonly keyPrototype: T['keyPrototype'],
+      valueTypeDef: T['valueTypeDef'] | undefined,
+    }>
+  {
+    return this
+  }
+
+  readonly(): RecordTypeDefBuilder<{
+    readonly type: TypeDefType.Record,
+    readonly keyPrototype: T['keyPrototype'],
+    readonly valueTypeDef: T['valueTypeDef'],
+  }> {
+    return this
+  }
+}
+
+class ObjectTypeDefBuilder<
+  Fields extends Readonly<Record<ObjectFieldKey, TypeDef>> = {},
+> extends TypeDefBuilder<
+  ObjectTypeDef<Fields>
+> {
+  set<
+    Name extends string,
+    T extends TypeDef,
+  >(
+    name: Name,
+    { definition: typeDef }: Type<T>,
+  ): ObjectTypeDefBuilder<
+    Fields & Record<Name, T>
+  > {
+    const newFields = {
+      [name]: typeDef,
+    }
+    // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+    return new ObjectTypeDefBuilder<
+      Fields & Record<Name, T>
+    >({
+      type: TypeDefType.Object,
+      fields: {
+        ...this.definition.fields,
+        ...newFields,
+      },
+    })
+  }
+
+  setReadonly<
+    Name extends string,
+    T extends TypeDef,
+  >(
+    name: Name,
+    { definition: typeDef }: Type<T>,
+  ): ObjectTypeDefBuilder<
+    Fields & Readonly<Record<Name, T>>
+  > {
+    const newFields = {
+      [name]: typeDef,
+    }
+    // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+    return new ObjectTypeDefBuilder<
+      Fields & Readonly<Record<Name, T>>
+    >({
+      type: TypeDefType.Object,
+      fields: {
+        ...this.definition.fields,
+        ...newFields,
+      },
+    })
+  }
+
+  setOptional<
+    Name extends string,
+    T extends TypeDef,
+  >(
+    name: Name,
+    { definition: typeDef }: Type<T>,
+  ): ObjectTypeDefBuilder<
+    Fields & Partial<Record<Name, T>>
+  > {
+    const newFields = {
+      [name]: typeDef,
+    }
+    // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+    return new ObjectTypeDefBuilder<
+      Fields & Partial<Record<Name, T>>
+    >({
+      type: TypeDefType.Object,
+      fields: {
+        ...this.definition.fields,
+        ...newFields,
+      },
+    })
+  }
+
+  setReadonlyOptional<
+    Name extends string,
+    T extends TypeDef,
+  >(
+    name: Name,
+    { definition: typeDef }: Type<T>,
+  ): ObjectTypeDefBuilder<
+    Fields & Partial<Readonly<Record<Name, T>>>
+  > {
+    const newFields = {
+      [name]: typeDef,
+    }
+    // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+    return new ObjectTypeDefBuilder<
+      Fields & Partial<Readonly<Record<Name, T>>>
+    >({
+      type: TypeDefType.Object,
+      fields: {
+        ...this.definition.fields,
+        ...newFields,
+      },
+    })
+  }
+}
+
+class UnionTypeDefBuilder<
+  D extends string | null,
+  U extends Record<UnionKey, TypeDef>,
+> extends TypeDefBuilder<
+  UnionTypeDef<
+    D,
+    U
+  >
+> {
+  add<
+    K extends Exclude<UnionKey, keyof U>,
+    T extends TypeDef,
+  >(
+    k: K,
+    {
+      definition: typeDef,
+    }: Type<T>,
+  ): UnionTypeDefBuilder<D, Readonly<Record<K, T>> & U> {
+    const {
+      discriminator,
+      unions,
+    } = this.definition
+    return new UnionTypeDefBuilder<D, Readonly<Record<K, T>> & U>(
+      {
+        type: TypeDefType.Union,
+        discriminator: discriminator,
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        unions: {
+          ...unions,
+          [k]: typeDef,
+        } as Readonly<Record<K, T>> & U,
+      },
+    )
+  }
+}
+
+export function literal<T>(value?: [T]): LiteralTypeDefBuilder<T> {
+  return new LiteralTypeDefBuilder({
+    type: TypeDefType.Literal,
+    valuePrototype: value!,
+  })
+}
+
+export const stringType = literal<string>()
+export const numberType = literal<number>()
+export const booleanType = literal<boolean>()
+export const nullType = literal([null])
+
+export function nullable<T extends TypeDef>(nonNullable: Type<T>): UnionTypeDefBuilder<null, {
+  readonly ['0']: T,
+  readonly ['1']: LiteralTypeDef<null>,
+}> {
+  return new UnionTypeDefBuilder(
+    {
+      type: TypeDefType.Union,
+      discriminator: null,
+      unions: {
+        ['0']: nonNullable.definition,
+        ['1']: nullType.definition,
+      },
+    },
+  )
+}
+
+export function list<T extends TypeDef>(elements: Type<T>): ListTypeDefBuilder<{
+  readonly type: TypeDefType.List,
+  elements: T,
+}> {
+  // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+  return new ListTypeDefBuilder<ListTypeDef<T>>({
+    type: TypeDefType.List,
+    elements: elements.definition,
+  })
+}
+
+export function record<
+  V extends Type,
+  // NOTE if we swap these generics and the caller forgets to supply the second one (so the Type)
+  // TSC will freeze
+  K extends RecordKeyType,
+>({ definition: typeDef }: V) {
+  return new RecordTypeDefBuilder<{
+    readonly type: TypeDefType.Record,
+    readonly keyPrototype: K,
+    valueTypeDef: V['definition'],
+  }>({
+    type: TypeDefType.Record,
+    // eslint-disable-next-line no-undefined
+    keyPrototype: undefined!,
+    valueTypeDef: typeDef,
+  })
+}
+
+export function object(): ObjectTypeDefBuilder<{}> {
+  // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+  return new ObjectTypeDefBuilder<{}>({
+    type: TypeDefType.Object,
+    fields: {},
+  })
+}
+
+export function union<D extends null>(): UnionTypeDefBuilder<D, {}>
+export function union<D extends string>(discriminator: D): UnionTypeDefBuilder<D, {}>
+export function union<D extends string | null>(discriminator?: D): UnionTypeDefBuilder<D, {}> {
+  // have to explicitly supply types as TS will infinitely recurse trying to infer them!
+  return new UnionTypeDefBuilder<D, {}>(
+    {
+      type: TypeDefType.Union,
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      discriminator: (discriminator ?? null) as D,
+      unions: {},
+    },
+  )
+}

package/types/definitions.ts

@@ -0,0 +1,106 @@
+// NOTE: this file, in conjunction with the types that derive information from these types, pushes the
+// Typescript compiler to its absolute limit. It tends to be a death of 1000 cuts so no individual feature
+// breaks it. When combined they hit some threshold (memory? performance? time?) beyond which the compiler
+// gives up. To avoid problems try to follow these guidelines
+// 1. Keep types as simple as possible.
+// If you find yourself having to unwrap a bunch of boolean flags (for example) you're probably going to encounter issues
+// 2. Only expose externally, and pass internally, the absolute minimum information information you need
+// TS tends to get overwhelmed, where you can, narrow the types that are being returned to just the information
+// the caller needs
+// 3. Take advantage of helper functions to hide complexity/fragility from client code
+// 4. Manually unroll complex operations
+// Typescript can choke on things like the below, however you can manually do a full implementation where you
+// check each type and return the appropriate value, and that seems to work.
+// ```
+// type HomogeneousFattenedValue<T extends TypeDef, V> = { [K in keyof FlattenedOf<T>]?: V }
+// ```
+// 5. Use longhand { [s: string]: number } instead of Record<string, number> when doing transformations and
+// defining types
+
+export type Type<T extends TypeDef = TypeDef> = {
+  readonly definition: T,
+}
+
+export type TypeDef =
+  | LiteralTypeDef
+  | ListTypeDef
+  | RecordTypeDef
+  | ObjectTypeDef
+  | UnionTypeDef
+
+export enum TypeDefType {
+  Literal = 1,
+  List,
+  Record,
+  Object,
+  Union,
+}
+
+// used to avoid TS complaining about circular references
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyTypeDef = any
+
+// literal
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type LiteralTypeDef<V = any> = {
+  readonly type: TypeDefType.Literal,
+  readonly valuePrototype: [V],
+}
+
+// list
+export type ListTypeDef<
+  E extends TypeDef = AnyTypeDef,
+> = {
+  readonly type: TypeDefType.List,
+  // readonly is inherited by the output
+  readonly elements: E,
+}
+
+// map
+export type RecordKeyType = string | number
+
+// might be able to combine map and list into a single "homogeneous" type def with an implementation
+// hint, which might help with performance
+export type RecordTypeDef<
+  K extends RecordKeyType = RecordKeyType,
+  // if `V` includes `undefined` the map is partial
+  V extends TypeDef | undefined = AnyTypeDef,
+> = {
+  readonly type: TypeDefType.Record,
+  // never actually populate
+  readonly keyPrototype: K,
+  // readonly is inherited by the output
+  readonly valueTypeDef: V,
+}
+
+// structured type
+// could be replaced with a map and an intersection
+export type ObjectFieldKey = string | number
+
+// NOTE we use the `readonly` and `?` (partial) status of these field definitions
+// to describe the same attributes of the fields
+export type ObjectTypeDefFields = {
+  [Key: ObjectFieldKey]: AnyTypeDef,
+}
+
+// NOTE: we cannot collapse this type to
+// `StructuredTypeDef = StructuredTypeDefFields`
+// as we rely on the `fields` field being unique to discriminate between different
+// TypeDefs
+export type ObjectTypeDef<
+  Fields extends ObjectTypeDefFields = ObjectTypeDefFields,
+> = {
+  readonly type: TypeDefType.Object,
+  readonly fields: Fields,
+}
+
+export type UnionKey = string
+
+export type UnionTypeDef<
+  D extends string | null = string | null,
+  U extends Readonly<Record<UnionKey, AnyTypeDef>> = Readonly<Record<UnionKey, AnyTypeDef>>,
+> = {
+  readonly discriminator: D,
+  readonly type: TypeDefType.Union,
+  readonly unions: U,
+}

package/types/flattened.ts

@@ -0,0 +1,5 @@
+// Unfortunately the TS compiler will infinitely loop if we don't give it a way of breaking out.
+// A starting depth of 10 (the maximum) will cause performance issues while developing
+export type StartingDepth = 8
+// Going much above a depth of 10 will also blow up
+export type Depths = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]

package/types/flattened_accessors_of.ts

@@ -0,0 +1,15 @@
+import { type Type } from './definitions'
+import { type FlattenedValueTypesOf } from './flattened_value_types_of'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Accessor<T = any> = {
+  readonly value: T,
+  set(v: T): void,
+}
+
+export type FlattenedAccessorsOf<
+  T extends Type,
+  Flattened extends Readonly<Record<string, Accessor>> = FlattenedValueTypesOf<T>,
+> = {
+  readonly [K in keyof Flattened]: Accessor<Flattened[K]>
+}

package/types/flattened_type_defs_of.ts

@@ -0,0 +1,130 @@
+import {
+  type UnionToIntersection,
+} from 'type-fest'
+import {
+  type ListTypeDef,
+  type LiteralTypeDef,
+  type ObjectTypeDef,
+  type RecordTypeDef,
+  type Type,
+  type TypeDef,
+  type UnionTypeDef,
+} from './definitions'
+import {
+  type Depths,
+  type StartingDepth,
+} from './flattened'
+import { type JsonPathOf } from './json_path_of'
+
+// NOTE removing any ternary from this file improves the performance and the depth of data structure we can go to
+
+export type FlattenedTypeDefsOf<
+  T extends Type,
+  SegmentOverride extends string | null,
+  Path extends string = '$',
+  Depth extends number = StartingDepth,
+> = InternalFlattenedTypeDefsOf<T['definition'], SegmentOverride, Path, '', Depth>
+
+type InternalFlattenedTypeDefsOf<
+  T extends TypeDef,
+  SegmentOverride extends string | null,
+  Path extends string,
+  Qualifier extends string,
+  Depth extends number,
+> =
+  & {
+    readonly [K in Path]: Type<T>
+  }
+  & InternalFlattenedTypeDefsOfChildren<T, SegmentOverride, Path, Qualifier, Depth>
+
+type InternalFlattenedTypeDefsOfChildren<
+  T extends TypeDef,
+  SegmentOverride extends string | null,
+  Path extends string,
+  Qualifier extends string,
+  Depth extends number,
+  NextDepth extends number = Depths[Depth],
+> =
+  // resolve anything too deep to `never` instead of to {} so the caller knows
+  // it has explicitly failed
+  NextDepth extends -1 ? never
+    : T extends LiteralTypeDef ? InternalFlattenedTypeDefsOfLiteralChildren
+    : T extends ListTypeDef ? InternalFlattenedTypeDefsOfListChildren<T, SegmentOverride, Path, NextDepth>
+    : T extends RecordTypeDef ? InternalFlattenedTypeDefsOfRecordChildren<T, SegmentOverride, Path, NextDepth>
+    : T extends ObjectTypeDef
+      ? InternalFlattenedTypeDefsOfObjectChildren<T, SegmentOverride, Path, Qualifier, NextDepth>
+    : T extends UnionTypeDef ? InternalFlattenedTypeDefsOfUnionChildren<T, SegmentOverride, Path, Qualifier, NextDepth>
+    : never
+
+type InternalFlattenedTypeDefsOfLiteralChildren = {}
+
+type InternalFlattenedTypeDefsOfListChildren<
+  T extends ListTypeDef,
+  SegmentOverride extends string | null,
+  Path extends string,
+  Depth extends number,
+> = InternalFlattenedTypeDefsOf<
+  T['elements'],
+  SegmentOverride,
+  JsonPathOf<Path, number, SegmentOverride>,
+  '',
+  Depth
+>
+
+type InternalFlattenedTypeDefsOfRecordChildren<
+  T extends RecordTypeDef,
+  SegmentOverride extends string | null,
+  Path extends string,
+  Depth extends number,
+> = InternalFlattenedTypeDefsOf<
+  T['valueTypeDef'],
+  SegmentOverride,
+  JsonPathOf<Path, T['keyPrototype'], SegmentOverride>,
+  '',
+  Depth
+>
+
+type InternalFlattenedTypeDefsOfObjectChildren<
+  T extends ObjectTypeDef,
+  SegmentOverride extends string | null,
+  Path extends string,
+  Qualifier extends string,
+  Depth extends number,
+> = T extends ObjectTypeDef<infer Fields> ? {} extends Fields ? {} : keyof Fields extends string ? UnionToIntersection<{
+      readonly [K in keyof Fields]-?: InternalFlattenedTypeDefsOf<
+        Exclude<Fields[K], undefined>,
+        SegmentOverride,
+        JsonPathOf<Path, `${Qualifier}${K}`, null>,
+        '',
+        Depth
+      >
+    }[keyof Fields]>
+  : never
+  : never
+
+type InternalFlattenedTypeDefsOfUnionChildren<
+  T extends UnionTypeDef,
+  SegmentOverride extends string | null,
+  Path extends string,
+  Qualifier extends string,
+  Depth extends number,
+> = T extends UnionTypeDef<infer D, infer Unions> ? keyof Unions extends string ? D extends null ? UnionToIntersection<{
+        readonly [K in keyof Unions]: InternalFlattenedTypeDefsOfChildren<
+          Unions[K],
+          SegmentOverride,
+          Path,
+          '',
+          Depth
+        >
+      }[keyof Unions]>
+    : UnionToIntersection<{
+      readonly [K in keyof Unions]: InternalFlattenedTypeDefsOfChildren<
+        Unions[K],
+        SegmentOverride,
+        Path,
+        `${Qualifier}${K}:`,
+        Depth
+      >
+    }[keyof Unions]>
+  : never
+  : never

package/types/flattened_value_types_of.ts

@@ -0,0 +1,11 @@
+import { type Type } from './definitions'
+import { type FlattenedTypeDefsOf } from './flattened_type_defs_of'
+import { type ValueTypeOf } from './value_type_of'
+
+export type FlattenedValueTypesOf<
+  T extends Type,
+  SegmentOverride extends string | null = null,
+  Flattened extends Readonly<Record<string, Type>> = FlattenedTypeDefsOf<T, SegmentOverride>,
+> = {
+  [K in keyof Flattened]: ValueTypeOf<Flattened[K], {}>
+}

package/types/json_path_of.ts

@@ -0,0 +1,7 @@
+export type JsonPathOf<
+  Prefix extends string,
+  Accessor extends string | number | symbol,
+  SegmentOverride extends string | null = null,
+> = SegmentOverride extends string ? `${Prefix}.${SegmentOverride}`
+  : Accessor extends string | number ? `${Prefix}.${Accessor}`
+  : never

package/types/json_paths_of.ts

@@ -0,0 +1,129 @@
+import {
+  type ListTypeDef,
+  type LiteralTypeDef,
+  type ObjectTypeDef,
+  type RecordTypeDef,
+  type Type,
+  type TypeDef,
+  type UnionTypeDef,
+} from './definitions'
+import {
+  type Depths,
+  type StartingDepth,
+} from './flattened'
+import { type JsonPathOf } from './json_path_of'
+
+export type JsonPathsOf<
+  T extends Type,
+  SegmentOverride extends string | null = null,
+  Prefix extends string = '$',
+> = InternalJsonPathsOf<T['definition'], Prefix, SegmentOverride, StartingDepth>
+
+export type InternalJsonPathsOf<
+  F extends TypeDef,
+  Prefix extends string,
+  SegmentOverride extends string | null,
+  // TODO maybe depth isn't necessary here?
+  Depth extends number,
+  NextDepth extends number = Depths[Depth],
+> = InternalJsonPathsOfChildren<F, Prefix, SegmentOverride, '', NextDepth> | Prefix
+
+type InternalJsonPathsOfChildren<
+  F extends TypeDef,
+  Prefix extends string,
+  SegmentOverride extends string | null,
+  Qualifier extends string,
+  Depth extends number,
+> = Depth extends -1 ? never
+  : F extends LiteralTypeDef ? InternalJsonPathsOfLiteralChildren
+  : F extends ListTypeDef ? InternalJsonPathsOfListChildren<F, Prefix, SegmentOverride, Depth>
+  : F extends RecordTypeDef ? InternalJsonPathsOfRecordChildren<F, Prefix, SegmentOverride, Depth>
+  : F extends ObjectTypeDef ? InternalJsonPathsOfObjectChildren<F, Prefix, SegmentOverride, Qualifier, Depth>
+  : F extends UnionTypeDef ? InternalJsonPathsOfUnionChildren<
+      F,
+      Prefix,
+      SegmentOverride,
+      Qualifier,
+      Depth
+    >
+  : never
+
+type InternalJsonPathsOfLiteralChildren = never
+
+type InternalJsonPathsOfListChildren<
+  F extends ListTypeDef,
+  Prefix extends string,
+  SegmentOverride extends string | null,
+  Depth extends number,
+> = InternalJsonPathsOf<
+  F['elements'],
+  JsonPathOf<
+    Prefix,
+    number,
+    SegmentOverride
+  >,
+  SegmentOverride,
+  Depth
+>
+
+type InternalJsonPathsOfRecordChildren<
+  F extends RecordTypeDef,
+  Prefix extends string,
+  SegmentOverride extends string | null,
+  Depth extends number,
+> = InternalJsonPathsOf<
+  F['valueTypeDef'],
+  JsonPathOf<
+    Prefix,
+    F['keyPrototype'],
+    SegmentOverride
+  >,
+  SegmentOverride,
+  Depth
+>
+
+type InternalJsonPathsOfObjectChildren<
+  F extends ObjectTypeDef,
+  Prefix extends string,
+  SegmentOverride extends string | null,
+  Qualifier extends string,
+  Depth extends number,
+> = F extends ObjectTypeDef<infer Fields> ? keyof Fields extends string ? {
+      [K in keyof Fields]: InternalJsonPathsOf<
+        Fields[K],
+        JsonPathOf<
+          Prefix,
+          `${Qualifier}${K}`,
+          null
+        >,
+        SegmentOverride,
+        Depth
+      >
+    }[keyof Fields]
+  : never
+  : never
+
+type InternalJsonPathsOfUnionChildren<
+  F extends UnionTypeDef,
+  Prefix extends string,
+  SegmentOverride extends string | null,
+  Qualifier extends string,
+  Depth extends number,
+> // typescript cannot infer the key in unions unless we get the value directly
+ = F extends UnionTypeDef<infer D, infer Unions> ? keyof Unions extends string ? {
+      readonly [K in keyof Unions]: InternalJsonPathsOfChildren<
+        Unions[K],
+        // This will overload paths, but we don't actually care about that here
+        // I think what we should do is have a "denormalize of", which you can then
+        // get the paths of if you want the unique paths
+        // (alt PrefixOf<Prefix, K>,)
+        Prefix,
+        SegmentOverride,
+        D extends null ? Qualifier : `${Qualifier}${K}:`,
+        Depth
+      >
+    }[keyof Unions]
+    // do not expose the discriminator as we cannot set this value independently
+    //  | (D extends string ? JsonPathOf<Prefix, D, null, Qualifier> : never)
+  : never
+  : never