@kontor/kontor-sdk 1.0.0-alpha.0

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

@@ -0,0 +1,193 @@
+// integer.ts
+// TODO: i may want to simplify this later
+//
+import * as z from "zod";
+import type { WaveExpr, CodecInstance, CodecConstructor } from "./types.js";
+
+const U64_MAX = (1n << 64n) - 1n;
+export const U64 = z
+  .bigint()
+  .min(0n, { message: "must be ≥ 0" })
+  .max(U64_MAX, { message: "must be ≤ 2^64-1" });
+
+export function parseIntegerWaveExpr(expr: string): _Integer.T {
+  const inner = expr
+    .trim()
+    .replace(/^\{\s*/, "")
+    .replace(/\s*\}$/, "");
+  if (!inner) throw new Error("empty integer expression");
+
+  const parts = inner
+    .split(",")
+    .map((p) => p.trim())
+    .filter(Boolean);
+
+  const seen = new Set<string>();
+  // Default middle limbs to 0 for ergonomics; require r0 + sign.
+  let out: Partial<_Integer.T> & {
+    r0?: bigint;
+    r1?: bigint;
+    r2?: bigint;
+    r3?: bigint;
+  } = {
+    r1: 0n,
+    r2: 0n,
+    r3: 0n,
+  };
+
+  for (const part of parts) {
+    const idx = part.indexOf(":");
+    if (idx === -1) {
+      throw new Error(`expected "key: value", got "${part}"`);
+    }
+    const keyRaw = part.slice(0, idx).trim();
+    const valRaw = part.slice(idx + 1).trim();
+
+    if (seen.has(keyRaw)) throw new Error(`duplicate key "${keyRaw}"`);
+    seen.add(keyRaw);
+
+    switch (keyRaw) {
+      case "r0":
+      case "r1":
+      case "r2":
+      case "r3": {
+        const normalized = valRaw.replace(/_/g, "");
+        if (!/^[+-]?\d+$/.test(normalized)) {
+          throw new Error(`invalid integer for ${keyRaw}: "${valRaw}"`);
+        }
+        const limb = BigInt(normalized);
+        if (limb < 0n || limb > U64_MAX) {
+          throw new Error(`value for ${keyRaw} out of u64 range: ${valRaw}`);
+        }
+        (out as any)[keyRaw] = limb;
+        break;
+      }
+      case "sign": {
+        if (valRaw !== "plus" && valRaw !== "minus") {
+          throw new Error(`invalid sign "${valRaw}" (expected plus|minus)`);
+        }
+        (out as any).sign = valRaw;
+        break;
+      }
+      default:
+        throw new Error(`unexpected key "${keyRaw}"`);
+    }
+  }
+
+  if (out.r0 === undefined) throw new Error(`missing required key "r0"`);
+  if (!out.sign) throw new Error(`missing required key "sign"`);
+
+  return _Integer.schema.parse(out);
+}
+
+// function parseIntegerWaveExpr(expr: string): _IntegerRaw.T {
+//   // strip { ... }
+//   const inner = expr.trim().replace(/^\{|\}$/g, "");
+//
+//   // split at commas at top level
+//   // e.g. ["r0: 1337", "r1: 0", "r2: 0", "r3: 0", "sign: Plus"]
+//   const parts = inner.split(",").map((p) => p.trim());
+//
+//   const out: any = {};
+//   for (const part of parts) {
+//     const [keyRaw, valRaw] = part.split(":").map((s) => s.trim());
+//
+//     if (
+//       keyRaw === "r0" ||
+//       keyRaw === "r1" ||
+//       keyRaw === "r2" ||
+//       keyRaw === "r3"
+//     ) {
+//       out[keyRaw] = Number(valRaw);
+//       continue;
+//     }
+//
+//     if (keyRaw === "sign") {
+//       if (valRaw !== "Plus" && valRaw !== "Minus") {
+//         throw new Error(`invalid sign '${valRaw}' in ${expr}`);
+//       }
+//       out.sign = valRaw;
+//       continue;
+//     }
+//
+//     throw new Error(`unexpected key '${keyRaw}' in ${expr}`);
+//   }
+//
+//   // validate with zod, return typed
+//   return _IntegerRaw.schema.parse(out);
+// }
+
+export namespace _Integer {
+  export namespace Sign {
+    export const schema = z.enum(["plus", "minus"]);
+    export type T = z.infer<typeof schema>;
+  }
+
+  export const schema = z.object({
+    r0: U64,
+    r1: U64,
+    r2: U64,
+    r3: U64,
+    sign: Sign.schema,
+  });
+
+  export type T = z.infer<typeof schema>;
+}
+
+// --- IntegerCodec ------------------------------------------------
+
+// Instance class: represents one integer value in limb/sign form,
+// and can render toWave() / toJs().
+class _IntegerCodec implements CodecInstance<bigint> {
+  public readonly data: _Integer.T;
+
+  constructor(data: _Integer.T) {
+    this.data = data;
+  }
+
+  static fromJs(value: bigint | number): _IntegerCodec {
+    let v = BigInt(value);
+
+    const sign: _Integer.Sign.T = v < 0n ? "minus" : "plus";
+    if (v < 0n) v = -v;
+
+    // break absolute value into four 32-bit limbs (little-endian style)
+    const mask32 = (1n << 32n) - 1n;
+    const r0 = v & mask32;
+    const r1 = (v >> 32n) & mask32;
+    const r2 = (v >> 64n) & mask32;
+    const r3 = (v >> 96n) & mask32;
+
+    return new _IntegerCodec({ r0, r1, r2, r3, sign });
+  }
+
+  static fromKontor(data: _Integer.T): _IntegerCodec {
+    return new _IntegerCodec(data);
+  }
+
+  static parseWave(expr: string): _Integer.T {
+    return _Integer.schema.parse(parseIntegerWaveExpr(expr));
+  }
+
+  // instance -> WaveExpr
+  toWave(): WaveExpr {
+    return `{r0: ${this.data.r0}, r1: ${this.data.r1}, r2: ${this.data.r2}, r3: ${this.data.r3}, sign: ${this.data.sign}}` as WaveExpr;
+  }
+
+  // instance -> JS bigint
+  toJs(): bigint {
+    const value =
+      (BigInt(this.data.r3) << 96n) |
+      (BigInt(this.data.r2) << 64n) |
+      (BigInt(this.data.r1) << 32n) |
+      BigInt(this.data.r0);
+
+    return this.data.sign === "minus" ? -value : value;
+  }
+}
+
+export const IntegerCodec = _IntegerCodec as unknown as CodecConstructor<
+  bigint,
+  _IntegerCodec,
+  _Integer.T
+>;

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

