@kontor/kontor-sdk 1.0.0-alpha.39 → 1.0.0-alpha.40

package/src/sdk/utils/wit/codecs/option.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+
+import { OptionCodec } from "./option.js";
+import { IntegerCodec } from "./numerics.js"; // adjust if different path
+
+import type { Option } from "../../../../wit/utils.js";
+
+describe("optionCodec", () => {
+  const OptionOfInteger = OptionCodec(IntegerCodec);
+  it("decodes and encodes none", () => {
+    expect(OptionOfInteger.decodeWave("none")).toEqual(["none"]);
+    expect(OptionOfInteger.encodeWave(["none"])).toBe("none");
+  });
+
+  it("decodes some(<wave>) by delegating to the inner codec", () => {
+    const wave = "some({r0: 7, r1: 0, r2: 0, r3: 0, sign: plus})";
+    const decoded = OptionOfInteger.decodeWave(wave);
+
+    expect(decoded).toEqual(["some", 7n] satisfies Option<bigint>);
+  });
+
+  it("encodes some(value) using the inner codec's canonical encoding", () => {
+    const js: Option<bigint> = ["some", 7n];
+    expect(OptionOfInteger.encodeWave(js)).toBe(
+      "some({r0: 7, r1: 0, r2: 0, r3: 0, sign: plus})",
+    );
+  });
+
+  it("round-trips: decode -> encode -> decode", () => {
+    const wave = "some({r0: 123, r1: 0, r2: 0, r3: 0, sign: plus})";
+    const js1 = OptionOfInteger.decodeWave(wave);
+    const wave2 = OptionOfInteger.encodeWave(js1);
+    const js2 = OptionOfInteger.decodeWave(wave2);
+    expect(js2).toEqual(js1);
+  });
+
+  it("throws on invalid option constructor", () => {
+    expect(() => OptionOfInteger.decodeWave("ok(1)")).toThrow(
+      "invalid option: ok(1)",
+    );
+    expect(() => OptionOfInteger.decodeWave("err(1)")).toThrow(
+      "invalid option: err(1)",
+    );
+  });
+
+  it("throws when some() has an empty argument", () => {
+    expect(() => OptionOfInteger.decodeWave("some()")).toThrow(
+      "invalid option: some()",
+    );
+    expect(() => OptionOfInteger.decodeWave("some(   )")).toThrow(
+      "invalid option: some(   )",
+    );
+  });
+
+  it("throws when trailing junk exists after some(...)", () => {
+    // parseConstructorCall will throw, and we want to preserve that behavior
+    expect(() => OptionOfInteger.decodeWave("some(1))")).toThrow(
+      'unexpected trailing characters after some(...): ")"',
+    );
+    expect(() => OptionOfInteger.decodeWave("some(1) nope")).toThrow(
+      'unexpected trailing characters after some(...): "nope"',
+    );
+  });
+
+  it("allows whitespace around the whole expression", () => {
+    const wave = "  some({r0: 7, r1: 0, r2: 0, r3: 0, sign: plus})  ";
+    expect(OptionOfInteger.decodeWave(wave)).toEqual(["some", 7n]);
+  });
+
+  // TODO: add nested
+});

package/src/sdk/utils/wit/codecs/option.ts

@@ -1,128 +1,29 @@
-import type {
-  WaveExpr,
-  CodecConstructor,
-  CodecInstance,
-  CodecJs,
-  CodecInst,
-  CodecWave,
-} from "./types.js";
+import { type Codec } from "./types.js";
+import { parseConstructorCall } from "./util.js";
 
-import { Enum } from "./enum.js";
+import type { Option } from "../../../../wit/utils.js";
 
