@harmoniclabs/pebble 0.1.0-dev0

package/dist/utils/ToJson.js

@@ -0,0 +1,5 @@
+import { stringify } from "./stringify.js";
+export function logJson(jsonLike, indent = 4) {
+    const obj = typeof jsonLike !== "undefined" && typeof jsonLike.toJson === "function" ? jsonLike.toJson() : jsonLike;
+    console.log(stringify(obj, undefined, indent), Error().stack?.split("\n")[2]);
+}

package/dist/utils/UPLCFlatUtils/index.d.ts

@@ -0,0 +1,46 @@
+import { BitStream } from "@harmoniclabs/bitstream";
+export type InByteOffset = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export declare function isInByteOffset(offset: InByteOffset): boolean;
+export interface BitStreamPadToByteOptions {
+    onByteAllignedAddNewByte: boolean;
+    withOneAsEndPadding: boolean;
+}
+/**
+ * @static
+ */
+export default class UPLCFlatUtils {
+    /**
+     * @deprecated this is a @static class, it is not supposed to have instances
+     */
+    private constructor();
+    static zigzagBigint(bigint: bigint): bigint;
+    static unzigzagBigint(bigint: bigint): bigint;
+    /**
+     * source: https://hydra.iohk.io/build/5988492/download/1/plutus-core-specification.pdf#Variable%20length%20data
+     *
+     * Non-empty lists are encoded by prefixing the element stored with ‘0’ if this is the last element
+     * or ‘1’ if there is more data following.
+     *
+     * We encode Integers as a non-empty list of chunks, 7 bits each, with the least significant chunk
+     * first and the most significant bit first in the chunk.
+     */
+    static encodeBigIntAsVariableLengthBitStream(integer: Readonly<bigint>): BitStream;
+    static getPadBitStream(n: InByteOffset): BitStream;
+    /**
+     * **_SIDE EFFECT_**: modifies the ```toPad``` ```BitStream``` passed as first argument
+     *
+     * @param toPad
+     * @param n
+     * @returns
+     */
+    static addPadTo(toPad: BitStream, n: InByteOffset): void;
+    static get padToByteDefaultOptions(): Readonly<BitStreamPadToByteOptions>;
+    /**
+     * **_SIDE EFFECT_**: modifies the ```toPad``` ```BitStream``` passed as first argument
+     *
+     * @param toPad
+     * @param options
+     * @returns
+     */
+    static padToByte(toPad: BitStream, options?: Partial<BitStreamPadToByteOptions>): void;
+}

package/dist/utils/UPLCFlatUtils/index.js

