@seljs/checker 1.0.0 → 1.0.1

package/dist/checker/type-compatibility.js

@@ -1,59 +0,0 @@
-const LOGICAL_OPERATORS = new Set(["&&", "||"]);
-const ARITHMETIC_OPERATORS = new Set(["+", "-", "*", "/", "%"]);
-const COMPARISON_OPERATORS = new Set(["<", "<=", ">", ">="]);
-const EQUALITY_OPERATORS = new Set(["==", "!="]);
-/** Types that support arithmetic operators (same-type only). */
-const ARITHMETIC_TYPES = new Set(["int", "uint", "double", "sol_int"]);
-/** Types that support the + operator for concatenation. */
-const CONCATENATION_TYPES = new Set(["string", "list", "bytes"]);
-/** Types that support comparison operators (same-type only). */
-const COMPARISON_TYPES = new Set([
-    "int",
-    "uint",
-    "double",
-    "string",
-    "bytes",
-    "sol_address",
-    "sol_int",
-]);
-/**
- * Given the type of the left operand and the operator,
- * returns the expected type for the right operand.
- *
- * Based on the registered operators in register-types.ts.
- * Type compatibility is strictly same-type (no implicit coercion).
- *
- * Returns undefined when the type/operator combination is unknown,
- * signaling that no narrowing should occur.
- */
-export const expectedTypeForOperator = (leftType, operator) => {
-    if (LOGICAL_OPERATORS.has(operator)) {
-        return "bool";
-    }
-    if (ARITHMETIC_OPERATORS.has(operator)) {
-        if (ARITHMETIC_TYPES.has(leftType)) {
-            return leftType;
-        }
-        if (operator === "+" && CONCATENATION_TYPES.has(leftType)) {
-            return leftType;
-        }
-        return undefined;
-    }
-    if (COMPARISON_OPERATORS.has(operator)) {
-        return COMPARISON_TYPES.has(leftType) ? leftType : undefined;
-    }
-    if (EQUALITY_OPERATORS.has(operator)) {
-        return leftType;
-    }
-    return undefined;
-};
-/**
- * Check if a candidate type is compatible with an expected type.
- * "dyn" is a wildcard — compatible with anything in either direction.
- */
-export const isTypeCompatible = (candidateType, expectedType) => {
-    if (expectedType === "dyn" || candidateType === "dyn") {
-        return true;
-    }
-    return candidateType === expectedType;
-};

package/dist/constants.d.ts

@@ -1,4 +0,0 @@
-/** Comprehension macro names that introduce scoped iteration variables. */
-export declare const COMPREHENSION_MACROS: Set<string>;
-/** Solidity scalar wrapper functions (pass-through for arg classification). */
-export declare const SCALAR_WRAPPER_FUNCTIONS: Set<string>;

package/dist/constants.js

@@ -1,10 +0,0 @@
-/** Comprehension macro names that introduce scoped iteration variables. */
-export const COMPREHENSION_MACROS = new Set([
-    "map",
-    "filter",
-    "exists",
-    "all",
-    "exists_one",
-]);
-/** Solidity scalar wrapper functions (pass-through for arg classification). */
-export const SCALAR_WRAPPER_FUNCTIONS = new Set(["solInt", "solAddress"]);

package/dist/debug.d.ts

@@ -1,2 +0,0 @@
-import createDebug from "debug";
-export declare const createLogger: (namespace: string) => createDebug.Debugger;

package/dist/debug.js

@@ -1,2 +0,0 @@
-import createDebug from "debug";
-export const createLogger = (namespace) => createDebug(`sel:checker:${namespace}`);

package/dist/environment/codec-registry.d.ts