@@ -0,0 +1,154 @@
+import type {
+  WaveExpr,
+  CodecConstructor,
+  CodecInstance,
+  CodecJs,
+  CodecInst,
+  CodecWave,
+} from "./types.js";
+
+// The JS-side shape we expose for list<T>
+export type ListJs<T> = T[];
+
+/**
+ * Instance that represents a decoded list<Inner> value.
+ *
+ * Generic parameterization is on the *inner codec constructor* so that
+ * the JS type of this list instance is always ListJs<CodecJs<InnerC>>.
+ */
+export class ListCodecFactory<
+  InnerC extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
+> implements CodecInstance<ListJs<CodecJs<InnerC>>>
+{
+  constructor(
+    private readonly innerCodec: InnerC,
+    public readonly data: string[], // array of wave expressions for each element
+  ) {}
+
+  toWave(): WaveExpr {
+    // Convert array of inner wave expressions back to array syntax
+    const innerWaves = this.data.join(", ");
+    return `[${innerWaves}]` as WaveExpr;
+  }
+
+  toJs(): ListJs<CodecJs<InnerC>> {
+    // Decode each element using the inner codec
+    return this.data.map((innerWave) => {
+      // 1) parse inner WaveExpr → inner WaveData
+      const innerWaveData = this.innerCodec.parseWave(
+        innerWave,
+      ) as CodecWave<InnerC>;
+
+      // 2) WaveData → inner instance
+      const innerInst = this.innerCodec.fromKontor(
+        innerWaveData,
+      ) as CodecInst<InnerC>;
+
+      // 3) instance → JS
+      return innerInst.toJs() as CodecJs<InnerC>;
+    });
+  }
+
+  // ----- Static factory to build a typed list<T> codec constructor -----
+
+  static create<
+    InnerC extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
+  >(
+    innerCodec: InnerC,
+  ): CodecConstructor<
+    // JS type this codec produces:
+    ListJs<CodecJs<InnerC>>,
+    // instance type:
+    ListCodecFactory<InnerC>,
+    // wave data type (array of inner wave strings):
+    string[]
+  > {
+    // Class expression implements the static methods required by CodecConstructor
+    class ListCodecClass implements CodecInstance<ListJs<CodecJs<InnerC>>> {
+      // Internally forward all instance behavior to ListCodecFactory
+      private readonly _impl: ListCodecFactory<InnerC>;
+
+      constructor(data: string[]) {
+        this._impl = new ListCodecFactory(innerCodec, data);
+      }
+
+      toWave(): WaveExpr {
+        return this._impl.toWave();
+      }
+
+      toJs(): ListJs<CodecJs<InnerC>> {
+        return this._impl.toJs();
+      }
+
+      // ----- Static methods required by CodecConstructor -----
+
+      static fromJs(value: ListJs<CodecJs<InnerC>>): ListCodecClass {
+        // Convert JS array to array of wave expressions
+        const waveArray = value.map((item) => {
+          const innerInst = innerCodec.fromJs(item as any);
+          return innerInst.toWave();
+        });
+        return new ListCodecClass(waveArray);
+      }
+
+      static fromKontor(data: string[]): ListCodecClass {
+        return new ListCodecClass(data);
+      }
+
+      static parseWave(expr: string): string[] {
+        // Parse array syntax: "[item1, item2, ...]"
+        const trimmed = expr.trim();
+
+        // Empty array
+        if (trimmed === "[]") {
+          return [];
+        }
+
+        // Remove brackets
+        if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+          throw new Error(`Expected array syntax [...], got: ${expr}`);
+        }
+
+        const inner = trimmed.slice(1, -1).trim();
+        if (inner === "") {
+          return [];
+        }
+
+        // Split by commas at the top level (respecting nested structures)
+        const items: string[] = [];
+        let depth = 0;
+        let current = "";
+
+        for (let i = 0; i < inner.length; i++) {
+          const char = inner[i];
+
+          if (char === "{" || char === "[" || char === "(") {
+            depth++;
+            current += char;
+          } else if (char === "}" || char === "]" || char === ")") {
+            depth--;
+            current += char;
+          } else if (char === "," && depth === 0) {
+            items.push(current.trim());
+            current = "";
+          } else {
+            current += char;
+          }
+        }
+
+        // Add last item
+        if (current.trim()) {
+          items.push(current.trim());
+        }
+
+        return items;
+      }
+    }
+
+    return ListCodecClass as unknown as CodecConstructor<
+      ListJs<CodecJs<InnerC>>,
+      ListCodecFactory<InnerC>,
+      string[]
+    >;
+  }
+}

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