@@ -0,0 +1,124 @@
+import { BitStream } from "@harmoniclabs/bitstream";
+import BitUtils from "../BitUtils/index.js";
+import { assert } from "../assert.js";
+export function isInByteOffset(offset) {
+    return (offset === 0 ||
+        offset === 1 ||
+        offset === 2 ||
+        offset === 3 ||
+        offset === 4 ||
+        offset === 5 ||
+        offset === 6 ||
+        offset === 7);
+}
+/**
+ * @static
+ */
+export default class UPLCFlatUtils {
+    /**
+     * @deprecated this is a @static class, it is not supposed to have instances
+     */
+    constructor() { }
+    ;
+    static zigzagBigint(bigint) {
+        return (bigint >>
+            (BigInt(BitUtils.getNOfUsedBits(bigint)))) ^ // XOR
+            (bigint << BigInt(1));
+    }
+    static unzigzagBigint(bigint) {
+        return (((bigint >> BigInt(1))) ^ // XOR
+            -(bigint & BigInt(1)));
+    }
+    /**
+     * source: https://hydra.iohk.io/build/5988492/download/1/plutus-core-specification.pdf#Variable%20length%20data
+     *
+     * Non-empty lists are encoded by prefixing the element stored with ‘0’ if this is the last element
+     * or ‘1’ if there is more data following.
+     *
+     * We encode Integers as a non-empty list of chunks, 7 bits each, with the least significant chunk
+     * first and the most significant bit first in the chunk.
+     */
+    static encodeBigIntAsVariableLengthBitStream(integer) {
+        assert(typeof integer === "bigint", "expected a bigint as input; got instance of type: " + typeof integer);
+        if (integer === BigInt(0))
+            return BitStream.fromBinStr("00000000");
+        assert(integer > BigInt(0), "'UPLCFlatUtils.encodeBigIntAsVariableLengthBitStream' can only encode non-negative integers; the given input was: " + integer.toString());
+        // store binary string for easy BitStream creation
+        const chunks = [];
+        let mask = BigInt(127);
+        // 1. Converting to binary
+        const nBits = BitUtils.getNOfUsedBits(integer);
+        for (let nAddedBits = 0; nAddedBits < nBits; nAddedBits += 7) {
+            // 3. Reorder chunks (least significant chunk first)
+            // 
+            // push at the end because the mask starts from the last signigficat chunk first
+            // so chunk[1] is the second least significant and so on
+            chunks.push(
+            // 2. Split into 7 bit chunks
+            // take 7 bits
+            ((integer & mask)
+                // allign to the start 
+                >> BigInt(nAddedBits))
+                // translate to biinary
+                .toString(2)
+                // make sure the bits are 7 in total
+                .padStart(7, '0'));
+            mask = mask << BigInt(7);
+        }
+        // 4. Add list constructor tags
+        for (let i = 0; i < chunks.length; i++) {
+            chunks[i] = (i === chunks.length - 1 ? '0' : '1') + chunks[i];
+        }
+        return BitStream.fromBinStr(chunks.join(''));
+    }
+    static getPadBitStream(n) {
+        assert(isInByteOffset(n), "addPadTo only works for pads from 0 inclusive to 7 inclusive");
+        if (n === 0) {
+            return BitStream.fromBinStr("1".padStart(8, '0'));
+        }
+        return BitStream.fromBinStr("1".padStart(n, '0'));
+    }
+    /**
+     * **_SIDE EFFECT_**: modifies the ```toPad``` ```BitStream``` passed as first argument
+     *
+     * @param toPad
+     * @param n
+     * @returns
+     */
+    static addPadTo(toPad, n) {
+        assert(BitStream.isStrictInstance(toPad), "BitStream strict instance expected as first argument in 'UPLCFlatUtils.addPadTo'");
+        toPad.append(UPLCFlatUtils.getPadBitStream(n));
+        return;
+    }
+    static get padToByteDefaultOptions() {
+        return Object.freeze({
+            onByteAllignedAddNewByte: true,
+            withOneAsEndPadding: true
+        });
+    }
+    /**
+     * **_SIDE EFFECT_**: modifies the ```toPad``` ```BitStream``` passed as first argument
+     *
+     * @param toPad
+     * @param options
+     * @returns
+     */
+    static padToByte(toPad, options) {
+        const opts = {
+            ...UPLCFlatUtils.padToByteDefaultOptions,
+            ...(options === undefined ? {} : options)
+        };
+        const nBitsMissingToByte = toPad.getNBitsMissingToByte();
+        if (nBitsMissingToByte === 0) {
+            if (opts.onByteAllignedAddNewByte) {
+                toPad.append(BitStream.fromBinStr((opts.withOneAsEndPadding ? "1" : "0").padStart(8, '0')));
+            }
+            else {
+                // do nothing, already alligned
+            }
+            return;
+        }
+        toPad.append(BitStream.fromBinStr((opts.withOneAsEndPadding ? "1" : "0").padStart(nBitsMissingToByte, '0')));
+        return;
+    }
+}

package/dist/utils/array/filterSortedStrArrInplace.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Removes elements from target that exist in source array.
+ * Assumes BOTH arrays are sorted in ascending order.
+ *
+ * @returns {string[]} reference to the **same** target array.
+ */
+export declare function filterSortedStrArrInplace(target: string[], source: string[]): string[];

package/dist/utils/array/filterSortedStrArrInplace.js

@@ -0,0 +1,46 @@
+/**
+ * Removes elements from target that exist in source array.
+ * Assumes BOTH arrays are sorted in ascending order.
+ *
+ * @returns {string[]} reference to the **same** target array.
+ */
+export function filterSortedStrArrInplace(target, source) {
+    if (source.length === 0 || target.length === 0)
+        return target;
+    source = source.slice(); // copy to avoid modifying the original array
+    let elem;
+    let start = 0;
+    while (elem = source.shift()) {
+        // Early return if element is greater than last element in target
+        if (elem > target[target.length - 1])
+            return target;
+        const index = findElementIndex(target, elem, start);
+        if (index !== -1) {
+            target.splice(index, 1);
+            if (target.length === 0
+                || index >= target.length)
+                return target; // if target is empty, no need to continue
+            start = index; // reset start to the found index
+        }
+    }
+    return target;
+}
+/**
+ * Binary search to find the exact index of an element
+ * @returns the index of the element if found, -1 otherwise
+ */
+function findElementIndex(target, elem, start = 0, end = target.length) {
+    if (start >= end)
+        return -1;
+    let mid;
+    while (start < end) {
+        mid = (start + end) >> 1;
+        if (target[mid] === elem)
+            return mid; // found exact match
+        if (target[mid] < elem)
+            start = mid + 1;
+        else
+            end = mid;
+    }
+    return -1; // not found
+}