@@ -1,42 +0,0 @@
-import { z } from "zod";
-type AnyCodec = z.ZodType;
-/**
- * Struct descriptor provided to CelCodecRegistry.
- */
-export interface StructCodecDescriptor {
-    name: string;
-    ctor: new () => object;
-    fieldNames: string[];
-    fieldTypes: Record<string, string>;
-}
-/**
- * Options for constructing a CelCodecRegistry.
- */
-export interface CelCodecRegistryOptions {
-    structs?: StructCodecDescriptor[];
-}
-/**
- * Registry that maps CEL type strings to bidirectional Zod 4 codecs.
- * Immutable after construction — all codecs resolved eagerly.
- */
-export declare class CelCodecRegistry {
-    private readonly codecs;
-    private readonly structMetas;
-    constructor(options?: CelCodecRegistryOptions);
-    /**
-     * Resolve a codec for the given CEL type string.
-     * Handles `list<T>` container types by composing element codecs.
-     * Unknown types fall back to z.unknown().
-     */
-    resolve(celType: string): AnyCodec;
-    /**
-     * Encode a CEL value back to its raw form using the codec for the given type.
-     * For bidirectional codecs (SolidityAddress, SolidityInt) this calls .encode().
-     * For structs, it recursively encodes each field.
-     * For passthrough types (bool, string, int), returns the value as-is.
-     */
-    encode(celType: string, value: unknown): unknown;
-    private buildStructCodec;
-    private decodeField;
-}
-export {};

package/dist/environment/codec-registry.js

@@ -1,146 +0,0 @@
-import { SolidityAddressTypeWrapper, SolidityIntTypeWrapper, } from "@seljs/types";
-import { z } from "zod";
-const solidityAddressCodec = z.codec(z.string(), z.instanceof(SolidityAddressTypeWrapper), {
-    decode: (s) => new SolidityAddressTypeWrapper(s),
-    encode: (w) => w.value,
-});
-const solidityIntCodec = z.codec(z.union([z.bigint(), z.number().transform((n) => BigInt(n))]), z.instanceof(SolidityIntTypeWrapper), {
-    decode: (n) => new SolidityIntTypeWrapper(n),
-    encode: (w) => w.value,
-});
-/**
- * Registry that maps CEL type strings to bidirectional Zod 4 codecs.
- * Immutable after construction — all codecs resolved eagerly.
- */
-export class CelCodecRegistry {
-    codecs;
-    structMetas;
-    constructor(options) {
-        this.codecs = new Map();
-        this.structMetas = new Map();
-        // Register base codecs
-        this.codecs.set("sol_address", solidityAddressCodec);
-        this.codecs.set("sol_int", solidityIntCodec);
-        this.codecs.set("bool", z.boolean());
-        this.codecs.set("string", z.string());
-        this.codecs.set("int", z.bigint());
-        this.codecs.set("bytes", z.union([
-            z.instanceof(Uint8Array),
-            z.string().transform((s) => {
-                const hex = s.startsWith("0x") ? s.slice(2) : s;
-                const bytes = new Uint8Array(hex.length / 2);
-                for (let i = 0; i < bytes.length; i++) {
-                    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-                }
-                return bytes;
-            }),
-        ]));
-        this.codecs.set("dyn", z
-            .unknown()
-            .transform((v) => typeof v === "bigint" ? new SolidityIntTypeWrapper(v) : v));
-        // Register struct codecs eagerly
-        for (const desc of options?.structs ?? []) {
-            this.codecs.set(desc.name, this.buildStructCodec(desc));
-            this.structMetas.set(desc.name, {
-                fieldNames: desc.fieldNames,
-                fieldTypes: desc.fieldTypes,
-            });
-        }
-    }
-    /**
-     * Resolve a codec for the given CEL type string.
-     * Handles `list<T>` container types by composing element codecs.
-     * Unknown types fall back to z.unknown().
-     */
-    resolve(celType) {
-        // Handle list<T> container type
-        const listMatch = /^list<(.+)>$/.exec(celType);
-        if (listMatch) {
-            const elementCodec = this.resolve(listMatch[1]);
-            return z.array(elementCodec);
-        }
-        return this.codecs.get(celType) ?? z.unknown();
-    }
-    /**
-     * Encode a CEL value back to its raw form using the codec for the given type.
-     * For bidirectional codecs (SolidityAddress, SolidityInt) this calls .encode().
-     * For structs, it recursively encodes each field.
-     * For passthrough types (bool, string, int), returns the value as-is.
-     */
-    encode(celType, value) {
-        // Handle bytes — convert Uint8Array back to hex string for viem
-        if (celType === "bytes") {
-            if (value instanceof Uint8Array) {
-                return ("0x" +
-                    Array.from(value)
-                        .map((b) => b.toString(16).padStart(2, "0"))
-                        .join(""));
-            }
-            return value;
-        }
-        // Handle dyn — unwrap known wrapper types
-        if (celType === "dyn") {
-            if (value instanceof SolidityIntTypeWrapper) {
-                return value.value;
-            }
-            if (value instanceof SolidityAddressTypeWrapper) {
-                return value.value;
-            }
-            return value;
-        }
-        // Handle list<T>
-        const listMatch = /^list<(.+)>$/.exec(celType);
-        if (listMatch && Array.isArray(value)) {
-            const elementType = listMatch[1];
-            return value.map((item) => this.encode(elementType, item));
-        }
-        // Handle structs — recurse into fields
-        const structMeta = this.structMetas.get(celType);
-        if (structMeta) {
-            const raw = value;
-            const result = {};
-            for (const name of structMeta.fieldNames) {
-                result[name] = this.encode(structMeta.fieldTypes[name] ?? "dyn", raw[name]);
-            }
-            return result;
-        }
-        // For bidirectional codecs, use .encode(); for passthrough, return as-is
-        const codec = this.codecs.get(celType);
-        if (!codec) {
-            return value;
-        }
-        try {
-            return codec.encode(value);
-        }
-        catch {
-            return value;
-        }
-    }
-    buildStructCodec(desc) {
-        const { ctor, fieldNames, fieldTypes } = desc;
-        // Build a transform that accepts array (positional) or object input
-        return z.unknown().transform((input) => {
-            let data;
-            if (Array.isArray(input)) {
-                // Positional multi-return from viem
-                data = Object.fromEntries(fieldNames.map((name, i) => [
-                    name,
-                    this.decodeField(fieldTypes[name] ?? "dyn", input[i]),
-                ]));
-            }
-            else {
-                // Named-field object
-                const raw = input;
-                data = Object.fromEntries(fieldNames.map((name) => [
-                    name,
-                    this.decodeField(fieldTypes[name] ?? "dyn", raw[name]),
-                ]));
-            }
-            // eslint-disable-next-line new-cap
-            return Object.assign(new ctor(), data);
-        });
-    }
-    decodeField(celType, value) {
-        return this.resolve(celType).parse(value);
-    }
-}

