shapecraft 1.0.0

package/packages/core/src/shape/builder.ts

@@ -0,0 +1,475 @@
+import { R } from "../common";
+import { remapObjectValues } from "../common/object";
+import { Arrayish, Tuple } from "../common/types";
+import { ValidationError } from "./error";
+import { annotate, shapes } from "./shape";
+import {
+  JSONSchema,
+  SQLOptions,
+  toJSONSchema,
+  toSQL,
+  toTypescript,
+} from "./transforms";
+
+export interface ShapeBuilderBase<out S extends shapes.Shape> {
+  type: S["type"];
+  shape: S;
+
+  is(input: unknown): input is shapes.InferShapeOut<S>;
+  parse(input: unknown): R.Result<shapes.InferShapeOut<S>, ValidationError[]>;
+  optional(): ShapeBuilder<shapes.Annotated<S, { optional: true }>>;
+  unique(): ShapeBuilder<shapes.Annotated<S, { unique: true }>>;
+  primary(): ShapeBuilder<shapes.Annotated<S, { primary: true }>>;
+  default<Value extends shapes.InferShapeOut<S>>(
+    value: Value,
+  ): ShapeBuilder<shapes.Annotated<S, { default: Value }>>;
+  title<Text extends string>(
+    text: Text,
+  ): ShapeBuilder<shapes.Annotated<S, { title: Text }>>;
+  describe<Text extends string>(
+    text: Text,
+  ): ShapeBuilder<shapes.Annotated<S, { description: Text }>>;
+  comment<Text extends string>(
+    text: Text,
+  ): ShapeBuilder<shapes.Annotated<S, { comment: Text }>>;
+  autoIncrement(): ShapeBuilder<shapes.Annotated<S, { autoIncrement: true }>>;
+  foreign<Table extends string, Column extends string>(
+    table: Table,
+    column: Column,
+  ): ShapeBuilder<
+    shapes.Annotated<S, { foreign: { table: Table; column: Column } }>
+  >;
+  references<
+    Target extends ShapeBuilder<
+      shapes.Annotated<shapes.ShapeMapping, { title: string }>
+    >,
+    Field extends Extract<
+      keyof {
+        [P in keyof shapes.InputOfShape<Target["shape"]> as shapes.InputOfShape<
+          Target["shape"]
+        >[P]["type"] extends S["type"] ?
+          P
+        : never]: P;
+      },
+      string
+    >,
+  >(
+    target: Target,
+    field: Field,
+  ): ShapeBuilder<
+    shapes.Annotated<
+      S,
+      {
+        foreign: {
+          table: Target["shape"]["anno"]["title"];
+          column: Extract<Field, string>;
+        };
+      }
+    >
+  >;
+  meta<Meta extends Record<string, any>>(
+    meta: Meta,
+  ): ShapeBuilder<shapes.Annotated<S, { meta: S["anno"]["meta"] & Meta }>>;
+
+  ////////////////
+
+  toJSONSchema(): JSONSchema;
+  toSQL(opts?: SQLOptions): R.Result<string, string[]>;
+  toTypescript(): string;
+}
+
+export interface ShapeBuilderWithLength<
+  out S extends shapes.ShapeWithLength = shapes.ShapeWithLength,
+> extends ShapeBuilderBase<S> {
+  min<N extends number>(n: N): ShapeBuilder<shapes.Annotated<S, { min: N }>>;
+  max<N extends number>(n: N): ShapeBuilder<shapes.Annotated<S, { max: N }>>;
+}
+
+export interface ShapeBuilderForString<
+  out S extends shapes.ShapeString = shapes.ShapeString,
+> extends ShapeBuilderWithLength<S> {
+  regex<P extends string | RegExp>(
+    pattern: P,
+  ): ShapeBuilder<shapes.Annotated<S, { pattern: P }>>;
+  format<F extends string>(
+    format: F,
+  ): ShapeBuilder<shapes.Annotated<S, { format: F }>>;
+  uuid(
+    version?: number | undefined,
+  ): ShapeBuilder<shapes.Annotated<S, { pattern: RegExp }>>;
+}
+
+export interface ShapeBuilderForNumber<
+  out S extends shapes.ShapeNumber = shapes.ShapeNumber,
+> extends ShapeBuilderWithLength<S> {}
+
+export interface ShapeBuilderForArray<
+  out S extends shapes.ShapeArray = shapes.ShapeArray,
+> extends ShapeBuilderWithLength<S> {
+  uniqueItems(): ShapeBuilder<shapes.Annotated<S, { uniqueItems: true }>>;
+}
+
+export interface ShapeBuilderForMapping<
+  out S extends shapes.ShapeMapping = shapes.ShapeMapping,
+> extends ShapeBuilderBase<S> {
+  unique(): ShapeBuilder<shapes.Annotated<S, { unique: true }>>;
+  unique<
+    Cols extends ReadonlyArray<Extract<keyof shapes.InputOfShape<S>, string>>,
+  >(
+    columns: Cols,
+    name?: string,
+  ): ShapeBuilder<S>;
+}
+
+export type ShapeBuilder<S extends { type: string }> =
+  [S["type"]] extends ["string"] ?
+    ShapeBuilderForString<Extract<S, shapes.ShapeString>>
+  : [S["type"]] extends ["number"] ?
+    ShapeBuilderForNumber<Extract<S, shapes.ShapeNumber>>
+  : [S["type"]] extends ["array"] ?
+    ShapeBuilderForArray<Extract<S, shapes.ShapeArray>>
+  : [S["type"]] extends ["mapping"] ?
+    ShapeBuilderForMapping<Extract<S, shapes.ShapeMapping>>
+  : [S] extends [shapes.Shape] ? ShapeBuilderBase<S>
+  : never;
+
+export type AnyShapeBuilder =
+  | ShapeBuilderBase<shapes.Shape>
+  | ShapeBuilderForString<shapes.ShapeString>
+  | ShapeBuilderForNumber<shapes.ShapeNumber>
+  | ShapeBuilderForArray<shapes.ShapeArray>
+  | ShapeBuilderForMapping<shapes.ShapeMapping>;
+
+export function createBuilderBase<const S extends shapes.Shape>(
+  shape: S,
+): ShapeBuilderBase<S> {
+  return {
+    type: shape.type,
+    shape: shape,
+    is: (input: unknown) => shapes.is(shape, input),
+    parse: (input: unknown) => shapes.parse(shape, input),
+    optional: () => createBuilder(annotate.optional(shape)),
+    unique: () => createBuilder(annotate.unique(shape)),
+    primary: () => createBuilder(annotate.primary(shape)),
+    default: (value) => createBuilder(annotate.defaulted(shape, value)),
+    title: (text) => createBuilder(annotate.titled(shape, text)),
+    describe: (text) => createBuilder(annotate.described(shape, text)),
+    comment: (text) => createBuilder(annotate.commented(shape, text)),
+    autoIncrement: () => createBuilder(annotate.autoIncremented(shape)),
+    foreign: <Table extends string, Column extends string>(
+      table: Table,
+      column: Column,
+    ) => createBuilder(annotate.foreign(shape, table, column)),
+    references: <
+      Target extends ShapeBuilder<
+        shapes.Annotated<shapes.ShapeMapping, { title: string }>
+      >,
+      Field extends Extract<
+        keyof {
+          [P in keyof shapes.InputOfShape<
+            Target["shape"]
+          > as shapes.InputOfShape<Target["shape"]>[P]["type"] extends (
+            S["type"]
+          ) ?
+            P
+          : never]: P;
+        },
+        string
+      >,
+    >(
+      target: Target,
+      field: Field,
+    ) =>
+      createBuilder(
+        annotate.foreign(shape, target.shape.anno.title, field),
+      ) as ShapeBuilder<
+        shapes.Annotated<
+          S,
+          {
+            foreign: {
+              table: Target["shape"]["anno"]["title"];
+              column: Extract<Field, string>;
+            };
+          }
+        >
+      >,
+    meta: (meta) => createBuilder(annotate.meta(shape, meta)),
+
+    //////
+    toJSONSchema: () => toJSONSchema(shape),
+    toSQL: (opts?: SQLOptions) => toSQL(shape, opts),
+    toTypescript: () => toTypescript(shape),
+  };
+}
+
+export function createBuilderWithLength<const S extends shapes.ShapeWithLength>(
+  shape: S,
+): ShapeBuilderWithLength<S> {
+  return {
+    ...createBuilderBase(shape),
+    min: <N extends number>(n: N) => createBuilder(annotate.min(shape, n)),
+    max: <N extends number>(n: N) => createBuilder(annotate.max(shape, n)),
+  };
+}
+
+export function createBuilderForString<const S extends shapes.ShapeString>(
+  shape: S,
+): ShapeBuilderForString<S> {
+  return {
+    ...createBuilderWithLength(shape),
+    regex: <P extends string | RegExp>(pattern: P) =>
+      createBuilder(annotate.as(shape, { pattern: pattern })),
+    format: <F extends string>(format: F) =>
+      createBuilder(annotate.as(shape, { format: format })),
+    uuid: (version?: number | undefined) =>
+      createBuilder(annotate.uuid(shape, version)),
+  };
+}
+
+export function createBuilderForNumber<const S extends shapes.ShapeNumber>(
+  shape: S,
+): ShapeBuilderForNumber<S> {
+  return {
+    ...createBuilderWithLength(shape),
+  };
+}
+
+export function createBuilderForArray<const S extends shapes.ShapeArray>(
+  shape: S,
+): ShapeBuilderForArray<S> {
+  return {
+    ...createBuilderWithLength(shape),
+    uniqueItems: () => createBuilder(annotate.uniqueItems(shape)),
+  };
+}
+
+export function createBuilderForMapping<const S extends shapes.ShapeMapping>(
+  shape: S,
+): ShapeBuilderForMapping<S> {
+  const uniqueFn = ((
+    columns?: ReadonlyArray<string>,
+    name?: string,
+  ): AnyShapeBuilder => {
+    if (columns === undefined) {
+      return createBuilder(annotate.unique(shape)) as AnyShapeBuilder;
+    }
+    const existing = shape.anno.uniqueConstraints ?? [];
+    const entry: { columns: string[]; name?: string } = {
+      columns: [...columns],
+    };
+    if (name !== undefined) entry.name = name;
+    return createBuilder(
+      annotate.as(shape, {
+        uniqueConstraints: [...existing, entry],
+      }),
+    ) as AnyShapeBuilder;
+  }) as ShapeBuilderForMapping<S>["unique"];
+  return {
+    ...createBuilderBase(shape),
+    unique: uniqueFn,
+  };
+}
+
+export function createBuilder<const S extends shapes.Shape>(
+  shape: S,
+): ShapeBuilder<S>;
+export function createBuilder<const S extends shapes.ShapeString>(
+  shape: S,
+): ShapeBuilderForString<S>;
+export function createBuilder<const S extends shapes.ShapeNumber>(
+  shape: S,
+): ShapeBuilderForNumber<S>;
+export function createBuilder<const S extends shapes.ShapeArray>(
+  shape: S,
+): ShapeBuilderForArray<S>;
+export function createBuilder<const S extends shapes.ShapeMapping>(
+  shape: S,
+): ShapeBuilderForMapping<S>;
+export function createBuilder(shape: shapes.Shape): AnyShapeBuilder;
+export function createBuilder(shape: shapes.Shape): AnyShapeBuilder {
+  switch (shape.type) {
+    case "string":
+      return createBuilderForString(shape);
+    case "number":
+      return createBuilderForNumber(shape);
+    case "array":
+      return createBuilderForArray(shape);
+    case "mapping":
+      return createBuilderForMapping(shape as shapes.ShapeMapping);
+    default:
+      return createBuilderBase(shape);
+  }
+}
+
+/*
+   Allows for more ergonomic shape definitions like:
+   ```
+   const myShape = B.mapping({
+     foo: B.string().optional()
+   })
+   ```
+*/
+export namespace B {
+  // ---------- primitive scalars
+  export const string = (): ShapeBuilderForString<shapes.ShapeString> =>
+    createBuilderForString(shapes.string());
+  export const boolean = (): ShapeBuilderBase<shapes.ShapeBoolean> =>
+    createBuilderBase(shapes.boolean());
+  export const notDefined = (): ShapeBuilderBase<shapes.ShapeUndefined> =>
+    createBuilderBase(shapes.notDefined());
+  export const date = (): ShapeBuilderBase<shapes.ShapeDate> =>
+    createBuilderBase(shapes.date());
+  export const nil = (): ShapeBuilderBase<shapes.ShapeNil> =>
+    createBuilderBase(shapes.nil());
+  export const unknown = (): ShapeBuilderBase<shapes.ShapeUnknown> =>
+    createBuilderBase(shapes.unknown());
+  export const binary = (): ShapeBuilderBase<shapes.ShapeBinary> =>
+    createBuilderBase(shapes.binary());
+
+  // ---------- numeric tags
+  export const number = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "number">
+  > => createBuilderForNumber(shapes.number());
+  export const int = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "int">
+  > => createBuilderForNumber(shapes.int());
+  export const int8 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "int8">
+  > => createBuilderForNumber(shapes.int8());
+  export const uint8 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "uint8">
+  > => createBuilderForNumber(shapes.uint8());
+  export const int16 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "int16">
+  > => createBuilderForNumber(shapes.int16());
+  export const uint16 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "uint16">
+  > => createBuilderForNumber(shapes.uint16());
+  export const int32 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "int32">
+  > => createBuilderForNumber(shapes.int32());
+  export const uint32 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "uint32">
+  > => createBuilderForNumber(shapes.uint32());
+  export const int64 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "int64">
+  > => createBuilderForNumber(shapes.int64());
+  export const uint64 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "uint64">
+  > => createBuilderForNumber(shapes.uint64());
+  export const float = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "float">
+  > => createBuilderForNumber(shapes.float());
+  export const float32 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "float32">
+  > => createBuilderForNumber(shapes.float32());
+  export const float64 = (): ShapeBuilderForNumber<
+    shapes.ShapeNumber<null, "float64">
+  > => createBuilderForNumber(shapes.float64());
+
+  // ---------- literal
+  export function literal<const V extends string>(
+    value: V,
+  ): ShapeBuilderForString<shapes.MakeLiteral<shapes.ShapeString<V>>>;
+  export function literal<const V extends number>(
+    value: V,
+  ): ShapeBuilderForNumber<shapes.MakeLiteral<shapes.ShapeNumber<V>>>;
+  export function literal<const V extends boolean>(
+    value: V,
+  ): ShapeBuilderBase<shapes.MakeLiteral<shapes.ShapeBoolean<V>>>;
+  export function literal<const V extends string | number | boolean>(
+    value: V,
+  ): AnyShapeBuilder {
+    return createBuilder(shapes.literal(value));
+  }
+
+  // ---------- containers
+  export const array = <const Builder extends { shape: shapes.Shape }>(
+    builder: Builder,
+  ): ShapeBuilderForArray<shapes.ShapeArray<Builder["shape"]>> =>
+    createBuilderForArray(shapes.array(builder.shape));
+
+  export const mapping = <
+    const Rec extends Record<string, { shape: shapes.Shape }>,
+  >(
+    rec: Rec,
+  ): ShapeBuilderForMapping<
+    shapes.ShapeMapping<{ -readonly [P in keyof Rec]: Rec[P]["shape"] }>
+  > => {
+    return createBuilderForMapping(
+      shapes.mapping(remapObjectValues(rec, ([_k, r]) => r.shape)),
+    );
+  };
+
+  export const record = <
+    const K extends { shape: shapes.ShapeKeyable },
+    const V extends { shape: shapes.Shape },
+  >(
+    key: K,
+    value: V,
+  ): ShapeBuilderBase<shapes.ShapeRecord<[K["shape"], V["shape"]]>> =>
+    createBuilderBase(shapes.record(key.shape, value.shape));
+
+  export const range = <const Item extends { shape: shapes.Shape }>(
+    item: Item,
+  ): ShapeBuilderBase<shapes.ShapeRange<Item["shape"]>> =>
+    createBuilderBase(shapes.range(item.shape));
+
+  export function vector<const Dims extends number>(
+    dims: Dims,
+  ): ShapeBuilderBase<shapes.ShapeVector<Dims, shapes.ShapeNumber>>;
+  export function vector<
+    const Dims extends number,
+    const Format extends { shape: shapes.ShapeNumber },
+  >(
+    dims: Dims,
+    format: Format,
+  ): ShapeBuilderBase<shapes.ShapeVector<Dims, Format["shape"]>>;
+  export function vector(
+    dims: number,
+    format?: { shape: shapes.ShapeNumber },
+  ): ShapeBuilderBase<shapes.ShapeVector> {
+    return createBuilderBase(
+      format ? shapes.vector(dims, format.shape) : shapes.vector(dims),
+    );
+  }
+
+  export function union<const Of extends readonly { shape: shapes.Shape }[]>(
+    ...of: Of
+  ): ShapeBuilderBase<
+    shapes.ShapeUnion<{ -readonly [K in keyof Of]: Of[K]["shape"] }>
+  >;
+  export function union(
+    ...of: Arrayish<AnyShapeBuilder>
+  ): ShapeBuilderBase<shapes.ShapeUnion> {
+    return createBuilderBase(shapes.union(...of.flat().map((x) => x.shape)));
+  }
+
+  export function tuple<const Of extends readonly { shape: shapes.Shape }[]>(
+    ...of: Of
+  ): ShapeBuilderBase<
+    shapes.ShapeTuple<{ -readonly [K in keyof Of]: Of[K]["shape"] }>
+  >;
+  export function tuple<const Of extends readonly { shape: shapes.Shape }[]>(
+    of: Of,
+  ): ShapeBuilderBase<
+    shapes.ShapeTuple<{ -readonly [K in keyof Of]: Of[K]["shape"] }>
+  >;
+  export function tuple(
+    ...of: Arrayish<AnyShapeBuilder>
+  ): ShapeBuilderBase<shapes.ShapeTuple> {
+    return createBuilderBase(shapes.tuple(...of.flat().map((x) => x.shape)));
+  }
+
+  export const module = <
+    const Rec extends Record<string, { shape: shapes.ShapeMapping }>,
+  >(
+    rec: Rec,
+  ): ShapeBuilderBase<
+    shapes.ShapeModule<{ -readonly [P in keyof Rec]: Rec[P]["shape"] }>
+  > => {
+    return createBuilderBase(
+      shapes.module(remapObjectValues(rec, ([_k, r]) => r.shape)),
+    );
+  };
+}