package/dist/utils/array/keepSortedArrInplace.d.ts

@@ -0,0 +1,7 @@
+/**
+ * only keeps elements from target that exist in source array.
+ * Assumes BOTH arrays are sorted in ascending order.
+ *
+ * @returns {string[]} reference to the **same** target array.
+ */
+export declare function keepSortedStrArrInplace(target: string[], source: string[]): string[];

package/dist/utils/array/keepSortedArrInplace.js

@@ -0,0 +1,49 @@
+/**
+ * only keeps elements from target that exist in source array.
+ * Assumes BOTH arrays are sorted in ascending order.
+ *
+ * @returns {string[]} reference to the **same** target array.
+ */
+export function keepSortedStrArrInplace(target, source) {
+    if (source.length === 0) {
+        target.length = 0; // clear target if source is empty
+        return target;
+    }
+    if (target.length === 0)
+        return target; // nothing to keep if target is empty
+    source = source.slice(); // copy to avoid modifying the original array
+    let fstSrc = source.shift(); // get first element from source
+    for (let i = 0; i < target.length; i++) {
+        const elem = target[i];
+        if (elem === fstSrc) {
+            fstSrc = source.shift(); // get next element from source
+            if (!fstSrc) {
+                target.length = i + 1; // truncate target to current index
+                return target; // no more elements to keep
+            }
+        }
+        // not equal, remove the element
+        target.splice(i, 1);
+        i--; // adjust index since we removed an element
+    }
+    return target; // return the modified target array
+}
+/**
+ * Binary search to find the exact index of an element
+ * @returns the index of the element if found, -1 otherwise
+ */
+function findElementIndex(target, elem, start = 0, end = target.length) {
+    if (start >= end)
+        return -1;
+    let mid;
+    while (start < end) {
+        mid = (start + end) >> 1;
+        if (target[mid] === elem)
+            return mid; // found exact match
+        if (target[mid] < elem)
+            start = mid + 1;
+        else
+            end = mid;
+    }
+    return -1; // not found
+}

package/dist/utils/array/mergeSortedStrArrInplace.d.ts

@@ -0,0 +1,6 @@
+/**
+ * assumes BOTH arrays are sorted in ascending order
+ *
+ * @returns {string[]} reference to the **same** target array.
+ */
+export declare function mergeSortedStrArrInplace(target: string[], source: string[]): string[];

package/dist/utils/array/mergeSortedStrArrInplace.js

@@ -0,0 +1,52 @@
+/**
+ * assumes BOTH arrays are sorted in ascending order
+ *
+ * @returns {string[]} reference to the **same** target array.
+ */
+export function mergeSortedStrArrInplace(target, source) {
+    if (source.length === 0)
+        return target;
+    if (target.length === 0) {
+        target.push(...source);
+        return target;
+    }
+    source = source.slice(); // copy to avoid modifying the original array
+    let start = 0;
+    let elem;
+    while (elem = source.shift())
+        start = insertUniqueSortedInpalce(target, elem, start) + 1;
+    return target;
+}
+/**
+ *
+ * @returns the position where the element was inserted (or where it was already present)
+ */
+function insertUniqueSortedInpalce(target, elem, start = 0, end = target.length) {
+    if (start >= end) {
+        target.splice(end, 0, elem);
+        return end;
+    }
+    let mid;
+    while (start < end) {
+        mid = (start + end) >> 1;
+        if (target[mid] === elem)
+            return mid; // already exists, do nothing
+        if (target[mid] < elem) {
+            start = mid + 1;
+            if (target[start] > elem) {
+                target.splice(start, 0, elem);
+                return start;
+            }
+        }
+        else if (target[mid] > elem)
+            end = mid;
+    }
+    if (start === target.length) {
+        target.push(elem);
+        return start;
+    }
+    else {
+        target.unshift(elem);
+        return 0;
+    }
+}

package/dist/utils/assert.d.ts

