@soundscript/soundscript 0.1.12 → 0.1.15

package/project-transform/src/stdlib/decode.ts

@@ -0,0 +1,390 @@
+import { type ErrorFrame, Failure } from 'sts:failures';
+import { err, isErr, none, ok, some, type Option, type Result } from 'sts:result';
+
+export type DecodePathSegment = string | number;
+export type DecodePath = readonly DecodePathSegment[];
+
+export class DecodeFailure extends Failure {
+  readonly path: DecodePath;
+
+  constructor(
+    message = 'Failed to decode value.',
+    options: {
+      cause?: unknown;
+      path?: DecodePath;
+      trace?: readonly ErrorFrame[];
+    } = {},
+  ) {
+    super(message, {
+      ...(options.cause === undefined ? {} : { cause: options.cause }),
+      ...(options.trace === undefined ? {} : { trace: options.trace }),
+    });
+    this.path = options.path ?? [];
+  }
+
+  at(segment: DecodePathSegment): this {
+    const prototype = Object.getPrototypeOf(this as object);
+    const clone = (prototype === null ? Object.create(null) : Object.create(prototype)) as this;
+    Object.defineProperties(clone, Object.getOwnPropertyDescriptors(this));
+    Object.defineProperty(clone, 'path', {
+      configurable: true,
+      enumerable: true,
+      writable: false,
+      value: [segment, ...this.path],
+    });
+    return clone;
+  }
+}
+
+// #[variance(T: out, E: out)]
+export type Decoder<T, E = DecodeFailure> = {
+  decode(value: unknown): Result<T, E>;
+};
+
+// #[variance(T: out, E: out)]
+export type OptionalDecoder<T, E = DecodeFailure> = Decoder<T | undefined, E> & {
+  readonly __soundscriptOptional: true;
+  readonly inner: Decoder<T, E>;
+};
+
+type DecoderValue<TDecoder> = TDecoder extends Decoder<infer TValue, unknown> ? TValue : never;
+type DecoderError<TDecoder> = TDecoder extends Decoder<unknown, infer E> ? E : never;
+
+type ObjectShape = Record<string, Decoder<unknown, unknown>>;
+type TupleShape = readonly Decoder<unknown, unknown>[];
+
+export const string: Decoder<string> = {
+  decode(value): Result<string, DecodeFailure> {
+    return typeof value === 'string'
+      ? ok(value)
+      : err(new DecodeFailure('Expected string.', { cause: value }));
+  },
+};
+
+export const number: Decoder<number> = {
+  decode(value): Result<number, DecodeFailure> {
+    return typeof value === 'number'
+      ? ok(value)
+      : err(new DecodeFailure('Expected number.', { cause: value }));
+  },
+};
+
+export const boolean: Decoder<boolean> = {
+  decode(value): Result<boolean, DecodeFailure> {
+    return typeof value === 'boolean'
+      ? ok(value)
+      : err(new DecodeFailure('Expected boolean.', { cause: value }));
+  },
+};
+
+export const bigint: Decoder<bigint> = {
+  decode(value): Result<bigint, DecodeFailure> {
+    if (typeof value === 'bigint') {
+      return ok(value);
+    }
+
+    if (typeof value === 'number') {
+      return Number.isInteger(value) && Number.isSafeInteger(value)
+        ? ok(BigInt(value))
+        : err(new DecodeFailure('Expected bigint.', { cause: value }));
+    }
+
+    if (typeof value === 'string') {
+      try {
+        return ok(BigInt(value));
+      } catch {
+        return err(new DecodeFailure('Expected bigint.', { cause: value }));
+      }
+    }
+
+    return err(new DecodeFailure('Expected bigint.', { cause: value }));
+  },
+};
+
+export function lazy<T, E>(getDecoder: () => Decoder<T, E>): Decoder<T, E> {
+  return {
+    decode(value) {
+      return getDecoder().decode(value);
+    },
+  };
+}
+
+export function optional<T, E>(decoder: Decoder<T, E>): OptionalDecoder<T, E> {
+  return {
+    __soundscriptOptional: true,
+    inner: decoder,
+    decode(value) {
+      return value === undefined ? ok(undefined) : decoder.decode(value);
+    },
+  };
+}
+
+export function literal<const T extends string | number | boolean | null>(value: T): Decoder<T> {
+  return {
+    decode(input) {
+      return Object.is(input, value)
+        ? ok(value)
+        : err(new DecodeFailure(`Expected literal ${JSON.stringify(value)}.`, { cause: input }));
+    },
+  };
+}
+
+export function array<T, E>(item: Decoder<T, E>): Decoder<readonly T[], E | DecodeFailure> {
+  return {
+    decode(value) {
+      if (!Array.isArray(value)) {
+        return err(new DecodeFailure('Expected array.', { cause: value }));
+      }
+
+      const decodedValues: T[] = [];
+      for (let index = 0; index < value.length; index += 1) {
+        const decoded = item.decode(value[index]);
+        if (isErr(decoded)) {
+          return err(prependPathIfPossible(decoded.error, index));
+        }
+        decodedValues.push(decoded.value);
+      }
+
+      return ok(decodedValues);
+    },
+  };
+}
+
+export function tuple<const TElements extends TupleShape>(
+  ...elements: TElements
+): Decoder<
+  { readonly [K in keyof TElements]: DecoderValue<TElements[K]> },
+  DecoderError<TElements[number]> | DecodeFailure
+> {
+  return {
+    decode(value) {
+      if (!Array.isArray(value)) {
+        return err(new DecodeFailure('Expected tuple.', { cause: value }));
+      }
+
+      if (value.length !== elements.length) {
+        return err(
+          new DecodeFailure(`Expected tuple of length ${elements.length}.`, {
+            cause: value,
+          }),
+        );
+      }
+
+      const decodedValues: unknown[] = [];
+      for (let index = 0; index < elements.length; index += 1) {
+        const elementDecoder = elements[index];
+        if (!elementDecoder) {
+          continue;
+        }
+        const decoded = elementDecoder.decode(value[index]);
+        if (isErr(decoded)) {
+          return err(
+            prependPathIfPossible(decoded.error, index) as
+              | DecoderError<TElements[number]>
+              | DecodeFailure,
+          );
+        }
+        decodedValues.push(decoded.value);
+      }
+
+      return ok(decodedValues as { readonly [K in keyof TElements]: DecoderValue<TElements[K]> });
+    },
+  };
+}
+
+export function option<T, E>(item: Decoder<T, E>): Decoder<Option<T>, E | DecodeFailure> {
+  return union(
+    map(
+      object({
+        tag: literal('some'),
+        value: item,
+      }),
+      (value) => some(value.value) as Option<T>,
+    ),
+    map(
+      object({
+        tag: literal('none'),
+      }),
+      () => none() as Option<T>,
+    ),
+  );
+}
+
+export function result<T, EValue, EDecodeValue, EDecodeError>(
+  okDecoder: Decoder<T, EDecodeValue>,
+  errDecoder: Decoder<EValue, EDecodeError>,
+): Decoder<Result<T, EValue>, EDecodeValue | EDecodeError | DecodeFailure> {
+  return union(
+    map(
+      object({
+        tag: literal('ok'),
+        value: okDecoder,
+      }),
+      (value) => ok(value.value) as Result<T, EValue>,
+    ),
+    map(
+      object({
+        tag: literal('err'),
+        error: errDecoder,
+      }),
+      (value) => err(value.error) as Result<T, EValue>,
+    ),
+  );
+}
+
+export function object<TShape extends ObjectShape>(
+  shape: TShape,
+): Decoder<
+  { readonly [K in keyof TShape]: DecoderValue<TShape[K]> },
+  DecoderError<TShape[keyof TShape]> | DecodeFailure
+> {
+  return {
+    decode(value) {
+      if (!isPlainObject(value)) {
+        return err(new DecodeFailure('Expected object.', { cause: value }));
+      }
+
+      const record = value as Record<string, unknown>;
+      const decodedObject: Record<string, unknown> = {};
+
+      for (const key of Object.keys(shape)) {
+        const decoder = shape[key];
+        if (!decoder) {
+          continue;
+        }
+        const hasKey = key in record;
+        const rawValue = record[key];
+
+        if (!hasKey || rawValue === undefined) {
+          if (isOptionalDecoder(decoder)) {
+            decodedObject[key] = undefined;
+            continue;
+          }
+
+          return err(
+            new DecodeFailure(`Missing field "${key}".`, {
+              cause: value,
+              path: [key],
+            }),
+          );
+        }
+
+        const decoded = decoder.decode(rawValue);
+        if (isErr(decoded)) {
+          return err(
+            prependPathIfPossible(decoded.error, key) as
+              | DecoderError<TShape[keyof TShape]>
+              | DecodeFailure,
+          );
+        }
+
+        decodedObject[key] = decoded.value;
+      }
+
+      return ok(decodedObject as { readonly [K in keyof TShape]: DecoderValue<TShape[K]> });
+    },
+  };
+}
+
+export function field<K extends string, T, E>(
+  key: K,
+  decoder: Decoder<T, E>,
+): Decoder<T, E | DecodeFailure> {
+  const shape = { [key]: decoder } as { readonly [P in K]: Decoder<T, E> };
+  return map(object(shape), (value) => value[key]);
+}
+
+export function optionalField<K extends string, T, E>(
+  key: K,
+  decoder: Decoder<T, E>,
+): Decoder<T | undefined, E | DecodeFailure> {
+  const shape = { [key]: optional(decoder) } as {
+    readonly [P in K]: OptionalDecoder<T, E>;
+  };
+  return map(object(shape), (value) => value[key]);
+}
+
+export function union<A, B, ELeft, ERight>(
+  left: Decoder<A, ELeft>,
+  right: Decoder<B, ERight>,
+): Decoder<A | B, ELeft | ERight | DecodeFailure> {
+  return {
+    decode(value) {
+      const leftDecoded = left.decode(value);
+      if (isErr(leftDecoded)) {
+        const rightDecoded = right.decode(value);
+        if (isErr(rightDecoded)) {
+          return err(
+            new DecodeFailure('Expected one of the union members.', {
+              cause: value,
+            }),
+          );
+        }
+        return rightDecoded;
+      }
+      return leftDecoded;
+    },
+  };
+}
+
+export function map<A, B, E>(
+  decoder: Decoder<A, E>,
+  project: (value: A) => B,
+): Decoder<B, E> {
+  return {
+    decode(value) {
+      const decoded = decoder.decode(value);
+      return isErr(decoded) ? decoded : ok(project(decoded.value));
+    },
+  };
+}
+
+export function andThen<A, B, E>(
+  decoder: Decoder<A, E>,
+  project: (value: A) => Decoder<B, E>,
+): Decoder<B, E> {
+  return {
+    decode(value) {
+      const decoded = decoder.decode(value);
+      return isErr(decoded) ? decoded : project(decoded.value).decode(valueOf(decoded));
+    },
+  };
+}
+
+export function refine<A, B extends A, E>(
+  decoder: Decoder<A, E>,
+  predicate: (value: A) => value is B,
+  message: string,
+): Decoder<B, E | DecodeFailure> {
+  return {
+    decode(value) {
+      const decoded = decoder.decode(value);
+      if (isErr(decoded)) {
+        return decoded;
+      }
+
+      return predicate(decoded.value)
+        ? ok(decoded.value)
+        : err(new DecodeFailure(message, { cause: value }));
+    },
+  };
+}
+
+function prependPathIfPossible<E>(error: E, segment: DecodePathSegment): E | DecodeFailure {
+  return error instanceof DecodeFailure ? error.at(segment) : error;
+}
+
+function isOptionalDecoder(
+  value: Decoder<unknown, unknown>,
+): value is OptionalDecoder<unknown, unknown> {
+  return '__soundscriptOptional' in value &&
+    value.__soundscriptOptional === true;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function valueOf<T>(decoded: { readonly value: T }): T {
+  return decoded.value;
+}

package/project-transform/src/stdlib/derive.d.ts

@@ -0,0 +1,6 @@
+export const eq: unknown;
+export const hash: unknown;
+export const decode: unknown;
+export const encode: unknown;
+export const codec: unknown;
+export const tagged: unknown;

package/project-transform/src/stdlib/derive.js

@@ -0,0 +1,7 @@
+// Macro binding placeholders. The compiler-owned macro pipeline consumes these symbols.
+export const eq = undefined;
+export const hash = undefined;
+export const decode = undefined;
+export const encode = undefined;
+export const codec = undefined;
+export const tagged = undefined;

package/project-transform/src/stdlib/derive.ts

@@ -0,0 +1,7 @@
+// Macro binding placeholders. The compiler-owned macro pipeline consumes these symbols.
+export const eq: unknown = undefined;
+export const hash: unknown = undefined;
+export const decode: unknown = undefined;
+export const encode: unknown = undefined;
+export const codec: unknown = undefined;
+export const tagged: unknown = undefined;

package/project-transform/src/stdlib/encode.d.ts

@@ -0,0 +1,100 @@
+import type { Bind, Kind3, TypeLambda } from 'sts:hkt';
+import { Failure } from 'sts:failures';
+import type { Option, Result } from 'sts:result';
+import type { Contravariant } from 'sts:typeclasses';
+
+export class EncodeFailure extends Failure {
+  constructor(message?: string, cause?: unknown);
+}
+
+// #[variance(T: in, TEncoded: out, E: out)]
+export type Encoder<T, TEncoded = unknown, E = EncodeFailure> = {
+  encode(value: T): Result<TEncoded, E>;
+};
+
+// #[variance(T: in, TEncoded: out, E: out)]
+export type OptionalEncoder<T, TEncoded = T, E = EncodeFailure> =
+  Encoder<T | undefined, TEncoded | undefined, E> & {
+    readonly __soundscriptOptional: true;
+    readonly inner: Encoder<T, TEncoded, E>;
+  };
+
+type EncoderInput<TEncoder> = TEncoder extends Encoder<infer TValue, unknown, unknown> ? TValue
+  : never;
+type EncoderOutput<TEncoder> = TEncoder extends Encoder<unknown, infer TEncoded, unknown>
+  ? TEncoded
+  : never;
+type EncoderError<TEncoder> = TEncoder extends Encoder<unknown, unknown, infer E> ? E : never;
+type ObjectShape = Record<string, Encoder<unknown, unknown, unknown>>;
+type TupleShape = readonly Encoder<unknown, unknown, unknown>[];
+
+export interface EncoderF extends TypeLambda {
+  readonly type: Encoder<this['Args'][2], this['Args'][1], this['Args'][0]>;
+}
+
+export type EncoderKind<E, TEncoded, T> = Kind3<EncoderF, E, TEncoded, T>;
+
+export function fromEncode<T, TEncoded, E>(
+  encode: (value: T) => Result<TEncoded, E>,
+): Encoder<T, TEncoded, E>;
+export function contramap<A, B, TEncoded, E>(
+  encoder: Encoder<A, TEncoded, E>,
+  project: (value: B) => A,
+): Encoder<B, TEncoded, E>;
+export function encoderContravariant<TEncoded, E = EncodeFailure>(): Contravariant<
+  Bind<Bind<EncoderF, [E]>, [TEncoded]>
+>;
+
+export const stringEncoder: Encoder<string, string>;
+export const numberEncoder: Encoder<number, number>;
+export const booleanEncoder: Encoder<boolean, boolean>;
+export const bigintEncoder: Encoder<bigint, bigint>;
+
+export function optional<T, TEncoded, E>(
+  encoder: Encoder<T, TEncoded, E>,
+): OptionalEncoder<T, TEncoded, E>;
+export function lazy<T, TEncoded, E>(
+  getEncoder: () => Encoder<T, TEncoded, E>,
+): Encoder<T, TEncoded, E>;
+export function nullable<T, TEncoded, E>(
+  encoder: Encoder<T, TEncoded, E>,
+): Encoder<T | null, TEncoded | null, E>;
+export function literal<const T extends string | number | boolean | null>(value: T): Encoder<T, T>;
+export function array<T, TEncoded, E>(
+  item: Encoder<T, TEncoded, E>,
+): Encoder<readonly T[], readonly TEncoded[], E | EncodeFailure>;
+export function tuple<const TElements extends TupleShape>(
+  ...elements: TElements
+): Encoder<
+  { readonly [K in keyof TElements]: EncoderInput<TElements[K]> },
+  { readonly [K in keyof TElements]: EncoderOutput<TElements[K]> },
+  EncoderError<TElements[number]>
+>;
+export function option<T, TEncoded, E>(
+  item: Encoder<T, TEncoded, E>,
+): Encoder<
+  Option<T>,
+  { readonly tag: 'none' } | {
+    readonly tag: 'some';
+    readonly value: TEncoded;
+  },
+  E
+>;
+export function result<T, EValue, TEncoded, EEncoded, EOk, EErr>(
+  okEncoder: Encoder<T, TEncoded, EOk>,
+  errEncoder: Encoder<EValue, EEncoded, EErr>,
+): Encoder<
+  Result<T, EValue>,
+  { readonly tag: 'ok'; readonly value: TEncoded } | {
+    readonly error: EEncoded;
+    readonly tag: 'err';
+  },
+  EOk | EErr
+>;
+export function object<TShape extends ObjectShape>(
+  shape: TShape,
+): Encoder<
+  { readonly [K in keyof TShape]: EncoderInput<TShape[K]> },
+  { readonly [K in keyof TShape]: EncoderOutput<TShape[K]> },
+  EncoderError<TShape[keyof TShape]> | EncodeFailure
+>;

package/project-transform/src/stdlib/encode.js

@@ -0,0 +1,130 @@
+import { Failure } from '@soundscript/soundscript/failures';
+import { err, isErr, isOk, isSome, ok } from '@soundscript/soundscript/result';
+export class EncodeFailure extends Failure {
+    constructor(message = 'Failed to encode value.', cause) {
+        super(message, { cause });
+    }
+}
+export function fromEncode(encode) {
+    return {
+        encode,
+    };
+}
+export function contramap(encoder, project) {
+    return fromEncode((value) => encoder.encode(project(value)));
+}
+export function encoderContravariant() {
+    return {
+        contramap,
+    };
+}
+export const stringEncoder = fromEncode((value) => ok(value));
+export const numberEncoder = fromEncode((value) => ok(value));
+export const booleanEncoder = fromEncode((value) => ok(value));
+export const bigintEncoder = fromEncode((value) => ok(value));
+export function optional(encoder) {
+    return {
+        __soundscriptOptional: true,
+        inner: encoder,
+        encode(value) {
+            return value === undefined ? ok(undefined) : encoder.encode(value);
+        },
+    };
+}
+export function lazy(getEncoder) {
+    return fromEncode((value) => getEncoder().encode(value));
+}
+export function nullable(encoder) {
+    return fromEncode((value) => value === null ? ok(null) : encoder.encode(value));
+}
+export function literal(value) {
+    return fromEncode((input) => Object.is(input, value)
+        ? ok(value)
+        : err(new EncodeFailure(`Expected literal ${JSON.stringify(value)}.`, input)));
+}
+export function array(item) {
+    return fromEncode((value) => {
+        const encodedValues = [];
+        for (const entry of value) {
+            const encoded = item.encode(entry);
+            if (isErr(encoded)) {
+                return encoded;
+            }
+            encodedValues.push(encoded.value);
+        }
+        return ok(encodedValues);
+    });
+}
+export function tuple(...elements) {
+    return fromEncode((value) => {
+        const values = value;
+        const encodedValues = [];
+        for (let index = 0; index < elements.length; index += 1) {
+            const elementEncoder = elements[index];
+            if (!elementEncoder) {
+                continue;
+            }
+            const encoded = elementEncoder.encode(values[index]);
+            if (isErr(encoded)) {
+                return encoded;
+            }
+            encodedValues.push(encoded.value);
+        }
+        return ok(encodedValues);
+    });
+}
+export function option(item) {
+    return fromEncode((value) => {
+        if (isSome(value)) {
+            const encoded = item.encode(value.value);
+            return isErr(encoded) ? encoded : ok({ tag: 'some', value: encoded.value });
+        }
+        return ok({ tag: 'none' });
+    });
+}
+export function result(okEncoder, errEncoder) {
+    return fromEncode((value) => {
+        if (isOk(value)) {
+            const encoded = okEncoder.encode(value.value);
+            return isErr(encoded) ? encoded : ok({ tag: 'ok', value: encoded.value });
+        }
+        const encoded = errEncoder.encode(value.error);
+        return isErr(encoded) ? encoded : ok({ tag: 'err', error: encoded.value });
+    });
+}
+export function object(shape) {
+    return fromEncode((value) => {
+        if (!isPlainObject(value)) {
+            return err(new EncodeFailure('Expected object.', value));
+        }
+        const record = value;
+        const encodedObject = {};
+        for (const key of Object.keys(shape)) {
+            const encoder = shape[key];
+            if (!encoder) {
+                continue;
+            }
+            const hasKey = key in record;
+            const rawValue = record[key];
+            if (!hasKey || rawValue === undefined) {
+                if (isOptionalEncoder(encoder)) {
+                    encodedObject[key] = undefined;
+                    continue;
+                }
+                return err(new EncodeFailure(`Missing field "${key}".`, value));
+            }
+            const encoded = encoder.encode(rawValue);
+            if (isErr(encoded)) {
+                return encoded;
+            }
+            encodedObject[key] = encoded.value;
+        }
+        return ok(encodedObject);
+    });
+}
+function isOptionalEncoder(value) {
+    return '__soundscriptOptional' in value && value.__soundscriptOptional === true;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}