-export const KontorOption = Enum.Option;
+export function OptionCodec<T>(inner: Codec<T>): Codec<Option<T>> {
+  return {
+    decodeWave(expr: string): Option<T> {
+      const s = expr.trim();
 
-// The JS-side shape we expose for option<T>
-export type OptionJs<T> = { kind: "none" } | { kind: "some"; value: T };
+      if (s === "none") return ["none"];
 
-/**
- * Instance that represents a decoded option<Inner> value.
- *
- * Generic parameterization is on the *inner codec constructor* so that
- * the JS type of this option instance is always OptionJs<CodecJs<InnerC>>.
- */
-export class OptionCodecFactory<
-  InnerC extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
-> implements CodecInstance<OptionJs<CodecJs<InnerC>>>
-{
-  constructor(
-    private readonly innerCodec: InnerC,
-    public readonly data: Enum.Option.T, // parsed wave data for option
-  ) {}
+      const { name, arg } = parseConstructorCall(s); // shared wave util
+      if (name !== "some" || arg == null)
+        throw new Error(`invalid option: ${expr}`);
 
-  toWave(): WaveExpr {
-    if (this.data.kind === "none") {
-      return "none" as WaveExpr;
-    }
-    // assume data.value is a WaveExpr string for the inner
-    return `some(${this.data.value ?? ""})` as WaveExpr;
-  }
+      return ["some", inner.decodeWave(arg)];
+    },
 
-  toJs(): OptionJs<CodecJs<InnerC>> {
-    if (this.data.kind === "none") {
-      return { kind: "none" };
-    }
-    if (this.data.value == null) {
-      throw new Error("Option some() has no inner value");
-    }
-
-    // 1) parse inner WaveExpr → inner WaveData
-    const innerWaveData = this.innerCodec.parseWave(
-      this.data.value,
-    ) as CodecWave<InnerC>;
-
-    // 2) WaveData → inner instance
-    const innerInst = this.innerCodec.fromKontor(
-      innerWaveData,
-    ) as CodecInst<InnerC>;
-
-    // 3) instance → JS
-    return { kind: "some", value: innerInst.toJs() as CodecJs<InnerC> };
-  }
-
-  // ----- Static factory to build a typed option<T> codec constructor -----
-
-  static create<
-    InnerC extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
-  >(
-    innerCodec: InnerC,
-  ): CodecConstructor<
-    // JS type this codec produces:
-    OptionJs<CodecJs<InnerC>>,
-    // instance type:
-    OptionCodecFactory<InnerC>,
-    // wave data type (parsed form of "none" | "some(<inner>)"):
-    Enum.Option.T
-  > {
-    // Class expression implements the static methods required by CodecConstructor
-    class OptionCodecClass implements CodecInstance<OptionJs<CodecJs<InnerC>>> {
-      // Internally forward all instance behavior to OptionCodecInstance
-      private readonly _impl: OptionCodecFactory<InnerC>;
-
-      constructor(data: Enum.Option.T) {
-        this._impl = new OptionCodecFactory(innerCodec, data);
-      }
-
-      // ----- CodecConstructor statics -----
-
-      static fromJs(
-        value: OptionJs<CodecJs<InnerC>>,
-      ): OptionCodecFactory<InnerC> {
-        if (value.kind === "none") {
-          return new OptionCodecFactory(innerCodec, { kind: "none" });
-        }
-        // encode inner via innerCodec
-        const innerInst = innerCodec.fromJs(value.value as CodecJs<InnerC>);
-        const innerWave = innerInst.toWave();
-        return new OptionCodecFactory(innerCodec, {
-          kind: "some",
-          value: innerWave,
-        });
+    encodeWave(value: Option<T>): string {
+      switch (value[0]) {
+        case "none":
+          return "none";
+        case "some":
+          return `some(${inner.encodeWave(value[1])})`;
       }
-
-      static parseWave(expr: string): Enum.Option.T {
-        // Expect raw "none" or "some(<inner...>)"
-        return Enum.Option.schema.parse(expr);
-      }
-
-      static fromKontor(data: Enum.Option.T): OptionCodecFactory<InnerC> {
-        return new OptionCodecFactory(innerCodec, data);
-      }
-
-      // ----- Instance side -----
-
-      toWave(): WaveExpr {
-        return this._impl.toWave();
-      }
-      toJs(): OptionJs<CodecJs<InnerC>> {
-        return this._impl.toJs();
-      }
-    }
-
-    // Satisfy the CodecConstructor contract with precise generics
-    return OptionCodecClass as unknown as CodecConstructor<
-      OptionJs<CodecJs<InnerC>>,
-      OptionCodecFactory<InnerC>,
-      Enum.Option.T
-    >;
-  }
+    },
+  };
 }

package/src/sdk/utils/wit/codecs/result.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { ResultCodec } from "./result.js";
+import { IntegerCodec, DecimalCodec } from "./numerics.js";
+import type { Result } from "../../../../wit/utils.js";
+
+describe("ResultCodec", () => {
+  const ResultOfIntegerDecimal = ResultCodec(IntegerCodec, DecimalCodec);
+
+  it("decodes ok(<wave>) by delegating to the ok codec", () => {
+    const wave = "ok({r0: 7, r1: 0, r2: 0, r3: 0, sign: plus})";
+    const decoded = ResultOfIntegerDecimal.decodeWave(wave);
+
+    expect(decoded).toEqual(["ok", 7n] satisfies Result<
+      bigint,
+      [bigint, number]
+    >);
+  });
+
+  it("decodes err(<wave>) by delegating to the err codec", () => {
+    const wave = "err({r0: 9, r1: 0, r2: 0, r3: 0, sign: minus})";
+    const decoded = ResultOfIntegerDecimal.decodeWave(wave);
+
+    // DecimalCodec decodes to [coef, 18]
+    expect(decoded).toEqual(["err", [-9n, 18]] satisfies Result<
+      bigint,
+      [bigint, number]
+    >);
+  });
+
+  it("encodes ok and err with canonical inner encodings", () => {
+    expect(ResultOfIntegerDecimal.encodeWave(["ok", 7n])).toBe(
+      "ok({r0: 7, r1: 0, r2: 0, r3: 0, sign: plus})",
+    );
+
+    expect(ResultOfIntegerDecimal.encodeWave(["err", [-9n, 18]])).toBe(
+      "err({r0: 9, r1: 0, r2: 0, r3: 0, sign: minus})",
+    );
+  });
+
+  it("round-trips: decode -> encode -> decode", () => {
+    const wave1 = "ok({r0: 123, r1: 0, r2: 0, r3: 0, sign: plus})";
+    const js1 = ResultOfIntegerDecimal.decodeWave(wave1);
+    const wave2 = ResultOfIntegerDecimal.encodeWave(js1);
+    const js2 = ResultOfIntegerDecimal.decodeWave(wave2);
+
+    expect(js2).toEqual(js1);
+    expect(wave2).toBe(wave1);
+  });
+
+  it("throws on invalid constructor names", () => {
+    expect(() => ResultOfIntegerDecimal.decodeWave("some(1)")).toThrow(
+      "invalid result: some(1)",
+    );
+    expect(() => ResultOfIntegerDecimal.decodeWave("none")).toThrow(
+      "invalid result: none",
+    );
+  });
+
+  it("throws when ok()/err() has an empty argument", () => {
+    expect(() => ResultOfIntegerDecimal.decodeWave("ok()")).toThrow(
+      "invalid result: ok()",
+    );
+    expect(() => ResultOfIntegerDecimal.decodeWave("err(   )")).toThrow(
+      "invalid result: err(   )",
+    );
+  });
+
+  it("throws when trailing junk exists after ok(...)/err(...)", () => {
+    // parseConstructorCall is responsible for this error text
+    expect(() => ResultOfIntegerDecimal.decodeWave("ok(1))")).toThrow(
+      'unexpected trailing characters after ok(...): ")"',
+    );
+    expect(() => ResultOfIntegerDecimal.decodeWave("err(1) nope")).toThrow(
+      'unexpected trailing characters after err(...): "nope"',
+    );
+  });
+
+  it("allows whitespace around the whole expression", () => {
+    const wave = "  ok({r0: 7, r1: 0, r2: 0, r3: 0, sign: plus})  ";
+    expect(ResultOfIntegerDecimal.decodeWave(wave)).toEqual(["ok", 7n]);
+  });
+});

package/src/sdk/utils/wit/codecs/result.ts

@@ -0,0 +1,37 @@
+// result.ts
+import type { Result } from "../../../../wit/utils.js";
+import type { Codec } from "./types.js";
+import { parseConstructorCall } from "./util.js";
+
+export function ResultCodec<T, E>(
+  ok: Codec<T>,
+  err: Codec<E>,
+): Codec<Result<T, E>> {
+  return {
+    decodeWave(expr: string): Result<T, E> {
+      const s = expr.trim();
+      const { name, arg } = parseConstructorCall(s);
+
+      if (name === "ok") {
+        if (arg == null) throw new Error(`invalid result: ${expr}`);
+        return ["ok", ok.decodeWave(arg)];
+      }
+
+      if (name === "err") {
+        if (arg == null) throw new Error(`invalid result: ${expr}`);
+        return ["err", err.decodeWave(arg)];
+      }
+
+      throw new Error(`invalid result: ${expr}`);
+    },
+
+    encodeWave(value: Result<T, E>): string {
+      switch (value[0]) {
+        case "ok":
+          return `ok(${ok.encodeWave(value[1])})`;
+        case "err":
+          return `err(${err.encodeWave(value[1])})`;
+      }
+    },
+  };
+}

package/src/sdk/utils/wit/codecs/string.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { StringCodec } from "./string.js";
+
+describe("StringCodec", () => {
+  it("decodes quoted strings", () => {
+    expect(StringCodec.decodeWave(`"hello"`)).toBe("hello");
+    expect(StringCodec.decodeWave(`"  spaced  "`)).toBe("  spaced  ");
+  });
+
+  it("encodes using JSON escaping rules", () => {
+    expect(StringCodec.encodeWave("hello")).toBe(`"hello"`);
+    expect(StringCodec.encodeWave(`he said "yo"`)).toBe(`"he said \\"yo\\""`);
+    expect(StringCodec.encodeWave("a\\b")).toBe(`"a\\\\b"`);
+    expect(StringCodec.encodeWave("line1\nline2")).toBe(`"line1\\nline2"`);
+  });
+
+  it("round-trips", () => {
+    const values = [
+      "",
+      "ascii",
+      `quote: "`,
+      "backslash: \\",
+      "newline:\n",
+      "tab:\t",
+      "emoji: 😀",
+      "json-ish: {a:1} [x] (y), commas, colons: :",
+    ];
+
+    for (const v of values) {
+      const wave = StringCodec.encodeWave(v);
+      const decoded = StringCodec.decodeWave(wave);
+      expect(decoded).toBe(v);
+    }
+  });
+
+  it("throws on non-strings / invalid wave", () => {
+    expect(() => StringCodec.decodeWave("hello")).toThrow(
+      "invalid string: hello",
+    );
+    expect(() => StringCodec.decodeWave("123")).toThrow("invalid string: 123");
+    expect(() => StringCodec.decodeWave("true")).toThrow(
+      "invalid string: true",
+    );
+    expect(() => StringCodec.decodeWave("null")).toThrow(
+      "invalid string: null",
+    );
+
+    // bad JSON string
+    expect(() => StringCodec.decodeWave(`"unterminated`)).toThrow(
+      'invalid string: "unterminated',
+    );
+
+    // JSON.parse can return non-string if not quoted (we guard earlier), but keep a sanity check
+    expect(() => StringCodec.decodeWave(`{"a":1}`)).toThrow(
+      'invalid string: {"a":1}',
+    );
+  });
+
+  it("allows whitespace around the whole expression", () => {
+    expect(StringCodec.decodeWave(`   "hi"   `)).toBe("hi");
+  });
+});

package/src/sdk/utils/wit/codecs/string.ts

@@ -1,30 +1,28 @@
-import type { CodecConstructor, CodecInstance, WaveExpr } from "./types.js";
+import type { Codec } from "./types.js";
 
-export const StringCodec = {
-  fromJs(value: String) {
-    return {
-      toWave(): WaveExpr {
-        // Wave syntax for string args: we assume quoted
-        return `"${value}"` as WaveExpr;
-      },
-      toJs(): String {
-        return value;
-      },
-    };
-  },
+/**
+ * Wave string literals follow JSON escaping rules (double-quoted).
+ * We encode using JSON.stringify to ensure valid escaping.
+ */
+export const StringCodec: Codec<string> = {
+  decodeWave(expr: string): string {
+    const s = expr.trim();
+    // Require quoted string (Wave/JSON style)
+    if (s.length < 2 || s[0] !== `"` || s[s.length - 1] !== `"`) {
+      throw new Error(`invalid string: ${expr}`);
+    }
 
-  fromKontor(data: string) {
-    return {
-      toWave(): WaveExpr {
-        return `"${data}"` as WaveExpr;
-      },
-      toJs(): String {
-        return data as String;
-      },
-    };
+    try {
+      const v = JSON.parse(s);
+      if (typeof v !== "string") throw new Error("not a string");
+      return v;
+    } catch {
+      throw new Error(`invalid string: ${expr}`);
+    }
   },
 
-  parseWave(expr: string): string {
-    return JSON.parse(expr);
+  encodeWave(value: string): string {
+    // JSON.stringify returns a valid double-quoted JSON string literal
+    return JSON.stringify(value);
   },
-} as unknown as CodecConstructor<String, CodecInstance<String>, string>;
+};

package/src/sdk/utils/wit/codecs/types.ts

@@ -106,3 +106,8 @@ export function makeDecoder<
 >(codec: C) {
   return new Decoder<C>(codec);
 }
+
+export type Codec<T> = {
+  decodeWave(expr: string): T;
+  encodeWave(value: T): string; // or WaveExpr if you keep that brand
+};

package/src/sdk/utils/wit/codecs/unit.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { UnitCodec } from "./unit.js";
+import { unit } from "./types.js";
+
+describe("UnitCodec", () => {
+  it("decodes underscore to unit", () => {
+    expect(UnitCodec.decodeWave("_")).toBe(unit);
+    expect(UnitCodec.decodeWave("  _ \n")).toBe(unit);
+  });
+
+  it("encodes unit to underscore", () => {
+    expect(UnitCodec.encodeWave(unit)).toBe("_");
+  });
+
+  it("round-trips", () => {
+    const wave = UnitCodec.encodeWave(unit);
+    expect(wave).toBe("_");
+    expect(UnitCodec.decodeWave(wave)).toBe(unit);
+  });
+
+  it("throws on invalid input", () => {
+    expect(() => UnitCodec.decodeWave("")).toThrow("invalid unit:");
+    expect(() => UnitCodec.decodeWave("()")).toThrow("invalid unit: ()");
+    expect(() => UnitCodec.decodeWave("none")).toThrow("invalid unit: none");
+    expect(() => UnitCodec.decodeWave("__")).toThrow("invalid unit: __");
+  });
+});

package/src/sdk/utils/wit/codecs/unit.ts

@@ -1,38 +1,14 @@
-import {
-  type CodecConstructor,
-  type CodecInstance,
-  type Unit,
-  unit,
-  type WaveExpr,
-} from "./types.js";
-
-class _UnitCodec implements CodecInstance<Unit> {
-  constructor() {}
-
-  static fromJs(_value: null): _UnitCodec {
-    return new _UnitCodec();
-  }
-
-  static fromKontor(_data: unknown): _UnitCodec {
-    return new _UnitCodec();
-  }
-
-  static parseWave(_expr: string): Unit {
-    // ok branch payload is conceptually "unit"
-    return unit;
-  }
-
-  toWave(): WaveExpr {
-    return "" as WaveExpr;
-  }
-
-  toJs(): Unit {
-    return unit;
-  }
-}
-
-export const UnitCodec = _UnitCodec as unknown as CodecConstructor<
-  Unit,
-  _UnitCodec,
-  unknown
->;
+import type { Codec, Unit } from "./types.js";
+import { unit } from "./types.js";
+
+export const UnitCodec: Codec<Unit> = {
+  decodeWave(expr: string): Unit {
+    const s = expr.trim();
+    if (s === "_") return unit;
+    throw new Error(`invalid unit: ${expr}`);
+  },
+
+  encodeWave(_value: Unit): string {
+    return "_";
+  },
+};