functionalscript 0.2.1 → 0.2.3

package/out/prime_field/test.f.mjs

@@ -123,6 +123,13 @@ export default {
                 test(f.max - 1n);
                 test(f.max);
             },
+            sqrtExample: () => {
+                const field = prime_field(7n);
+                const root = sqrt(field)(4n);
+                if (root !== 2n) {
+                    throw root;
+                }
+            },
             sqrt: () => {
                 /** @type {(a: bigint) => void} */
                 const test = a => {

package/out/secp/module.f.d.mts

@@ -1,6 +1,17 @@
-/** @typedef {readonly[bigint, bigint]} Point2D */
-/** @typedef {Point2D|null} Point */
 /**
+ * A 2D point represented as a pair of `bigint` values `[x, y]`.
+ *
+ * @typedef {readonly[bigint, bigint]} Point2D
+ */
+/**
+ * A 2D point on an elliptic curve, represented as a pair of `bigint` values.
+ * `null` represents the point at infinity (`O`).
+ *
+ * @typedef {Point2D|null} Point
+ */
+/**
+ * Initialization parameters for an elliptic curve.
+ *
  * @typedef {{
  *  readonly p: bigint
  *  readonly a: readonly[bigint, bigint]
@@ -9,6 +20,8 @@
  * }} Init
  */
 /**
+ * Represents an elliptic curve and its associated operations.
+ *
  * @typedef {{
  *  readonly pf: pf.PrimeField
  *  readonly nf: pf.PrimeField
@@ -19,22 +32,71 @@
  *  readonly mul: (a: Point) => (n: bigint) => Point
  * }} Curve
  */
-/** @type {(i: Init) => Curve} */
+/**
+ * Constructs an elliptic curve with the given initialization parameters.
+ *
+ * @example
+ *
+ * ```js
+ * const curveParams = {
+ *     p: 23n,
+ *     a: [0n, 1n],
+ *     g: [1n, 1n],
+ *     n: 19n
+ * };
+ * const curveInstance = curve(curveParams);
+ *
+ * // Access curve operations
+ * const point = curveInstance.add([1n, 1n])([2n, 5n]); // Add two points
+ * const negPoint = curveInstance.neg([1n, 1n]); // Negate a point
+ * const mulPoint = curveInstance.mul([1n, 1n])(3n); // Multiply a point by 3
+ * ```
+ *
+ * @type {(i: Init) => Curve}
+ */
 export const curve: (i: Init) => Curve;
 /** @type {(a: Point) => (b: Point) => boolean} */
 export const eq: (a: Point) => (b: Point) => boolean;
-/** @type {Init} */
-export const secp256k1: Init;
-/** @type {Init} */
+/**
+ * https://neuromancer.sk/std/secg/secp192r1
+ *
+ * @type {Init}
+ */
 export const secp192r1: Init;
+/**
+ * https://en.bitcoin.it/wiki/Secp256k1
+ * https://neuromancer.sk/std/secg/secp256k1
+ *
+ * @type {Init}
+ */
+export const secp256k1: Init;
+/**
+ * https://neuromancer.sk/std/secg/secp256r1
+ *
+ * @type { Init }
+ */
+export const secp256r1: Init;
+/**
+ * A 2D point represented as a pair of `bigint` values `[x, y]`.
+ */
 export type Point2D = readonly [bigint, bigint];
+/**
+ * A 2D point on an elliptic curve, represented as a pair of `bigint` values.
+ * `null` represents the point at infinity (`O`).
+ */
 export type Point = Point2D | null;
+/**
+ * Initialization parameters for an elliptic curve.
+ */
 export type Init = {
     readonly p: bigint;
     readonly a: readonly [bigint, bigint];
     readonly g: readonly [bigint, bigint];
     readonly n: bigint;
 };
+/**
+ * Represents an elliptic curve and its associated operations.
+ */
 export type Curve = {
     readonly pf: pf.PrimeField;
     readonly nf: pf.PrimeField;

package/out/secp/module.f.mjs

@@ -4,9 +4,20 @@ import * as pf from '../prime_field/module.f.mjs';
 import * as bi from '../types/bigint/module.f.mjs';
 const { scalar_mul } = bi;
 const { prime_field, sqrt } = pf;
-/** @typedef {readonly[bigint, bigint]} Point2D */
-/** @typedef {Point2D|null} Point */
 /**
+ * A 2D point represented as a pair of `bigint` values `[x, y]`.
+ *
+ * @typedef {readonly[bigint, bigint]} Point2D
+ */
+/**
+ * A 2D point on an elliptic curve, represented as a pair of `bigint` values.
+ * `null` represents the point at infinity (`O`).
+ *
+ * @typedef {Point2D|null} Point
+ */
+/**
+ * Initialization parameters for an elliptic curve.
+ *
  * @typedef {{
  *  readonly p: bigint
  *  readonly a: readonly[bigint, bigint]
@@ -15,6 +26,8 @@ const { prime_field, sqrt } = pf;
  * }} Init
  */
 /**
+ * Represents an elliptic curve and its associated operations.
+ *
  * @typedef {{
  *  readonly pf: pf.PrimeField
  *  readonly nf: pf.PrimeField
@@ -25,7 +38,28 @@ const { prime_field, sqrt } = pf;
  *  readonly mul: (a: Point) => (n: bigint) => Point
  * }} Curve
  */
-/** @type {(i: Init) => Curve} */
+/**
+ * Constructs an elliptic curve with the given initialization parameters.
+ *
+ * @example
+ *
+ * ```js
+ * const curveParams = {
+ *     p: 23n,
+ *     a: [0n, 1n],
+ *     g: [1n, 1n],
+ *     n: 19n
+ * };
+ * const curveInstance = curve(curveParams);
+ *
+ * // Access curve operations
+ * const point = curveInstance.add([1n, 1n])([2n, 5n]); // Add two points
+ * const negPoint = curveInstance.neg([1n, 1n]); // Negate a point
+ * const mulPoint = curveInstance.mul([1n, 1n])(3n); // Multiply a point by 3
+ * ```
+ *
+ * @type {(i: Init) => Curve}
+ */
 export const curve = ({ p, a: [a0, a1], n }) => {
     const pf = prime_field(p);
     const { pow2, pow3, sub, add, mul, neg, div } = pf;
@@ -88,7 +122,29 @@ export const eq = a => b => {
     const [bx, by] = b;
     return ax === bx && ay === by;
 };
-/** @type {Init} */
+/**
+ * https://neuromancer.sk/std/secg/secp192r1
+ *
+ * @type {Init}
+ */
+export const secp192r1 = {
+    p: 0xfffffffffffffffffffffffffffffffeffffffffffffffffn,
+    a: [
+        0x64210519e59c80e70fa7e9ab72243049feb8deecc146b9b1n,
+        0xfffffffffffffffffffffffffffffffefffffffffffffffcn
+    ],
+    g: [
+        0x188da80eb03090f67cbf20eb43a18800f4ff0afd82ff1012n,
+        0x07192b95ffc8da78631011ed6b24cdd573f977a11e794811n
+    ],
+    n: 0xffffffffffffffffffffffff99def836146bc9b1b4d22831n,
+};
+/**
+ * https://en.bitcoin.it/wiki/Secp256k1
+ * https://neuromancer.sk/std/secg/secp256k1
+ *
+ * @type {Init}
+ */
 export const secp256k1 = {
     p: 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn,
     a: [7n, 0n],
@@ -98,16 +154,20 @@ export const secp256k1 = {
     ],
     n: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n,
 };
-/** @type {Init} */
-export const secp192r1 = {
-    p: 0xfffffffffffffffffffffffffffffffeffffffffffffffffn,
+/**
+ * https://neuromancer.sk/std/secg/secp256r1
+ *
+ * @type { Init }
+ */
+export const secp256r1 = {
+    p: 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn,
     a: [
-        0x64210519e59c80e70fa7e9ab72243049feb8deecc146b9b1n,
-        0xfffffffffffffffffffffffffffffffefffffffffffffffcn
+        0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn, //< b
+        0xffffffff00000001000000000000000000000000fffffffffffffffffffffffcn, //< a
     ],
     g: [
-        0x188da80eb03090f67cbf20eb43a18800f4ff0afd82ff1012n,
-        0x07192b95ffc8da78631011ed6b24cdd573f977a11e794811n
+        0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296n, //< x
+        0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5n, //< y
     ],
-    n: 0xffffffffffffffffffffffff99def836146bc9b1b4d22831n,
+    n: 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n,
 };

package/out/secp/test.f.d.mts

@@ -1,4 +1,5 @@
 declare namespace _default {
+    function example(): void;
     function test(): void;
 }
 export default _default;

package/out/secp/test.f.mjs

@@ -1,6 +1,20 @@
 import * as _ from './module.f.mjs';
-const { curve, secp256k1, secp192r1, eq } = _;
+const { curve, secp256k1, secp192r1, secp256r1, eq } = _;
 export default {
+    example: () => {
+        /** @type {_.Init} */
+        const curveParams = {
+            p: 23n,
+            a: [0n, 1n],
+            g: [1n, 1n],
+            n: 19n
+        };
+        const c = curve(curveParams);
+        // Access curve operations
+        const point = c.add([1n, 1n])([2n, 5n]); // Add two points
+        const negPoint = c.neg([1n, 1n]); // Negate a point
+        const mulPoint = c.mul([1n, 1n])(3n); // Multiply a point by 3
+    },
     test: () => {
         /** @type {(c: _.Init) => void} */
         const test_curve = c => {
@@ -9,12 +23,12 @@ export default {
             /** @type {(p: _.Point) => void} */
             const point_check = p => {
                 if (p === null) {
-                    throw 'null';
+                    throw 'p === null';
                 }
                 const [x, y] = p;
                 const ye = yf(x);
                 if (ye === null) {
-                    throw 'null';
+                    throw 'ye === null';
                 }
                 if (abs(ye) !== abs(y)) {
                     throw 'ye';
@@ -59,5 +73,6 @@ export default {
         };
         test_curve(secp256k1);
         test_curve(secp192r1);
+        test_curve(secp256r1);
     }
 };

package/out/types/bigint/test.f.mjs

@@ -110,6 +110,13 @@ export default {
                 throw result;
             }
         },
+        () => {
+            const v = 0x18945n;
+            const result = log2(v);
+            if (result !== 16n) {
+                throw result;
+            }
+        }
     ],
     toString2: () => {
         // max for Bun (131_072 Bytes)

package/out/types/bit_vec/module.f.d.mts

@@ -0,0 +1,72 @@
+/**
+ * A vector of bits represented as a `bigint`.
+ *
+ * @typedef {bigint} Vec
+ */
+/**
+ * An empty vector of bits.
+ */
+export const empty: 1n;
+/**
+ * Calculates the length of the given vector of bits.
+ */
+export const len: (v: bigint) => bigint;
+/**
+ * Extract an unsigned integer of the given `uintLen` from the given vector.
+ *
+ * @type {(uintLen: bigint) => (v: Vec) => bigint}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = 0b110101n;
+ * const extract3Bits = uint(3n);
+ * const result = extract3Bits(vector); // result is 0b101n (5n)
+ * ```
+ */
+export const uint: (uintLen: bigint) => (v: Vec) => bigint;
+/**
+ * Creates a vector of bits of the given `vecLen` from the given unsigned integer.
+ *
+ * @type {(vecLen: bigint) => (ui: bigint) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const createVector = vec(4n);
+ * const vector = createVector(5n); // vector is 0b10101n
+ * ```
+ */
+export const vec: (vecLen: bigint) => (ui: bigint) => Vec;
+/**
+ * Appends the vector `b` to the back of the vector `a`.
+ *
+ * @type {(a: Vec) => (b: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const vec8 = vec(8n)
+ * const a = vec8(0x345n)
+ * const b = vec8(0x789n)
+ * const ab = appendBack(a)(b) // 0x18945n
+ * ```
+ */
+export const appendBack: (a: Vec) => (b: Vec) => Vec;
+/**
+ * Removes the first `len` bits from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const v = vec(17n)(0x12345n) // v = 0x32345n
+ * const r = removeFront(9n)(v) // r = 0x191n
+ * ```
+ */
+export const removeFront: (len: bigint) => (v: Vec) => Vec;
+/**
+ * A vector of bits represented as a `bigint`.
+ */
+export type Vec = bigint;

package/out/types/bit_vec/module.f.mjs

@@ -0,0 +1,83 @@
+// @ts-self-types="./module.f.d.mts"
+import { log2 } from '../bigint/module.f.mjs';
+/**
+ * A vector of bits represented as a `bigint`.
+ *
+ * @typedef {bigint} Vec
+ */
+/**
+ * An empty vector of bits.
+ */
+export const empty = 1n;
+/**
+ * Calculates the length of the given vector of bits.
+ */
+export const len = log2;
+/**
+ * Extract an unsigned integer of the given `uintLen` from the given vector.
+ *
+ * @type {(uintLen: bigint) => (v: Vec) => bigint}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = 0b110101n;
+ * const extract3Bits = uint(3n);
+ * const result = extract3Bits(vector); // result is 0b101n (5n)
+ * ```
+ */
+export const uint = uintLen => {
+    const mask = (1n << uintLen) - 1n;
+    return data => data & mask;
+};
+/**
+ * Creates a vector of bits of the given `vecLen` from the given unsigned integer.
+ *
+ * @type {(vecLen: bigint) => (ui: bigint) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const createVector = vec(4n);
+ * const vector = createVector(5n); // vector is 0b10101n
+ * ```
+ */
+export const vec = vecLen => {
+    const stop = 1n << vecLen;
+    const mask = stop - 1n;
+    return data => (data & mask) | stop;
+};
+/**
+ * Appends the vector `b` to the back of the vector `a`.
+ *
+ * @type {(a: Vec) => (b: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const vec8 = vec(8n)
+ * const a = vec8(0x345n)
+ * const b = vec8(0x789n)
+ * const ab = appendBack(a)(b) // 0x18945n
+ * ```
+ */
+export const appendBack = a => {
+    const aLen = len(a);
+    return b => a | (b << aLen);
+};
+/**
+ * Removes the first `len` bits from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const v = vec(17n)(0x12345n) // v = 0x32345n
+ * const r = removeFront(9n)(v) // r = 0x191n
+ * ```
+ */
+export const removeFront = len => v => {
+    const r = v >> len;
+    return r === 0n ? empty : r;
+};

package/out/types/bit_vec/test.f.d.mts

@@ -0,0 +1,9 @@
+declare namespace _default {
+    function uintExample(): void;
+    function vecExample(): void;
+    function length(): void;
+    function bitset(): void;
+    function appendBack(): void;
+    function removeBack(): void;
+}
+export default _default;

package/out/types/bit_vec/test.f.mjs

@@ -0,0 +1,60 @@
+import { empty, len, appendBack, vec, uint, removeFront } from './module.f.mjs';
+export default {
+    uintExample: () => {
+        const vector = 53n;
+        const extract3Bits = uint(3n);
+        const result = extract3Bits(vector); // result is 0b101n (5n)
+        if (result !== 5n) {
+            throw result;
+        }
+    },
+    vecExample: () => {
+        const createVector = vec(4n);
+        const vector = createVector(5n); // vector is 0b10101n
+        if (vector !== 21n) {
+            throw vector;
+        }
+    },
+    length: () => {
+        const i = len(empty);
+        if (i !== 0n) {
+            throw i;
+        }
+    },
+    bitset: () => {
+        const v = vec(8n)(0x5fen);
+        if (v !== 0x1fen) {
+            throw v;
+        }
+        if (len(v) !== 8n) {
+            throw 'len';
+        }
+        const u = uint(8n)(v);
+        if (u !== 0xfen) {
+            throw v;
+        }
+    },
+    appendBack: () => {
+        const vec8 = vec(8n);
+        const a = vec8(0x345n);
+        const b = vec8(0x789n);
+        const ab = appendBack(a)(b);
+        if (ab !== 0x18945n) {
+            throw ab;
+        }
+        const s = len(ab);
+        if (s !== 16n) {
+            throw `appendBack: ${s}`;
+        }
+    },
+    removeBack: () => {
+        const v = vec(17n)(0x12345n);
+        if (v !== 0x32345n) {
+            throw v.toString(16);
+        }
+        const r = removeFront(9n)(v);
+        if (r !== 0x191n) {
+            throw r.toString(16);
+        }
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "FunctionalScript is a functional subset of JavaScript",
   "scripts": {

package/prime_field/module.f.mjs

@@ -8,6 +8,8 @@ const { scalar_mul } = bi
 /** @typedef {Operator.Unary<bigint, bigint>} Unary*/
 
 /**
+ * A type representing a prime field and its associated operations.
+ *
  * @typedef {{
  *  readonly p: bigint
  *  readonly middle: bigint
@@ -25,7 +27,14 @@ const { scalar_mul } = bi
  * }} PrimeField
  */
 
-/** @type {(p: bigint) => PrimeField} */
+/**
+ * Creates a prime field with the specified prime modulus and associated operations.
+ *
+ * @param p - A prime number to define the field.
+ * @returns The prime field object.
+ *
+ * @type {(p: bigint) => PrimeField}
+ */
 export const prime_field = p => {
     /** @type {Reduce} */
     const sub = a => b => {
@@ -77,7 +86,21 @@ export const prime_field = p => {
     }
 }
 
-/** @type {(f: PrimeField) => (a: bigint) => bigint|null} */
+/**
+ * Computes the square root of a number in a prime field.
+ *
+ * @throws If the prime modulus `p` does not satisfy `p % 4 == 3`.
+ *
+ * @example
+ *
+ * ```js
+ * const field = prime_field(7n);
+ * const root = sqrt(field)(4n);
+ * if (root !== 2n) { throw root }
+ * ```
+ *
+ * @type {(f: PrimeField) => (a: bigint) => bigint|null}
+ */
 export const sqrt = ({p, mul, pow }) => {
     if ((p & 3n) !== 3n) { throw 'sqrt' }
     const sqrt_k = (p + 1n) >> 2n

package/prime_field/test.f.mjs

@@ -68,6 +68,11 @@ export default {
                 test(f.max - 1n)
                 test(f.max)
             },
+            sqrtExample: () => {
+                const field = prime_field(7n);
+                const root = sqrt(field)(4n);
+                if (root !== 2n) { throw root }
+            },
             sqrt: () => {
                 /** @type {(a: bigint) => void} */
                 const test = a => {