@@ -0,0 +1 @@
+export declare function assert<T>(thing: T, message?: string): NonNullable<T>;

package/dist/utils/assert.js

@@ -0,0 +1,5 @@
+export function assert(thing, message = "TypeAssertion failed") {
+    if (!thing)
+        throw new Error(message);
+    return thing;
+}

package/dist/utils/capitalize.d.ts

@@ -0,0 +1 @@
+export declare function capitalize<str extends string>(s: str): Capitalize<str>;

package/dist/utils/capitalize.js

@@ -0,0 +1,5 @@
+export function capitalize(s) {
+    if (s.length === 0)
+        return s;
+    return (s[0].toUpperCase() + s.slice(1));
+}

package/dist/utils/combinators.d.ts

@@ -0,0 +1,37 @@
+import { Head, Tail } from "./types.js";
+export type CurriedFn<Args extends any[], Output> = Args extends [] ? () => Output : Args extends [infer Arg] ? (arg: Arg) => Output : Args extends [infer Arg1, infer Arg2, ...infer RestArgs] ? (arg: Arg1) => CurriedFn<[Arg2, ...RestArgs], Output> : Args extends [...infer Tys] ? (...args: Tys) => Output : never;
+/**
+ * parametrized functions will have TypeParameters automatically substituted with ```any```
+ *
+ * > example:
+ * > ```ts
+ * > function ifThenElse<T>( cond: boolean, a: T, b: T ): T
+ * > {
+ * >      return cond ? a : b;
+ * > }
+ * >
+ * > const cuffiedIf = curry( ifThenElse );
+ * > // type:
+ * > // ( arg: boolean ) => ( arg: any ) => ( arg: any ) => any
+ * > ```
+ *
+ * a workaround is to define a wrapper function ( ofthe translating to identity at runtime )
+ * with the fixed types:
+ * > ```ts
+ * > const ifNum = ( cond: boolean, a: number, b: number ) => ifThenElse( cond, a, b );
+ * >
+ * > const cuffiedIfNum = curry( ifNum );
+ * > // type:
+ * > // ( arg: boolean ) => ( arg: number ) => ( arg: number ) => number
+ * > ```
+ *
+ * but at this point it would be probably faster and easier to directly vrite the curried version:
+ * > ```ts
+ * > const curriedIfNumFaster = ( cond: boolean ) => ( a: number ) => ( b: number ) => ifThenElse( cond, a, b );
+ * > // type:
+ * > // ( arg: boolean ) => ( arg: number ) => ( arg: number ) => number
+ * > ```
+ *
+*/
+export declare function curry<Args extends any[], Output>(fn: (...args: Args) => Output): CurriedFn<Args, Output>;
+export declare function curryFirst<Args extends [any, ...any[]], Output>(fn: (arg1: Head<Args>, ...args: Tail<Args>) => Output): (arg1: Head<Args>) => (...args: Tail<Args>) => Output;

package/dist/utils/combinators.js

