functionalscript 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -7,4 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 0.2.3
+
+- BitVec and documentation update [PR #322](https://github.com/functionalscript/functionalscript/pull/322).
+
 ## 0.1.608

package/com/cpp/module.f.mjs

@@ -1,4 +1,10 @@
 // @ts-self-types="./module.f.d.mts"
+
+/**
+ * This module generates C++ code blocks, including structs, interfaces, and method headers,
+ * based on a COM library of type definitions.
+ */
+
 import * as types from '../types/module.f.mjs'
 import * as text from '../../text/module.f.mjs'
 import * as O from '../../types/object/module.f.mjs'
@@ -51,7 +57,10 @@ const mapParamName = map(paramName)
 
 const joinComma = join(', ')
 
-/** @type {(name: string) => (lib: types.Library) => text.Block} */
+/**
+ * Generates the C++ code for a library.
+ * @type {(name: string) => (lib: types.Library) => text.Block}
+ */
 export const cpp = name => lib => {
 
     /** @type {(t: types.Type) => string|null} */

package/com/cs/module.f.mjs

@@ -1,4 +1,11 @@
 // @ts-self-types="./module.f.d.mts"
+
+/**
+ * This module generates C# code blocks for COM interop from a high-level type library definition.
+ *
+ * The module maps type definitions (e.g., structs, interfaces, and methods) into C# constructs
+ * with appropriate attributes for COM interop, such as `[StructLayout]`, `[Guid]`, and `[InterfaceType]`.
+ */
 import * as types from '../types/module.f.mjs'
 const { result, paramList } = types
 import * as text from '../../text/module.f.mjs'
@@ -118,7 +125,10 @@ const header = [
     ''
 ]
 
-/** @type {(name: string) => (library: types.Library) => text.Block} */
+/**
+ * Generates the C# code for a library.
+ * @type {(name: string) => (library: types.Library) => text.Block}
+ */
 export const cs = name => library => {
     const v = flatMapDef(entries(library))
     const ns = namespace(name)(v)

package/com/rust/module.f.mjs

@@ -1,4 +1,11 @@
 // @ts-self-types="./module.f.d.mts"
+
+/**
+ * This module generates Rust code for COM interop from a high-level type library definition.
+ *
+ * The module provides functions to define structs, traits, and implementations in Rust,
+ * specifically tailored for `nanocom` interoperation.
+ */
 import * as types from '../types/module.f.mjs'
 const { paramList } = types
 import * as Text from '../../text/module.f.mjs'
@@ -131,7 +138,12 @@ const traitImpl = t => {
 
 const where = ['Self: nanocom::Class<Interface = Interface>', 'nanocom::CObject<Self>: Ex']
 
-/** @type {(library: types.Library) => Text.Block} */
+/**
+ * Generates Rust code for the given type library.
+ *
+ * @param {types.Library} library - The library of type definitions to generate Rust code for.
+ * @returns {Text.Block} - A block of Rust code representing the library.
+ */
 export const rust = library => {
 
     /** @type {(p: string) => (o: (_: string) => string) => (t: types.Type) => string} */

package/issues/lang/3370-type-inference.md

@@ -0,0 +1,69 @@
+# Type Inference
+
+We need type inference to prove that specific values have specific types. Type annotations can help, but we can't trust them.
+
+## Level 1
+
+```rust
+enum Type {
+    Unknown,
+    Null,
+    Undefined,
+    Bool,
+    Number,
+    String,
+    BigInt,
+    Object,
+    Array,
+    Function,
+    // ...
+}
+```
+
+## Level 2
+
+It is a set. For example,
+
+```rust
+Set<Type>
+```
+
+On this level, we can extend our `Type` definition with some known finite values:
+
+```rs
+enum Type {
+    Unknown,
+    Null,
+    Undefined,
+    False,
+    True,
+    Number,
+    String,
+    BigInt,
+    Object,
+    Array,
+    Function,
+    // ...
+    // ...
+    EmptyString,
+    NumberZero,
+    NumberNaN,
+    NumberPositive,
+    NumberNegative,
+    NumberPInf,
+    NumberNInf,
+    BigIntZero,
+    BigIntPositive,
+    BigIntNegative,
+    EmptyObject,
+    EmptyArray,
+    FunctionId,
+    // ...
+}
+```
+
+The set is finite and can be implemented using a bit-set.
+
+### Level 3
+
+Compared to level 2, this level contains dynamic information about subsets of the type.

package/issues/lang/3380-promise.md

@@ -0,0 +1,22 @@
+# Promise
+
+It could be blocked until we solve the ownership problem.
+
+Promise is the main object. `async` and `await` are syntax sugars. If we can safely work with promises, we can transform a FunctionalScript program with `async` functions into a normal function with Promises.
+
+## `.then()`
+
+```ts
+a.then(f)
+```
+
+```ts
+const g0 = async(a) => f(await a)
+// g0 = a => a.then(f)
+
+const g1 = async(a) => f(await a)
+
+const a = io.wrtieFile('a', 'x')
+const p0 = g0(a)
+const p1 = g1(a)
+```

package/issues/lang/3390-class.md

@@ -0,0 +1,3 @@
+# Classes
+
+Classes are [nominal types](https://en.wikipedia.org/wiki/Nominal_type_system). In other words, their definitions are location-based, not content-based. This can cause many problems, such as duplicate incompatible class definitions during serialization and code importing. So, the best way to use classes would be to use CA VM.

package/issues/lang/README.md

@@ -1,7 +1,8 @@
 # FunctionalScript Language
 
-Two main FunctionsScript princples:
-1. if FS code pass validation/compilation, then it doesn't have side-effects,
+Two main FunctionsScript principles:
+
+1. if FS code passes validation/compilation, then it doesn't have side-effects,
 2. the code that passed validation/compilation should behave on FunctionalScript VM the same way as on any other modern JavaScript engine.
 
 When we implement features of FunctionalScript, the first priority is a simplification of the VM.
@@ -22,7 +23,7 @@ File Types:
 
 **VM**:
 
-We are introducing new commands in the order that every new command depends only on previous commands.
+We are introducing new commands in such a way that every new command depends only on previous commands.
 
 |format|any           |Tag|          |
 |------|--------------|---|----------|
@@ -98,18 +99,27 @@ File extensions: `.f.js` and `.f.mjs`.
 2. [ ] [parameters](./3120-parameters.md)
 3. [ ] [body-const](./3130-body-const.md)
 
-### 3.2. Priority 1
+### 3.2. Priority 2
 
 1. [ ] `if`. See https://developer.mozilla.org/en-US/docs/Glossary/Falsy
 2. [ ] [let](./3220-let.md)
 3. [ ] `while`
 4. [ ] [export](./3240-export.md)
+5. [ ] Ownership of Mutable Objects (Singletons)
+
+### 3.3. Priority 3
 
-### 3.3. Syntactic Sugar
+1. [ ] Regular Expressions
+2. [ ] [type inference](./3370-type-inference.md)
+3. [ ] [promise](./3380-promise.md)
+4. [ ] [class](./3390-class.md)
 
-1. [ ] [expression](./3210-expression.md)
-2. [ ] [one-parameter](./3220-one-parameter.md)
-3. [ ] [assignments](./3330-assignments.md)
+### 3.4. Syntactic Sugar
+
+1. [ ] [expression](./3410-expression.md)
+2. [ ] [one-parameter](./3420-one-parameter.md)
+3. [ ] [assignments](./3430-assignments.md)
+4. [ ] `async`/`await`. Depends on the implementation of promises.
 
 ## 4. ECMAScript Proposals
 
@@ -120,3 +130,64 @@ File extensions: `.f.js` and `.f.mjs`.
    - most browsers don't support the feature.
 2. [ ] [Pipe Operator `|>`](https://github.com/tc39/proposal-pipeline-operator), Stage 2.
 3. [ ] [Records and Tuples](https://github.com/tc39/proposal-record-tuple), Stage 2.
+
+## 5. I/O
+
+### 5.1. Isolated I/O
+
+Using dependency injection.
+
+This implementation of VM requires external function implementation.
+
+### 5.2 Isolated Asynchronous I/O
+
+It requires a promise implementation.
+
+### 5.3. State Machine with Asynchronous Requests
+
+VM doesn't need to implement external functions or promises.
+
+```ts
+type RequestType = ...;
+type Request = readonly[Input, Continuation];
+type Continuation = (_: Output) => Request;
+type Main = Request
+```
+
+## 6. Content-Addressable VM
+
+See also [Unison](https://www.unison-lang.org/).
+
+The main target is run-time performance.
+
+Hash function: most likely SHA256 because there is a lot of hardware support from modern processors.
+
+Hash structure: we will use several initial hashes for a compress function.
+
+We may use CDT for huge arrays, objects, strings, and BigInts.
+
+The first bit of a hash is reserved for a tag. If the tag is `0`, we have raw data with `1` at the end. A hash with all zeroes is used for `undefined`. If the first bit is `0`, then the value is a hash. So, we have only 255 bits for a hash.
+
+Because we use tagged hash, we can keep small values in a `nanenum`. So it may reuse a lot from non-content addressable VM and ref-values can keep a hash value inside.
+
+Instead of an address, we can use a prefix, hash. 48 bits should be enough for most cases. However, we also need a mechanism to resolve collisions (even if they are rare). For example, our value can be an enum like this
+
+```rust
+enum Value {
+   Data(...),
+   Hash(u48),
+   Ref(u48),
+}
+```
+
+However, while the `===` operation can be faster, `Value::Hash` is slower when we need to access the object's internals because it requires two dereference operations. So, we may come back to using only references.
+
+```rust
+enum Value {
+   Data(...)
+   Ref(u48)
+}
+```
+
+Collision probability for 48 bits is 50% for `16777216 = 2^24` hashes (birthday attack). 
+    

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@functionalscript/functionalscript",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "exports": {
     "./com/cpp": "./out/com/cpp/module.f.mjs",
     "./com/cs": "./out/com/cs/module.f.mjs",
@@ -38,6 +38,7 @@
     "./types/array": "./out/types/array/module.f.mjs",
     "./types/bigfloat": "./out/types/bigfloat/module.f.mjs",
     "./types/bigint": "./out/types/bigint/module.f.mjs",
+    "./types/bit_vec": "./out/types/bit_vec/module.f.mjs",
     "./types/btree/find": "./out/types/btree/find/module.f.mjs",
     "./types/btree": "./out/types/btree/module.f.mjs",
     "./types/btree/remove": "./out/types/btree/remove/module.f.mjs",

package/out/com/cpp/module.f.d.mts

@@ -1,4 +1,7 @@
-/** @type {(name: string) => (lib: types.Library) => text.Block} */
+/**
+ * Generates the C++ code for a library.
+ * @type {(name: string) => (lib: types.Library) => text.Block}
+ */
 export const cpp: (name: string) => (lib: types.Library) => text.Block;
 import * as types from '../types/module.f.mjs';
 import * as text from '../../text/module.f.mjs';

package/out/com/cpp/module.f.mjs

@@ -1,4 +1,8 @@
 // @ts-self-types="./module.f.d.mts"
+/**
+ * This module generates C++ code blocks, including structs, interfaces, and method headers,
+ * based on a COM library of type definitions.
+ */
 import * as types from '../types/module.f.mjs';
 import * as text from '../../text/module.f.mjs';
 import * as O from '../../types/object/module.f.mjs';
@@ -39,7 +43,10 @@ const ref = id => `${id} const&`;
 const paramName = ([name]) => name;
 const mapParamName = map(paramName);
 const joinComma = join(', ');
-/** @type {(name: string) => (lib: types.Library) => text.Block} */
+/**
+ * Generates the C++ code for a library.
+ * @type {(name: string) => (lib: types.Library) => text.Block}
+ */
 export const cpp = name => lib => {
     /** @type {(t: types.Type) => string|null} */
     const interface_ = t => {

package/out/com/cs/module.f.d.mts

@@ -1,4 +1,7 @@
-/** @type {(name: string) => (library: types.Library) => text.Block} */
+/**
+ * Generates the C# code for a library.
+ * @type {(name: string) => (library: types.Library) => text.Block}
+ */
 export const cs: (name: string) => (library: types.Library) => text.Block;
 import * as types from '../types/module.f.mjs';
 import * as text from '../../text/module.f.mjs';

package/out/com/cs/module.f.mjs

@@ -1,4 +1,10 @@
 // @ts-self-types="./module.f.d.mts"
+/**
+ * This module generates C# code blocks for COM interop from a high-level type library definition.
+ *
+ * The module maps type definitions (e.g., structs, interfaces, and methods) into C# constructs
+ * with appropriate attributes for COM interop, such as `[StructLayout]`, `[Guid]`, and `[InterfaceType]`.
+ */
 import * as types from '../types/module.f.mjs';
 const { result, paramList } = types;
 import * as text from '../../text/module.f.mjs';
@@ -87,7 +93,10 @@ const header = [
     using('System.Runtime.InteropServices'),
     ''
 ];
-/** @type {(name: string) => (library: types.Library) => text.Block} */
+/**
+ * Generates the C# code for a library.
+ * @type {(name: string) => (library: types.Library) => text.Block}
+ */
 export const cs = name => library => {
     const v = flatMapDef(entries(library));
     const ns = namespace(name)(v);

package/out/com/rust/module.f.d.mts

@@ -1,5 +1,4 @@
-/** @type {(library: types.Library) => Text.Block} */
-export const rust: (library: types.Library) => Text.Block;
+export function rust(library: types.Library): Text.Block;
 export type OptionalProperty<T> = T | {};
 export type Where = {
     readonly where: readonly string[];

package/out/com/rust/module.f.mjs

@@ -1,4 +1,10 @@
 // @ts-self-types="./module.f.d.mts"
+/**
+ * This module generates Rust code for COM interop from a high-level type library definition.
+ *
+ * The module provides functions to define structs, traits, and implementations in Rust,
+ * specifically tailored for `nanocom` interoperation.
+ */
 import * as types from '../types/module.f.mjs';
 const { paramList } = types;
 import * as Text from '../../text/module.f.mjs';
@@ -102,7 +108,12 @@ const traitImpl = t => {
     return flat([trait({ ...t, where }), i]);
 };
 const where = ['Self: nanocom::Class<Interface = Interface>', 'nanocom::CObject<Self>: Ex'];
-/** @type {(library: types.Library) => Text.Block} */
+/**
+ * Generates Rust code for the given type library.
+ *
+ * @param {types.Library} library - The library of type definitions to generate Rust code for.
+ * @returns {Text.Block} - A block of Rust code representing the library.
+ */
 export const rust = library => {
     /** @type {(p: string) => (o: (_: string) => string) => (t: types.Type) => string} */
     const type = p => {

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

@@ -1,6 +1,8 @@
 /** @typedef {Operator.Reduce<bigint>} Reduce */
 /** @typedef {Operator.Unary<bigint, bigint>} Unary*/
 /**
+ * A type representing a prime field and its associated operations.
+ *
  * @typedef {{
  *  readonly p: bigint
  *  readonly middle: bigint
@@ -17,12 +19,36 @@
  *  readonly pow3: Unary
  * }} 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: bigint) => PrimeField;
-/** @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: (f: PrimeField) => (a: bigint) => bigint | null;
 export type Reduce = Operator.Reduce<bigint>;
 export type Unary = Operator.Unary<bigint, bigint>;
+/**
+ * A type representing a prime field and its associated operations.
+ */
 export type PrimeField = {
     readonly p: bigint;
     readonly middle: bigint;

package/out/prime_field/module.f.mjs

@@ -5,6 +5,8 @@ const { scalar_mul } = bi;
 /** @typedef {Operator.Reduce<bigint>} Reduce */
 /** @typedef {Operator.Unary<bigint, bigint>} Unary*/
 /**
+ * A type representing a prime field and its associated operations.
+ *
  * @typedef {{
  *  readonly p: bigint
  *  readonly middle: bigint
@@ -21,7 +23,14 @@ const { scalar_mul } = bi;
  *  readonly pow3: Unary
  * }} 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 => {
@@ -74,7 +83,21 @@ export const prime_field = p => {
         pow3: a => mul(a)(pow2(a))
     };
 };
-/** @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';

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

@@ -6,6 +6,7 @@ declare namespace _default {
         mul: () => void;
         reciprocal: () => void;
         pow: () => void;
+        sqrtExample: () => void;
         sqrt: () => void;
     };
 }

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;