package/dist/environment/hydrate.d.ts

@@ -1,48 +0,0 @@
-import { Environment } from "@marcbachmann/cel-js";
-import { CelCodecRegistry } from "./codec-registry.js";
-import type { SELSchema } from "@seljs/schema";
-/**
- * CEL environment limits configuration.
- */
-export interface CelLimits {
-    maxAstNodes?: number;
-    maxDepth?: number;
-    maxListElements?: number;
-    maxMapEntries?: number;
-    maxCallArguments?: number;
-}
-/**
- * Handler called when a contract method is invoked at runtime.
- */
-export type ContractCallHandler = (contractName: string, methodName: string, args: unknown[]) => unknown;
-/**
- * Create a base CEL environment with Solidity types registered.
- * No contracts, no variables — just the type system.
- *
- * Use this when you need to register contracts and variables yourself
- * (e.g., runtime evaluation with real async handlers).
- */
-export declare const createBaseEnvironment: (options?: {
-    limits?: CelLimits;
-}) => Environment;
-/**
- * Create a fully hydrated checker environment from a SELSchema.
- *
- * Registers Solidity primitive types, contract types with their methods
- * (using no-op handlers since the checker only needs type information),
- * schema variables, and built-in functions.
- */
-export declare const createCheckerEnvironment: (schema: SELSchema) => Environment;
-export interface RuntimeEnvironmentResult {
-    env: Environment;
-    contractBindings: Record<string, unknown>;
-    codecRegistry: CelCodecRegistry;
-}
-/**
- * Create a fully hydrated runtime environment from a SELSchema with a
- * real async handler for contract method calls.
- */
-export declare const createRuntimeEnvironment: (schema: SELSchema, handler: ContractCallHandler, options?: {
-    limits?: CelLimits;
-    unlistedVariablesAreDyn?: boolean;
-}) => RuntimeEnvironmentResult;