@@ -0,0 +1,76 @@
+/**
+ * parametrized functions will have TypeParameters automatically substituted with ```any```
+ *
+ * > example:
+ * > ```ts
+ * > function ifThenElse<T>( cond: boolean, a: T, b: T ): T
+ * > {
+ * >      return cond ? a : b;
+ * > }
+ * >
+ * > const cuffiedIf = curry( ifThenElse );
+ * > // type:
+ * > // ( arg: boolean ) => ( arg: any ) => ( arg: any ) => any
+ * > ```
+ *
+ * a workaround is to define a wrapper function ( ofthe translating to identity at runtime )
+ * with the fixed types:
+ * > ```ts
+ * > const ifNum = ( cond: boolean, a: number, b: number ) => ifThenElse( cond, a, b );
+ * >
+ * > const cuffiedIfNum = curry( ifNum );
+ * > // type:
+ * > // ( arg: boolean ) => ( arg: number ) => ( arg: number ) => number
+ * > ```
+ *
+ * but at this point it would be probably faster and easier to directly vrite the curried version:
+ * > ```ts
+ * > const curriedIfNumFaster = ( cond: boolean ) => ( a: number ) => ( b: number ) => ifThenElse( cond, a, b );
+ * > // type:
+ * > // ( arg: boolean ) => ( arg: number ) => ( arg: number ) => number
+ * > ```
+ *
+*/
+export function curry(fn) {
+    if (fn.length === 0)
+        return ((...restArgs) => fn(...restArgs));
+    function curryMem(uncurried, argsMem, lastCallRest) {
+        if (argsMem.length === uncurried.length) {
+            return uncurried(...argsMem, ...lastCallRest);
+        }
+        return (arg, ...rest) => curryMem(uncurried, [...argsMem, arg], rest);
+    }
+    return curryMem(fn, [], []);
+}
+export function curryFirst(fn) {
+    if (fn.length === 0)
+        return (() => fn());
+    if (fn.length === 1)
+        return ((arg) => fn(arg));
+    /*
+    !!!  IMPORTANT !!!
+
+    return ( arg: Head<Args> ) => ( ...args: Tail<Args> ) => fn( arg, ...args )
+    
+    doesn't work because  ```( ...args: Tail<Args> ) => ...``` has ```length``` of  ```0```
+    */
+    if (fn.length === 2)
+        return (arg) => ((args_0) => fn(arg, ...[args_0]));
+    if (fn.length === 3)
+        return (arg) => ((args_0, args_1) => fn(arg, ...[args_0, args_1]));
+    if (fn.length === 4)
+        return (arg) => ((args_0, args_1, args_2) => fn(arg, ...[args_0, args_1, args_2]));
+    if (fn.length === 5)
+        return (arg) => ((args_0, args_1, args_2, args_3) => fn(arg, ...[args_0, args_1, args_2, args_3]));
+    if (fn.length === 6)
+        return (arg) => ((args_0, args_1, args_2, args_3, args_4) => fn(arg, ...[args_0, args_1, args_2, args_3, args_4]));
+    if (fn.length === 7)
+        return (arg) => ((args_0, args_1, args_2, args_3, args_4, args_5) => fn(arg, ...[args_0, args_1, args_2, args_3, args_4, args_5]));
+    if (fn.length === 8)
+        return (arg) => ((args_0, args_1, args_2, args_3, args_4, args_5, args_6) => fn(arg, ...[args_0, args_1, args_2, args_3, args_4, args_5, args_6]));
+    if (fn.length === 9)
+        return (arg) => ((args_0, args_1, args_2, args_3, args_4, args_5, args_6, args_7) => fn(arg, ...[args_0, args_1, args_2, args_3, args_4, args_5, args_6, args_7]));
+    if (fn.length === 10)
+        return (arg) => ((args_0, args_1, args_2, args_3, args_4, args_5, args_6, args_7, args_8) => fn(arg, ...[args_0, args_1, args_2, args_3, args_4, args_5, args_6, args_7, args_8]));
+    throw new Error("functions with more thatn 10 parameters not supported for conversion; try gruping paramters in structured types");
+}

package/dist/utils/getCallStackAt/index.d.ts

@@ -0,0 +1,43 @@
+export type CallStackSiteInfos = {
+    /** raw call stack line as it is reported in `new Error().stack */
+    __line__: string;
+    inferredName?: string | undefined;
+    path: string;
+    line: number | undefined;
+    column: number | undefined;
+    once: (evt: "inferredName", listener: (inferredName: string) => any) => void;
+    dispatchEvent: (evt: "inferredName", inferredName: string) => void;
+};
+export interface GetCallStackAtOptions {
+    /**
+     * if `inferredName` was not already present in the stack trace
+     * tries to parse the file (using `fetch`) indicated by the stack trace
+     *
+     * **if found**, `inferredName` will be modified i the reference present in the object returned
+     *
+     * @default false
+    **/
+    tryGetNameAsync?: boolean;
+    /**
+     * automatically add callback once the name is inferred
+    **/
+    onNameInferred?: (inferredName: string) => void;
+}
+export declare const defaultGetCallStackAtOptions: GetCallStackAtOptions;
+/**
+ *
+ * @param n index of an array tha looks like this
+ * ```ts
+ *          [
+ *              "Error: ",
+ *              "    at getCallStackAt path/to/this/file.ts 10:17",
+ *              "    at someCallerFunction path/to/caller/file.ts line:column",
+ *              "    at callerCallerFunction path/to/callerCaller/file.ts line:column",
+ *              "    at just/some/path/to/some/caller.ts line:column",
+ *              "    at someOtherFunction path/to/something.ts line:column",
+ *              ...rest_of_call_stack
+ *          ]
+ * ```
+ * @returns
+ */
+export declare function getCallStackAt(n?: number, opts?: GetCallStackAtOptions): CallStackSiteInfos | undefined;