@@ -0,0 +1,128 @@
+import type {
+  WaveExpr,
+  CodecConstructor,
+  CodecInstance,
+  CodecJs,
+  CodecInst,
+  CodecWave,
+} from "./types.js";
+
+import { Enum } from "./enum.js";
+
+export const KontorOption = Enum.Option;
+
+// The JS-side shape we expose for option<T>
+export type OptionJs<T> = { kind: "none" } | { kind: "some"; value: T };
+
+/**
+ * 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
+  ) {}
+
+  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;
+  }
+
+  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,
+        });
+      }
+
+      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/string.ts

@@ -0,0 +1,30 @@
+import type { CodecConstructor, CodecInstance, WaveExpr } 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;
+      },
+    };
+  },
+
+  fromKontor(data: string) {
+    return {
+      toWave(): WaveExpr {
+        return `"${data}"` as WaveExpr;
+      },
+      toJs(): String {
+        return data as String;
+      },
+    };
+  },
+
+  parseWave(expr: string): string {
+    return JSON.parse(expr);
+  },
+} as unknown as CodecConstructor<String, CodecInstance<String>, string>;

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

@@ -0,0 +1,111 @@
+export type Unit = { readonly _tag: "Unit" };
+export const unit: Unit = { _tag: "Unit" };
+
+export type Address = string & { readonly __brand: "Address" };
+
+export type WaveExpr = string & { readonly __brand: "WaveExpr" };
+
+export interface ToWave {
+  toWave(): WaveExpr;
+}
+
+export interface ToJs<JS> {
+  toJs(): JS;
+}
+
+export interface WaveConvertible<JS> extends ToWave, ToJs<JS> {}
+
+// Keep for compatibility: "instance members only"
+// @ts-ignore
+export interface WaveCodec<JS, WaveData> extends WaveConvertible<JS> {}
+
+// The runtime instance a codec produces (must be convertible both ways)
+export interface CodecInstance<JS> extends WaveConvertible<JS> {}
+
+// ---------- Codec constructor shape (no `any`) ----------
+
+export type CodecConstructor<
+  JS,
+  I extends CodecInstance<JS>,
+  W = unknown, // parser payload / AST type
+> = {
+  // runtime instance constructor (usually unused directly)
+  new (...args: unknown[]): I;
+
+  // static: from JS → instance
+  fromJs(value: JS): I;
+
+  // static: parse raw wave expr → parser payload
+  parseWave(expr: string): W;
+
+  // static: from parser payload → instance
+  fromKontor(data: W): I;
+};
+
+// ---------- Type helpers to extract associated types ----------
+
+export type CodecJs<C> =
+  C extends CodecConstructor<infer JS, any, any> ? JS : never;
+export type CodecInst<C> =
+  C extends CodecConstructor<any, infer I, any> ? I : never;
+export type CodecWave<C> =
+  C extends CodecConstructor<any, any, infer W> ? W : never;
+
+// ---------- Schema & inference over schema ----------
+
+export type Schema = Record<
+  string,
+  CodecConstructor<unknown, CodecInstance<unknown>, unknown>
+>;
+
+export type InferJS<S extends Schema> = {
+  [K in keyof S]: CodecJs<S[K]>;
+};
+
+export type InferInstance<S extends Schema> = {
+  [K in keyof S]: CodecInst<S[K]>;
+};
+
+export type InferWaveData<S extends Schema> = {
+  [K in keyof S]: CodecWave<S[K]>;
+};
+
+// ---------- Encoder: JS → WaveExpr (fully type-safe) ----------
+
+export class Encoder<S extends Schema> {
+  constructor(private readonly schema: S) {}
+
+  encode(values: InferJS<S>): { [K in keyof S]: WaveExpr } {
+    const out = {} as { [K in keyof S]: WaveExpr };
+    for (const key of Object.keys(this.schema) as Array<keyof S>) {
+      const ctor = this.schema[key]!;
+      const inst = ctor.fromJs(values[key]);
+      out[key] = inst.toWave();
+    }
+    return out;
+  }
+}
+
+// ---------- Decoder: WaveExpr → JS (inferred from codec) ----------
+
+export class Decoder<
+  C extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
+> {
+  constructor(private readonly codec: C) {}
+
+  decode(expr: string): CodecJs<C> {
+    console.log("in tuple decode");
+    const wave = this.codec.parseWave(expr) as CodecWave<C>;
+    console.log({ wave });
+    const inst = this.codec.fromKontor(wave) as CodecInst<C>;
+    console.log({ inst });
+    return inst.toJs() as CodecJs<C>;
+  }
+}
+
+// Optional ergonomic helper so callers don't write generics at `new` sites
+export function makeDecoder<
+  C extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
+>(codec: C) {
+  return new Decoder<C>(codec);
+}

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

@@ -0,0 +1,38 @@
+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
+>;