package/dist/environment/hydrate.js

@@ -1,198 +0,0 @@
-import { Environment } from "@marcbachmann/cel-js";
-import { contractTypeName } from "@seljs/common";
-import { createLogger } from "../debug.js";
-import { CelCodecRegistry } from "./codec-registry.js";
-import { registerSolidityTypes } from "./register-types.js";
-import { toCelLiteralType } from "./value-wrappers.js";
-const debug = createLogger("hydrate");
-const hydrateEnvironment = (env, schema, handler) => {
-    const contractBindings = {};
-    const structRegistry = new Map();
-    // Register struct types from schema (nested types appear before parents)
-    for (const type of schema.types) {
-        if (type.kind === "struct" && type.fields) {
-            const fields = {};
-            for (const field of type.fields) {
-                fields[field.name] = field.type;
-            }
-            try {
-                if (handler !== undefined) {
-                    // Runtime mode: register WITH ctor so structs can be instantiated
-                    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
-                    const StructCtor = class {
-                    };
-                    env.registerType(type.name, { ctor: StructCtor, fields });
-                    structRegistry.set(type.name, {
-                        ctor: StructCtor,
-                        fieldNames: Object.keys(fields),
-                        fieldTypes: fields,
-                    });
-                }
-                else {
-                    // Checker mode: no ctor needed
-                    env.registerType(type.name, { fields });
-                }
-            }
-            catch (err) {
-                debug("skipped type %s: %O", type.name, err);
-            }
-        }
-    }
-    const codecRegistry = handler !== undefined
-        ? new CelCodecRegistry({
-            structs: Array.from(structRegistry.entries()).map(([name, info]) => ({
-                name,
-                ...info,
-            })),
-        })
-        : undefined;
-    // Register contract types and methods
-    for (const contract of schema.contracts) {
-        const typeName = contractTypeName(contract.name);
-        class ContractType {
-            name;
-            constructor(name) {
-                this.name = name;
-            }
-        }
-        env
-            .registerType(typeName, { ctor: ContractType, fields: {} })
-            .registerVariable(contract.name, typeName);
-        contractBindings[contract.name] = new ContractType(contract.name);
-        /* eslint-disable @typescript-eslint/no-unsafe-argument */
-        for (const method of contract.methods) {
-            const returnType = method.returns || "dyn";
-            const methodHandler = handler !== undefined
-                ? async (...args) => {
-                    const raw = await handler(contract.name, method.name, args.slice(1));
-                    if (!codecRegistry) {
-                        throw new Error("codecRegistry is required when handler is provided");
-                    }
-                    return codecRegistry.resolve(returnType).parse(raw);
-                }
-                : () => undefined;
-            // Primary overload with schema param types
-            try {
-                env.registerFunction({
-                    name: method.name,
-                    receiverType: typeName,
-                    returnType,
-                    handler: methodHandler,
-                    params: method.params.map((param) => ({
-                        name: param.name,
-                        type: param.type,
-                    })),
-                }, undefined);
-            }
-            catch (err) {
-                debug("skipped method %s.%s: %O", contract.name, method.name, err);
-            }
-            // CEL literal type overloads for SolidityInt/SolidityAddress params
-            const hasCustomParams = method.params.some((p) => toCelLiteralType(p.type) !== null);
-            if (hasCustomParams) {
-                try {
-                    env.registerFunction({
-                        name: method.name,
-                        receiverType: typeName,
-                        returnType,
-                        handler: methodHandler,
-                        params: method.params.map((param) => ({
-                            name: param.name,
-                            type: toCelLiteralType(param.type) ?? param.type,
-                        })),
-                    }, undefined);
-                }
-                catch (err) {
-                    debug("skipped literal overload %s.%s: %O", contract.name, method.name, err);
-                }
-            }
-        }
-        /* eslint-enable @typescript-eslint/no-unsafe-argument */
-    }
-    // Register variables
-    for (const variable of schema.variables) {
-        try {
-            env.registerVariable(variable.name, variable.type);
-        }
-        catch (err) {
-            debug("variable %s: fallback to dyn: %O", variable.name, err);
-            env.registerVariable(variable.name, "dyn");
-        }
-    }
-    // Register schema functions with receiverType for type-checking
-    for (const fn of schema.functions) {
-        if (!fn.receiverType) {
-            continue;
-        }
-        try {
-            /* eslint-disable @typescript-eslint/no-unsafe-argument */
-            env.registerFunction({
-                name: fn.name,
-                receiverType: fn.receiverType,
-                returnType: fn.returns,
-                handler: () => undefined,
-                params: fn.params.map((param) => ({
-                    name: param.name,
-                    type: param.type,
-                })),
-            }, undefined);
-            /* eslint-enable @typescript-eslint/no-unsafe-argument */
-        }
-        catch (err) {
-            // Skip functions that are already registered as CEL builtins
-            if (!(err instanceof Error) ||
-                !err.message.includes("overlaps with existing overload")) {
-                throw err;
-            }
-            debug("skipped overlapping overload: %O", err);
-        }
-    }
-    return { contractBindings, codecRegistry };
-};
-/**
- * Create a base CEL environment with Solidity types registered.
- * No contracts, no variables — just the type system.
- *
- * Use this when you need to register contracts and variables yourself
- * (e.g., runtime evaluation with real async handlers).
- */
-export const createBaseEnvironment = (options) => {
-    const env = new Environment({
-        unlistedVariablesAreDyn: false,
-        ...(options?.limits ? { limits: options.limits } : {}),
-    });
-    registerSolidityTypes(env);
-    return env;
-};
-/**
- * Create a fully hydrated checker environment from a SELSchema.
- *
- * Registers Solidity primitive types, contract types with their methods
- * (using no-op handlers since the checker only needs type information),
- * schema variables, and built-in functions.
- */
-export const createCheckerEnvironment = (schema) => {
-    const env = createBaseEnvironment();
-    hydrateEnvironment(env, schema);
-    return env;
-};
-/**
- * Create a fully hydrated runtime environment from a SELSchema with a
- * real async handler for contract method calls.
- */
-export const createRuntimeEnvironment = (schema, handler, options) => {
-    const env = new Environment({
-        unlistedVariablesAreDyn: options?.unlistedVariablesAreDyn ?? false,
-        ...(options?.limits ? { limits: options.limits } : {}),
-    });
-    registerSolidityTypes(env);
-    const result = hydrateEnvironment(env, schema, handler);
-    if (!result.codecRegistry) {
-        throw new Error("codecRegistry is required when handler is provided");
-    }
-    return {
-        env,
-        contractBindings: result.contractBindings,
-        codecRegistry: result.codecRegistry,
-    };
-};

package/dist/environment/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./codec-registry.js";
-export * from "./hydrate.js";
-export * from "./register-types.js";
-export * from "./value-wrappers.js";

package/dist/environment/index.js

@@ -1,4 +0,0 @@
-export * from "./codec-registry.js";
-export * from "./hydrate.js";
-export * from "./register-types.js";
-export * from "./value-wrappers.js";

package/dist/environment/register-types.d.ts

@@ -1,14 +0,0 @@
-import type { Environment } from "@marcbachmann/cel-js";
-/**
- * Subset of the CEL Environment API needed for Solidity type registration.
- * Mirrors the parameter signatures from Environment but drops the return type
- * to void — registerSolidityTypes never chains the return value.
- */
-type SolidityTypeHost = {
-    [K in "registerType" | "registerOperator" | "registerFunction"]: (...args: Parameters<Environment[K]>) => void;
-};
-/**
- * Register all Solidity primitive types on a CEL Environment.
- */
-export declare const registerSolidityTypes: (env: SolidityTypeHost) => void;
-export {};