package/packages/core/src/shape/error.ts

@@ -0,0 +1,4 @@
+export type ValidationError = {
+  path: PropertyKey[];
+  message: string;
+};

package/packages/core/src/shape/index.ts

@@ -0,0 +1,3 @@
+export * from "./shape";
+export * from "./builder";
+export * from "./transforms";

package/packages/core/src/shape/number.ts

@@ -0,0 +1,118 @@
+import { FloatTag, IntTag, NumberTag } from "./tags";
+
+const INT8_MIN = -128;
+const INT8_MAX = 127;
+const UINT8_MAX = 255;
+const INT16_MIN = -32_768;
+const INT16_MAX = 32_767;
+const UINT16_MAX = 65_535;
+const INT32_MIN = -2_147_483_648;
+const INT32_MAX = 2_147_483_647;
+const UINT32_MAX = 4_294_967_295;
+const INT64_MIN = -(2 ** 63);
+const INT64_MAX = 2 ** 63 - 1;
+const UINT64_MAX = 2 ** 64 - 1;
+
+const FLOAT32_MAX = 3.4028234663852886e38;
+
+const fitsFloat32 = (x: number): boolean => {
+  if (!Number.isFinite(x)) return true;
+  if (Math.abs(x) > FLOAT32_MAX) return false;
+  return Math.fround(x) === x;
+};
+
+export const inferNumberTag = (x: number): NumberTag => {
+  if (!Number.isFinite(x)) {
+    return "float32";
+  }
+
+  if (Number.isInteger(x)) {
+    if (x >= 0) {
+      if (x <= INT8_MAX) return "uint8";
+      if (x <= UINT8_MAX) return "uint8";
+      if (x <= INT16_MAX) return "uint16";
+      if (x <= UINT16_MAX) return "uint16";
+      if (x <= INT32_MAX) return "uint32";
+      if (x <= UINT32_MAX) return "uint32";
+      if (x <= INT64_MAX) return "uint64";
+      if (x <= UINT64_MAX) return "uint64";
+      return "int";
+    } else {
+      if (x >= INT8_MIN) return "int8";
+      if (x >= INT16_MIN) return "int16";
+      if (x >= INT32_MIN) return "int32";
+      if (x >= INT64_MIN) return "int64";
+      return "int";
+    }
+  }
+
+  // Non-integer floats
+  if (fitsFloat32(x)) return "float32";
+  return "float64";
+};
+
+export const isFloatTag = (x: NumberTag): x is FloatTag =>
+  x === "float" || x === "float32" || x === "float64";
+
+export const isIntTag = (x: NumberTag): x is IntTag => !isFloatTag(x);
+
+export const isUnsignedTag = (x: NumberTag): boolean => x.startsWith("uint");
+
+const INT_RANK: Record<IntTag, number> = {
+  uint8: 1,
+  int8: 2,
+  uint16: 3,
+  int16: 4,
+  uint32: 5,
+  int32: 6,
+  uint64: 7,
+  int64: 8,
+  int: 9,
+};
+
+const FLOAT_RANK: Record<FloatTag, number> = {
+  float32: 1,
+  float64: 2,
+  float: 3,
+};
+
+const rankOf = (x: NumberTag): number =>
+  isIntTag(x) ? INT_RANK[x]
+  : isFloatTag(x) ? FLOAT_RANK[x]
+  : -1;
+
+const merge = (a: NumberTag, b: NumberTag): NumberTag => {
+  if (a === b) return a;
+  if (a === "number" || b === "number") return "number";
+
+  if (isIntTag(a) && isIntTag(b)) {
+    return rankOf(a) > rankOf(b) ? a : b;
+  }
+
+  if (isFloatTag(a) && isFloatTag(b)) {
+    return rankOf(a) > rankOf(b) ? a : b;
+  }
+
+  return "float64";
+};
+
+export const inferNumberTagFromSamples = (samples: number[]): NumberTag => {
+  if (samples.length <= 0) return "number";
+  const tags = samples.map((s) => inferNumberTag(s));
+  const uniqueTags = Array.from(new Set(tags).values());
+  if (uniqueTags.length === 1) return uniqueTags[0]!;
+  return uniqueTags.reduce(merge);
+};
+
+export const numberTagCanBeCastedTo = (
+  tag: NumberTag,
+  to: NumberTag,
+): boolean => {
+  if (tag === to || to === "number") return true;
+
+  if ((isIntTag(tag) && isIntTag(to)) || (isFloatTag(tag) && isFloatTag(to))) {
+    return rankOf(tag) <= rankOf(to);
+  }
+
+  return false;
+};