affinirum 1.4.2 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +226 -154
- package/dst/Affinirum.js +24 -15
- package/dst/Atom.d.ts +3 -1
- package/dst/Constant.js +1 -1
- package/dst/Functions.js +7 -4
- package/dst/Keywords.js +4 -4
- package/dst/ParserState.d.ts +2 -1
- package/dst/ParserState.js +43 -82
- package/dst/Type.d.ts +11 -7
- package/dst/Type.js +113 -38
- package/dst/Value.d.ts +1 -0
- package/dst/Value.js +19 -1
- package/dst/atom/ArrayAtom.d.ts +7 -3
- package/dst/atom/ArrayAtom.js +53 -8
- package/dst/atom/FunctionAtom.d.ts +4 -1
- package/dst/atom/FunctionAtom.js +65 -15
- package/dst/atom/ObjectAtom.d.ts +7 -5
- package/dst/atom/ObjectAtom.js +35 -13
- package/dst/atom/PrimitiveAtom.d.ts +3 -1
- package/dst/atom/PrimitiveAtom.js +10 -1
- package/dst/cjs/Affinirum.js +24 -15
- package/dst/cjs/Constant.js +1 -1
- package/dst/cjs/Functions.js +6 -3
- package/dst/cjs/Keywords.js +4 -4
- package/dst/cjs/ParserState.js +42 -81
- package/dst/cjs/Type.js +113 -38
- package/dst/cjs/Value.js +21 -0
- package/dst/cjs/atom/ArrayAtom.js +53 -8
- package/dst/cjs/atom/FunctionAtom.js +65 -15
- package/dst/cjs/atom/ObjectAtom.js +35 -13
- package/dst/cjs/atom/PrimitiveAtom.js +10 -1
- package/dst/cjs/native/Aggregable.js +3 -2
- package/dst/cjs/native/Array.js +10 -8
- package/dst/cjs/native/Boolean.js +8 -5
- package/dst/cjs/native/Buffer.js +32 -3
- package/dst/cjs/native/Enumerable.js +7 -4
- package/dst/cjs/native/Float.js +26 -13
- package/dst/cjs/native/Integer.js +64 -28
- package/dst/cjs/native/Iterable.js +8 -5
- package/dst/cjs/native/Number.js +62 -33
- package/dst/cjs/native/Object.js +2 -1
- package/dst/cjs/native/String.js +71 -24
- package/dst/cjs/native/Timestamp.js +76 -18
- package/dst/cjs/native/Unknown.js +1 -1
- package/dst/cjs/native/notation/AN.js +152 -11
- package/dst/cjs/native/notation/IP.js +4 -3
- package/dst/cjs/native/notation/JSON.js +1 -1
- package/dst/cjs/node/ArrayNode.js +6 -6
- package/dst/cjs/node/BlockNode.js +5 -4
- package/dst/cjs/node/CallNode.js +28 -22
- package/dst/cjs/node/CastNode.js +42 -0
- package/dst/cjs/node/ObjectNode.js +2 -4
- package/dst/cjs/node/SwitchNode.js +10 -10
- package/dst/cjs/node/VariableNode.js +3 -1
- package/dst/native/Aggregable.js +3 -2
- package/dst/native/Array.js +10 -8
- package/dst/native/Boolean.d.ts +1 -0
- package/dst/native/Boolean.js +7 -4
- package/dst/native/Buffer.d.ts +2 -0
- package/dst/native/Buffer.js +29 -2
- package/dst/native/Enumerable.js +7 -4
- package/dst/native/Float.d.ts +2 -0
- package/dst/native/Float.js +25 -12
- package/dst/native/Integer.d.ts +5 -1
- package/dst/native/Integer.js +61 -27
- package/dst/native/Iterable.js +8 -5
- package/dst/native/Number.d.ts +4 -3
- package/dst/native/Number.js +57 -32
- package/dst/native/Object.js +2 -1
- package/dst/native/String.d.ts +2 -7
- package/dst/native/String.js +68 -16
- package/dst/native/Timestamp.d.ts +4 -2
- package/dst/native/Timestamp.js +73 -17
- package/dst/native/Unknown.js +1 -1
- package/dst/native/notation/AN.d.ts +1 -0
- package/dst/native/notation/AN.js +152 -12
- package/dst/native/notation/IP.js +4 -3
- package/dst/native/notation/JSON.js +1 -1
- package/dst/node/ArrayNode.d.ts +1 -1
- package/dst/node/ArrayNode.js +6 -6
- package/dst/node/BlockNode.js +5 -4
- package/dst/node/CallNode.js +28 -22
- package/dst/node/CastNode.d.ts +15 -0
- package/dst/node/CastNode.js +38 -0
- package/dst/node/ObjectNode.d.ts +1 -1
- package/dst/node/ObjectNode.js +2 -4
- package/dst/node/SwitchNode.js +10 -10
- package/dst/node/VariableNode.js +3 -1
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
# Affinirum
|
|
2
|
-
A fast, embeddable scripting language powered by a lightweight recursive descent parser,
|
|
3
|
-
designed to evaluate complex algorithmic logic with precision and flexibility.
|
|
4
|
-
Ideal for embedding in host applications, it offers clear syntax,
|
|
5
|
-
and
|
|
6
|
-
|
|
2
|
+
A fast, embeddable scripting language powered by a lightweight recursive descent parser,
|
|
3
|
+
designed to evaluate complex algorithmic logic with precision and flexibility.
|
|
4
|
+
Ideal for embedding in host applications, it offers clear syntax, type inference, permissive type checking,
|
|
5
|
+
and support for host-provided values and functions—enabling rapid prototyping and advanced rule evaluation
|
|
6
|
+
in applications that control which capabilities are exposed to scripts.
|
|
7
7
|
|
|
8
8
|
Supports algebraic and boolean expressions, variables, conditionals, loops, and a rich standard library for working with numbers, buffers, strings, arrays, and objects.
|
|
9
9
|
|
|
10
|
-
Runs in
|
|
10
|
+
Runs in browsers and Node.js.
|
|
11
11
|
|
|
12
|
-
Target: ES2022 [browser+
|
|
12
|
+
Target: ES2022 [browser+Node.js][ESM+CJS].
|
|
13
13
|
|
|
14
14
|
## Features
|
|
15
15
|
|
|
16
16
|
- Efficient execution: Parse once, execute many times with different variable values.
|
|
17
17
|
- Variable support: Input and statement-scoped variables.
|
|
18
|
-
- Function support: Variadic and first-
|
|
18
|
+
- Function support: Variadic and first-class functions for expressive scripting.
|
|
19
19
|
- Optimized evaluation: Constant expression folding with type checks.
|
|
20
20
|
- Comprehensive set of operators: Boolean, arithmetic, buffer, string, comparison, and indexing support.
|
|
21
21
|
- Built-in functions: Rich set of mathematical and composition utilities.
|
|
@@ -23,7 +23,7 @@ Target: ES2022 [browser+NodeJS][ESM+CJS].
|
|
|
23
23
|
## Specifications
|
|
24
24
|
|
|
25
25
|
A script may contain multiple expressions separated by semicolons, as well as blocks of statements.
|
|
26
|
-
The value of a block is defined by the value of its last expression.
|
|
26
|
+
The value of a block is defined by the value of its last expression. An empty block has type **void** and evaluates to JavaScript `undefined`.
|
|
27
27
|
- Scientific notation is supported for floating point numbers, like *0.1281e+2*.
|
|
28
28
|
- ISO Timestamps prefixed with **@**, like *@2025-05-11T19:09:21.320Z*.
|
|
29
29
|
- Hexadecimal buffer values are enclosed in backticks (**\`**), like *\`10ab0901\`*.
|
|
@@ -39,24 +39,24 @@ It is defined by comma-separated values enclosed in brackets (**[]**),
|
|
|
39
39
|
Array elements can be accessed using the access operator (**.**),
|
|
40
40
|
or using brackets with a zero-based numeric index, like *theArray.23*, *theArray[0]*, *theArray[10]*, *theArray[indexVar]*.
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
An easy way to check whether an array contains an index is to use the presence operator (**?**), like *theArray?50*.
|
|
43
43
|
|
|
44
44
|
### Objects
|
|
45
|
-
Object is a container of named values of any type.
|
|
46
|
-
It is defined by comma-separated key-value
|
|
47
|
-
like *["key1":100, "key2":"abc"]*, *["a":0,"b":"str"
|
|
45
|
+
Object is a container of named values of any type.
|
|
46
|
+
It is defined by comma-separated key-value pairs enclosed in brackets (**[]**), where each key is separated from its value by a colon (**:**),
|
|
47
|
+
like *["key1":100, "key2":"abc"]*, *["a":0, "b":"str", "c":valueVar]*.
|
|
48
48
|
<br>An empty object is represented as **[\:]**.
|
|
49
49
|
|
|
50
50
|
Object properties can be accessed using the access operator (**.**) with a string literal, token,
|
|
51
51
|
or with brackets containing a string key,
|
|
52
52
|
like *theObject."key"*, *theObject.key*, or *theObject["key"]*.
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
An easy way to check whether an object contains a key is to use the presence operator (**?**), like *theObject?myKey*.
|
|
55
55
|
|
|
56
|
-
### Functions
|
|
57
|
-
A function is a callable code unit that produces a value.
|
|
58
|
-
The
|
|
59
|
-
|
|
56
|
+
### Functions
|
|
57
|
+
A function is a callable code unit that produces a value.
|
|
58
|
+
The standard library provides built-in functions. Host functions can be supplied as typed input variables,
|
|
59
|
+
and subroutines can be defined in Affinirum code.
|
|
60
60
|
|
|
61
61
|
### Variables
|
|
62
62
|
Valid variable and function names must start with a letter, number sign (**\#**), dollar sign (**\$**), or underscore (**\_**)
|
|
@@ -65,22 +65,63 @@ Valid variable and function names must start with a letter, number sign (**\#**)
|
|
|
65
65
|
|
|
66
66
|
Whitespace characters are ignored.
|
|
67
67
|
|
|
68
|
-
### Types
|
|
69
|
-
- **void** for value **null**
|
|
70
|
-
- **boolean** for values **true** and **false**
|
|
71
|
-
- **timestamp** for date-time values
|
|
72
|
-
- **float** for 64-bit floating point values in binary64, IEEE 754 binary floating-point format
|
|
73
|
-
- **integer** for 64-bit integer values
|
|
68
|
+
### Types
|
|
69
|
+
- **void** for the absence of a value; the **null** literal and injected JavaScript `null` or `undefined` values have this type, and a **void** result is returned as JavaScript `undefined`
|
|
70
|
+
- **boolean** (alias **bool**) for values **true** and **false**
|
|
71
|
+
- **timestamp** (alias **time**) for date-time values backed by JavaScript `Date` objects
|
|
72
|
+
- **float** (alias **f64**) for 64-bit floating point values in binary64, IEEE 754 binary floating-point format
|
|
73
|
+
- **integer** (alias **i64**) for signed 64-bit integer values; arithmetic overflow wraps to the signed 64-bit range
|
|
74
74
|
- **buffer** for ordered sequences of bytes
|
|
75
75
|
- **string** for ordered sequences of characters, text strings
|
|
76
|
-
- **array** for ordered sequences of values
|
|
77
|
-
- **object** for collections of named values
|
|
78
|
-
- **function** for built-in, injected or script-defined subroutines
|
|
79
|
-
-
|
|
76
|
+
- **array** for ordered sequences of values
|
|
77
|
+
- **object** for collections of named values
|
|
78
|
+
- **function** for built-in, injected or script-defined subroutines
|
|
79
|
+
- **[type]** for a homogeneous array whose items have the specified type, such as **[string]**
|
|
80
|
+
- **[type1, type2, ...]** for a tuple whose items have the corresponding types
|
|
81
|
+
- **??** for unknown or variant type
|
|
80
82
|
- Type grouping: **(...)**
|
|
81
83
|
- Type union: **|**
|
|
82
84
|
- Type optionality modifier: **?**
|
|
83
85
|
|
|
86
|
+
Canonical type names and their aliases are reserved and cannot be used as variable or function names.
|
|
87
|
+
|
|
88
|
+
### Type-checking policy
|
|
89
|
+
Affinirum uses intentionally permissive type checking. Type information helps reject clearly incompatible expressions,
|
|
90
|
+
select function overloads, and report useful compilation errors; it is not intended to enforce strict static
|
|
91
|
+
substitutability or prove that every accepted expression is safe for every possible runtime value.
|
|
92
|
+
|
|
93
|
+
- **??** is the unknown or variant type and is compatible with every type. It includes **void**, so a **??**
|
|
94
|
+
function parameter may receive **null**, `undefined`, or be omitted.
|
|
95
|
+
- An optional type such as **integer?** is the union **void | integer**. Optional parameters may receive **null**, `undefined`,
|
|
96
|
+
or be omitted.
|
|
97
|
+
- A call with known argument types must match one complete function overload. Parameter matches from separate overloads
|
|
98
|
+
are not combined to accept a call.
|
|
99
|
+
- Object types are open structural constraints: required properties and their values are checked, while additional
|
|
100
|
+
properties are allowed.
|
|
101
|
+
- Tuple types are prefix constraints: the declared item types are checked in order, optional trailing items may be
|
|
102
|
+
omitted, and additional items are allowed.
|
|
103
|
+
- Function compatibility is deliberately flexible. The accepted argument-count ranges only need to overlap;
|
|
104
|
+
one function's complete arity range does not need to contain the other's.
|
|
105
|
+
- A callback may declare fewer parameters than the caller provides. Additional arguments are ignored at runtime,
|
|
106
|
+
following JavaScript function-call behavior.
|
|
107
|
+
- Function parameter types are checked contravariantly where both signatures declare a parameter, while **??**
|
|
108
|
+
remains compatible with any parameter type. Return types are checked covariantly.
|
|
109
|
+
- Fixed and variadic signatures are not interchangeable. Variadic arguments use a distinct packed-array calling
|
|
110
|
+
convention and are only compatible with corresponding variadic signatures.
|
|
111
|
+
|
|
112
|
+
For example, a callback declared as `~(value: float):boolean` is compatible with an expected callback type such as
|
|
113
|
+
`~(value: ??, index: integer?, values: array?):boolean`: the arities overlap, **??** accepts the concrete value type,
|
|
114
|
+
and the callback may ignore the additional arguments. This behavior is intentional. Affinirum does not enforce strict
|
|
115
|
+
function subtyping.
|
|
116
|
+
|
|
117
|
+
### Type casting
|
|
118
|
+
A postfix type cast declares the expected type of an expression using **::type**,
|
|
119
|
+
like `value::object` or `JSON.Parse(json)::object.property`.
|
|
120
|
+
|
|
121
|
+
A cast does not convert the value. The source and target types must be compatible at compile time,
|
|
122
|
+
and the evaluated value must satisfy the target type at runtime. An incompatible cast raises an error.
|
|
123
|
+
Casts can be followed by property access, index access, function calls, or another cast.
|
|
124
|
+
|
|
84
125
|
### Definitions
|
|
85
126
|
- Unit grouping: **{...}**
|
|
86
127
|
- Unit separator: **;**
|
|
@@ -88,11 +129,11 @@ Whitespace characters are ignored.
|
|
|
88
129
|
- Value separator: **,**
|
|
89
130
|
- Array element at numeric index, or object property by string key: **[]**
|
|
90
131
|
- Object property by string key or method function call: **.**
|
|
91
|
-
- Array
|
|
92
|
-
- Object definition: **[
|
|
132
|
+
- Array definition: **[item1, ...]**
|
|
133
|
+
- Object definition: **[property1-key: property1-value, ...]**
|
|
93
134
|
- Subroutine definition: **~(argument1-name: argument1-type, ...):return-type {...}**
|
|
94
|
-
- Conditional switch definition, returns first or second value if prefix is true or false: **if condition {value1} else {value2}**,
|
|
95
|
-
and if **else** clause is
|
|
135
|
+
- Conditional switch definition, returns first or second value if prefix is true or false: **if condition {value1} else {value2}**,
|
|
136
|
+
and if the **else** clause is omitted, the second value is **void**
|
|
96
137
|
- Loop definition, iteratively evaluates suffix while prefix is true, returns last evaluated value: **while condition {...}**
|
|
97
138
|
- Stop iteration: **stop**
|
|
98
139
|
- Proceed to next iteration: **next**
|
|
@@ -109,38 +150,39 @@ Whitespace characters are ignored.
|
|
|
109
150
|
- Less than or equals to: **<=**
|
|
110
151
|
- Equals to: **==**
|
|
111
152
|
- Not equals to: **!=**
|
|
112
|
-
-
|
|
113
|
-
- Arithmetic addition, or buffer, string, and array concatination: **+**
|
|
153
|
+
- Arithmetic addition, or buffer, string, and array concatenation: **+**
|
|
114
154
|
- Arithmetic subtraction or negation: **-**
|
|
115
155
|
- Arithmetic multiplication: **\***
|
|
116
156
|
- Arithmetic division: **/**
|
|
117
157
|
- Arithmetic remainder: **%**
|
|
118
158
|
- Exponentiation operator: **^**
|
|
119
159
|
- Property access operator: **.**
|
|
120
|
-
- Property
|
|
160
|
+
- Property existence operator: **?**
|
|
161
|
+
- Null coalescence operator: **?:**
|
|
162
|
+
- Type cast operator: **::**
|
|
121
163
|
- Assignment: **=**
|
|
122
164
|
- Boolean disjunction (Logical OR) assignment: **|=**
|
|
123
165
|
- Boolean conjunction (Logical AND) assignment: **&=**
|
|
124
166
|
- Arithmetic addition assignment: **+=**
|
|
125
167
|
- Arithmetic subtraction assignment: **-=**
|
|
126
|
-
- Arithmetic multiplication assignment:
|
|
168
|
+
- Arithmetic multiplication assignment: **\*=**
|
|
127
169
|
- Arithmetic division assignment: **/=**
|
|
128
170
|
- Arithmetic remainder assignment: **%=**
|
|
129
171
|
|
|
130
172
|
### Native Global Functions
|
|
131
173
|
|
|
132
|
-
Native conversions use the following
|
|
133
|
-
|
|
134
|
-
- `Format` returns an empty string for
|
|
135
|
-
- `Encode` returns a zero-length buffer for
|
|
136
|
-
- `Decode` and `Parse` return **
|
|
137
|
-
|
|
138
|
-
Empty strings and zero-length buffers remain ordinary values; they are not serialized
|
|
139
|
-
Invalid non-
|
|
140
|
-
|
|
141
|
-
#### Boolean
|
|
142
|
-
- **Boolean.Or(values: ...(boolean |
|
|
143
|
-
- **Boolean.And(values: ...(boolean |
|
|
174
|
+
Native conversions use the following **void** handling:
|
|
175
|
+
|
|
176
|
+
- `Format` returns an empty string for **void**.
|
|
177
|
+
- `Encode` returns a zero-length buffer for **void**.
|
|
178
|
+
- `Decode` and `Parse` return **void** when their input value is **void**.
|
|
179
|
+
|
|
180
|
+
Empty strings and zero-length buffers remain ordinary values; they are not serialized void markers.
|
|
181
|
+
Invalid non-void inputs are function-specific and may raise an evaluation error.
|
|
182
|
+
|
|
183
|
+
#### Boolean
|
|
184
|
+
- **Boolean.Or(values: ...(boolean | [boolean])):boolean** — Boolean disjunction of booleans and arrays of booleans
|
|
185
|
+
- **Boolean.And(values: ...(boolean | [boolean])):boolean** — Boolean conjunction of booleans and arrays of booleans
|
|
144
186
|
- **Boolean.Not(value: boolean):boolean** — Boolean negation
|
|
145
187
|
- **Boolean.Decode(value: buffer?, offset: integer?):boolean?** — Decode a byte at the optional offset; missing or out-of-range input returns **void**
|
|
146
188
|
- **Boolean.Parse(value: string?):boolean?** — Parse case-insensitive `true` or `false`; other values return **void**
|
|
@@ -148,7 +190,7 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
148
190
|
#### Timestamp
|
|
149
191
|
- **Timestamp.Now():timestamp** — Current date and time
|
|
150
192
|
- **Timestamp.Epoch(value: float | integer, epoch: timestamp?):timestamp** — Create timestamp from milliseconds
|
|
151
|
-
- **Timestamp.Decode(value: buffer?, encoding: string?, offset: integer?):timestamp?** — Decode a timestamp using `i64` (default) or `i64le`
|
|
193
|
+
- **Timestamp.Decode(value: buffer?, encoding: string?, offset: integer?):timestamp?** — Decode a timestamp using `i32` or `i32le` minutes, or `i64` (default) or `i64le` milliseconds since the Unix epoch
|
|
152
194
|
- **Timestamp.Parse(value: string?):timestamp?** — Parse a string as a timestamp
|
|
153
195
|
|
|
154
196
|
#### Float
|
|
@@ -156,26 +198,26 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
156
198
|
- **Float.PositiveInfinity** — Positive infinity
|
|
157
199
|
- **Float.NegativeInfinity** — Negative infinity
|
|
158
200
|
- **Float.Epsilon** — Smallest positive float
|
|
159
|
-
- **Float.Sum(values: ...(float |
|
|
160
|
-
- **Float.Min(values: ...(float |
|
|
161
|
-
- **Float.Max(values: ...(float |
|
|
162
|
-
- **Float.Exponent(value: float):float** — Natural exponential
|
|
163
|
-
- **Float.Logarithm(value: float):float** — Natural logarithm
|
|
164
|
-
- **Float.Abs(value: float):float** — Absolute value
|
|
165
|
-
- **Float.Ceil(value: float):float** — Smallest integer greater than or equal to the value
|
|
166
|
-
- **Float.Floor(value: float):float** — Largest integer less than or equal to the value
|
|
167
|
-
- **Float.Round(value: float):float** — Rounded value
|
|
168
|
-
- **Float.Truncate(value: float):float** — Integer portion of the value
|
|
169
|
-
- **Float.Random(exclusiveTo: float):float** — Random float up to value
|
|
201
|
+
- **Float.Sum(values: ...(float | integer | [float | integer])):float** — Numeric sum
|
|
202
|
+
- **Float.Min(values: ...(float | integer | [float | integer])):float** — Numeric minimum
|
|
203
|
+
- **Float.Max(values: ...(float | integer | [float | integer])):float** — Numeric maximum
|
|
204
|
+
- **Float.Exponent(value: float | integer):float** — Natural exponential
|
|
205
|
+
- **Float.Logarithm(value: float | integer):float** — Natural logarithm
|
|
206
|
+
- **Float.Abs(value: float | integer):float** — Absolute value
|
|
207
|
+
- **Float.Ceil(value: float | integer):float** — Smallest integer greater than or equal to the value
|
|
208
|
+
- **Float.Floor(value: float | integer):float** — Largest integer less than or equal to the value
|
|
209
|
+
- **Float.Round(value: float | integer):float** — Rounded value
|
|
210
|
+
- **Float.Truncate(value: float | integer):float** — Integer portion of the value
|
|
211
|
+
- **Float.Random(exclusiveTo: float | integer):float** — Random float up to value
|
|
170
212
|
- **Float.Decode(value: buffer?, encoding: string?, offset: integer?):float?** — Decode using `f64` (default), `f64le`, `f32`, or `f32le`
|
|
171
213
|
- **Float.Parse(value: string?):float?** — Parse a string as a float
|
|
172
214
|
|
|
173
215
|
#### Integer
|
|
174
|
-
- **Integer.Sum(values: ...(integer |
|
|
175
|
-
- **Integer.Min(values: ...(integer |
|
|
176
|
-
- **Integer.Max(values: ...(integer |
|
|
216
|
+
- **Integer.Sum(values: ...(integer | [integer])):integer** — Numeric sum
|
|
217
|
+
- **Integer.Min(values: ...(integer | [integer])):integer** — Numeric minimum
|
|
218
|
+
- **Integer.Max(values: ...(integer | [integer])):integer** — Numeric maximum
|
|
177
219
|
- **Integer.Random(exclusiveTo: integer):integer** — Random integer up to value
|
|
178
|
-
- **Integer.Decode(value: buffer?, encoding: string?, offset: integer?):integer?** — Decode using signed `i8`, `i16`, `i16le`, `i32`, `i32le`, `i64` (default), or `i64le`, or unsigned `n8`, `n16`, `n16le`, `n32`, `n32le
|
|
220
|
+
- **Integer.Decode(value: buffer?, encoding: string?, offset: integer?):integer?** — Decode using signed `i8`, `i16`, `i16le`, `i32`, `i32le`, `i64` (default), or `i64le`, or unsigned `n8`, `n16`, `n16le`, `n32`, `n32le`
|
|
179
221
|
- **Integer.Parse(value: string?):integer?** — Parse a string as an integer
|
|
180
222
|
|
|
181
223
|
#### String
|
|
@@ -189,13 +231,13 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
189
231
|
|
|
190
232
|
#### Array
|
|
191
233
|
- **Array.Join(values: ...array):array** — Join arrays of any depths into a single array
|
|
192
|
-
- **Array.Range(
|
|
234
|
+
- **Array.Range(a: integer, b: integer):array** — Integers from the lower endpoint (inclusive) to the higher endpoint (exclusive)
|
|
193
235
|
- **Array.Unique(value: array):array** — Array of unique values
|
|
194
236
|
- **Array.Intersection(a1: array, a2: array):array** — Common values from two arrays
|
|
195
237
|
- **Array.Difference(a1: array, a2: array):array** — Symmetrical difference between arrays
|
|
196
238
|
|
|
197
|
-
#### Object
|
|
198
|
-
- **Object.Merge(values: ...(object |
|
|
239
|
+
#### Object
|
|
240
|
+
- **Object.Merge(values: ...(object | [object])):object** — Merge objects and arrays of objects
|
|
199
241
|
|
|
200
242
|
#### AN
|
|
201
243
|
- **AN.Format(value: ??, whitespace: string?):string** — Format a value as AN notation
|
|
@@ -204,8 +246,8 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
204
246
|
- **JSON.Format(value: (void | boolean | timestamp | float | integer | string | array | object), whitespace: string?):string** — Format a value as JSON
|
|
205
247
|
- **JSON.Parse(value: string?):(void | boolean | timestamp | float | integer | string | array | object)** — Parse a JSON-formatted string; standard JSON values are not revived as timestamps or integers
|
|
206
248
|
|
|
207
|
-
#### IP
|
|
208
|
-
- **IP.Match(values:
|
|
249
|
+
#### IP
|
|
250
|
+
- **IP.Match(values: [string], search: ...(string | [string])):boolean** — Check whether any searched IPv4 or IPv6 address belongs to the supplied addresses or CIDR ranges
|
|
209
251
|
- **IP.Encode(value: string?):buffer** — Encode an IPv4, IPv6, or CIDR string as a network-byte-order buffer; malformed or **void** input returns a zero-length buffer
|
|
210
252
|
- **IP.Decode(value: buffer?):string?** — Decode a 4-, 5-, 16-, or 17-byte buffer as canonical IPv4, IPv6, or CIDR notation; malformed or **void** input returns **void**
|
|
211
253
|
|
|
@@ -216,11 +258,12 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
216
258
|
- **??.Equal(value: ??):boolean** — Equals to
|
|
217
259
|
- **??.Unequal(value: ??):boolean** — Not equals to
|
|
218
260
|
- **(boolean | buffer | function).Encode():buffer** — Encode value to buffer
|
|
219
|
-
- **(void | timestamp | float | integer | string | array | object).Encode(encoding: string?):buffer** — Encode a value; defaults are `i64` for timestamps and integers, `f64` for floats, and `utf8` for strings
|
|
261
|
+
- **(void | timestamp | float | integer | string | array | object).Encode(encoding: string?):buffer** — Encode a value; timestamps support `i32` and `i32le` minutes or `i64` and `i64le` milliseconds, while defaults are `i64` for timestamps and integers, `f64` for floats, and `utf8` for strings
|
|
220
262
|
- **(boolean | string | function).Format():string** — Format value to string
|
|
221
263
|
- **(void | timestamp | float | integer | buffer | array | object).Format(formatting: string?):string** — Format a value; buffers use `hex` by default and also support `base64`
|
|
222
264
|
|
|
223
265
|
#### Aggregable Functions
|
|
266
|
+
- **float.Add(value: float):float** — Add a float
|
|
224
267
|
- **float.Add(value: integer):float** — Add an integer
|
|
225
268
|
- **integer.Add(value: float):float** — Add a float
|
|
226
269
|
- **integer.Add(value: integer):integer** — Add an integer
|
|
@@ -228,19 +271,19 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
228
271
|
- **string.Add(value: string):string** — Concatenate strings
|
|
229
272
|
- **array.Add(value: array):array** — Concatenate arrays
|
|
230
273
|
|
|
231
|
-
#### Array Functions
|
|
232
|
-
- **array.First(condition:
|
|
233
|
-
- **array.Last(condition:
|
|
234
|
-
- **array.FirstIndex(condition:
|
|
235
|
-
- **array.LastIndex(condition:
|
|
236
|
-
- **array.Every(condition:
|
|
237
|
-
- **array.Any(condition:
|
|
238
|
-
- **array.Reverse():array** — Reversed array
|
|
239
|
-
- **array.Flatten(depth: integer = 1):array** — Flatten array
|
|
240
|
-
- **array.Derive(transformation:
|
|
241
|
-
- **array.Filter(condition:
|
|
242
|
-
- **array.Reduce(reducer:
|
|
243
|
-
- **array.Compose(generator:
|
|
274
|
+
#### Array Functions
|
|
275
|
+
- **array.First(condition: ~(??, integer?, array?):boolean):??** — First item satisfying condition
|
|
276
|
+
- **array.Last(condition: ~(??, integer?, array?):boolean):??** — Last item satisfying condition
|
|
277
|
+
- **array.FirstIndex(condition: ~(??, integer?, array?):boolean):integer?** — First index satisfying condition, or **void** if none does
|
|
278
|
+
- **array.LastIndex(condition: ~(??, integer?, array?):boolean):integer?** — Last index satisfying condition, or **void** if none does
|
|
279
|
+
- **array.Every(condition: ~(??, integer?, array?):boolean):boolean** — All items satisfy condition
|
|
280
|
+
- **array.Any(condition: ~(??, integer?, array?):boolean):boolean** — Any item satisfies condition
|
|
281
|
+
- **array.Reverse():array** — Reversed array
|
|
282
|
+
- **array.Flatten(depth: integer = 1):array** — Flatten array
|
|
283
|
+
- **array.Derive(transformation: ~(??, integer?, array?):??):array** — Derived array
|
|
284
|
+
- **array.Filter(condition: ~(??, integer?, array?):boolean):array** — Filtered array
|
|
285
|
+
- **array.Reduce(reducer: ~(??, ??, integer?, array?):??, initial: ?? = void):??** — Reduced value
|
|
286
|
+
- **array.Compose(generator: ~(object, string, integer?, array?):??):object** — Compose object from array
|
|
244
287
|
- **array.Prepend(items: ...??):array** — Prepend items
|
|
245
288
|
- **array.Append(items: ...??):array** — Append items
|
|
246
289
|
|
|
@@ -251,11 +294,11 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
251
294
|
- **buffer.Slice(start: integer?, end: integer?):buffer** — Slice section
|
|
252
295
|
- **string.Slice(start: integer?, end: integer?):string** — Slice section
|
|
253
296
|
- **array.Slice(start: integer?, end: integer?):array** — Slice section
|
|
254
|
-
- **buffer.Splice(start: integer, remove: integer, inject: ...
|
|
255
|
-
- **string.Splice(start: integer, remove: integer, inject: ...
|
|
297
|
+
- **buffer.Splice(start: integer, remove: integer, inject: ...buffer):buffer** — Splice section
|
|
298
|
+
- **string.Splice(start: integer, remove: integer, inject: ...string):string** — Splice section
|
|
256
299
|
- **array.Splice(start: integer, remove: integer, inject: ...array):array** — Splice section
|
|
257
|
-
- **buffer.Inject(start: integer, inject: ...
|
|
258
|
-
- **string.Inject(start: integer, inject: ...
|
|
300
|
+
- **buffer.Inject(start: integer, inject: ...buffer):buffer** — Inject section
|
|
301
|
+
- **string.Inject(start: integer, inject: ...string):string** — Inject section
|
|
259
302
|
- **array.Inject(start: integer, inject: ...array):array** — Inject section
|
|
260
303
|
|
|
261
304
|
#### Iterable Functions
|
|
@@ -269,52 +312,57 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
269
312
|
- **array.Has(index: integer):boolean** — Identify if array has index
|
|
270
313
|
- **object.Has(index: string):boolean** — Identify if object has key
|
|
271
314
|
|
|
272
|
-
#### Number Functions
|
|
273
|
-
- **(float | integer).GreaterThan(value):boolean** — Greater than
|
|
274
|
-
- **(float | integer).LessThan(value):boolean** — Less than
|
|
275
|
-
- **(float | integer).GreaterOrEqual(value):boolean** — Greater or equal
|
|
276
|
-
- **(float | integer).LessOrEqual(value):boolean** — Less or equal
|
|
277
|
-
- **float.Subtract(subtrahend):float** — Subtract
|
|
278
|
-
- **integer.Subtract(subtrahend):
|
|
279
|
-
- **
|
|
280
|
-
- **
|
|
281
|
-
- **
|
|
282
|
-
- **
|
|
283
|
-
- **integer.Multiply(value:
|
|
284
|
-
- **
|
|
285
|
-
- **
|
|
286
|
-
- **
|
|
287
|
-
- **integer.
|
|
288
|
-
- **float.
|
|
289
|
-
- **integer.
|
|
290
|
-
- **
|
|
291
|
-
- **
|
|
292
|
-
- **
|
|
293
|
-
- **integer.
|
|
294
|
-
- **float.
|
|
295
|
-
- **integer.
|
|
296
|
-
- **integer.
|
|
297
|
-
- **float.
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
- **
|
|
301
|
-
- **
|
|
302
|
-
- **
|
|
315
|
+
#### Number Functions
|
|
316
|
+
- **(float | integer).GreaterThan(value: float | integer):boolean** — Greater than
|
|
317
|
+
- **(float | integer).LessThan(value: float | integer):boolean** — Less than
|
|
318
|
+
- **(float | integer).GreaterOrEqual(value: float | integer):boolean** — Greater or equal
|
|
319
|
+
- **(float | integer).LessOrEqual(value: float | integer):boolean** — Less or equal
|
|
320
|
+
- **float.Subtract(subtrahend: integer):float** — Subtract an integer
|
|
321
|
+
- **integer.Subtract(subtrahend: float):float** — Subtract a float
|
|
322
|
+
- **integer.Subtract(subtrahend: integer):integer** — Subtract an integer
|
|
323
|
+
- **float.Negate():float** — Negate number
|
|
324
|
+
- **integer.Negate():integer** — Negate number
|
|
325
|
+
- **float.Multiply(value: integer):float** — Multiply by an integer
|
|
326
|
+
- **integer.Multiply(value: float):float** — Multiply by a float
|
|
327
|
+
- **integer.Multiply(value: integer):integer** — Multiply by an integer
|
|
328
|
+
- **float.Divide(divisor: integer):float** — Divide by an integer
|
|
329
|
+
- **integer.Divide(divisor: float):float** — Divide by a float
|
|
330
|
+
- **integer.Divide(divisor: integer):integer** — Divide by an integer
|
|
331
|
+
- **float.Remainder(divisor: integer):float** — Remainder after division by an integer
|
|
332
|
+
- **integer.Remainder(divisor: float):float** — Remainder after division by a float
|
|
333
|
+
- **integer.Remainder(divisor: integer):integer** — Remainder after division by an integer
|
|
334
|
+
- **float.Modulo(divisor: integer):float** — Modulo by an integer
|
|
335
|
+
- **integer.Modulo(divisor: float):float** — Modulo by a float
|
|
336
|
+
- **integer.Modulo(divisor: integer):integer** — Modulo by an integer
|
|
337
|
+
- **float.Power(exponent: integer):float** — Raise to an integer power
|
|
338
|
+
- **integer.Power(exponent: float):float** — Raise to a float power
|
|
339
|
+
- **integer.Power(exponent: integer):integer** — Raise to an integer power
|
|
340
|
+
- **float.Root(index: integer):float** — Take an integer root
|
|
341
|
+
- **integer.Root(index: float):float** — Take a float root
|
|
342
|
+
- **integer.Root(index: integer):integer** — Take an integer root
|
|
343
|
+
- **(boolean | timestamp | integer).Float():float** — Convert to a float; timestamps use milliseconds since the Unix epoch
|
|
344
|
+
- **(boolean | timestamp | float).Integer():integer** — Convert to an integer; timestamps use milliseconds since the Unix epoch
|
|
345
|
+
- **(timestamp | float | integer).Boolean():boolean** — Convert to a boolean by testing whether the numeric or epoch value is non-zero
|
|
346
|
+
|
|
347
|
+
#### Object Functions
|
|
348
|
+
- **object.Entries():array** — Key-value pairs
|
|
349
|
+
- **object.Keys():[string]** — Object keys
|
|
350
|
+
- **object.Values():array** — Object values
|
|
303
351
|
|
|
304
352
|
#### String Functions
|
|
305
353
|
- **string.Like(value: string):boolean** — Alphanumeric equality
|
|
306
354
|
- **string.Unlike(value: string):boolean** — Alphanumeric inequality
|
|
307
355
|
- **string.StartsWith(search: string, startPos: integer?, ignoreCaseSpaceEtc: boolean?):boolean** — Prefix check
|
|
308
356
|
- **string.EndsWith(search: string, endPos: integer?, ignoreCaseSpaceEtc: boolean?):boolean** — Suffix check
|
|
309
|
-
- **string.Char(pos: integer):string
|
|
310
|
-
- **string.CharCode(pos: integer):integer
|
|
357
|
+
- **string.Char(pos: integer):string?** — Character at position, or **void** when unavailable
|
|
358
|
+
- **string.CharCode(pos: integer):integer?** — Character code, or **void** when unavailable
|
|
311
359
|
- **string.Trim():string** — Trim whitespace
|
|
312
360
|
- **string.TrimStart():string** — Trim leading whitespace
|
|
313
361
|
- **string.TrimEnd():string** — Trim trailing whitespace
|
|
314
362
|
- **string.LowerCase():string** — To lowercase
|
|
315
363
|
- **string.UpperCase():string** — To uppercase
|
|
316
|
-
- **string.Split(separator: string = ' '):
|
|
317
|
-
- **string.ReplaceWith(replacement: string, search: ...(string |
|
|
364
|
+
- **string.Split(separator: string = ' '):[string]** — Split into an array of strings
|
|
365
|
+
- **string.ReplaceWith(replacement: string, search: ...(string | [string])):string** — Replace all instances of the searched strings
|
|
318
366
|
|
|
319
367
|
#### Timestamp Functions
|
|
320
368
|
- **timestamp.Year(utc: boolean?):integer** — Get year
|
|
@@ -332,35 +380,59 @@ Invalid non-null inputs are function-specific and may raise an evaluation error.
|
|
|
332
380
|
- **timestamp.MinutesSince(value: timestamp):float** — Difference from another timestamp in minutes
|
|
333
381
|
- **timestamp.SecondsSince(value: timestamp):float** — Difference from another timestamp in seconds
|
|
334
382
|
|
|
335
|
-
## Reference
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
const
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
383
|
+
## Reference
|
|
384
|
+
|
|
385
|
+
Install the package:
|
|
386
|
+
|
|
387
|
+
```sh
|
|
388
|
+
npm install affinirum
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
Create an `Affinirum` instance with a script and optional compilation configuration, then call `evaluate`
|
|
392
|
+
with the script's input variables:
|
|
393
|
+
|
|
394
|
+
```ts
|
|
395
|
+
import { Affinirum } from "affinirum";
|
|
396
|
+
|
|
397
|
+
const expression = new Affinirum("a + b");
|
|
398
|
+
const result = expression.evaluate({ a: 10n, b: 20n }); // 30n
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
During parsing, any valid name that is not recognized as a keyword, constant, or built-in function is treated as an input variable.
|
|
402
|
+
Use the optional constructor configuration to specify the expected result `type`, enable `strict` handling of undeclared variables,
|
|
403
|
+
or declare input `variables` and their types. An instance exposes the original `script`, its inferred result `type`,
|
|
404
|
+
the inferred input types through `variables()`, and the parsed tree through `toString()`. `Affinirum.format()` formats
|
|
405
|
+
a JavaScript value using Affinirum Notation.
|
|
406
|
+
|
|
407
|
+
JavaScript `number` values map to **float**, while **integer** values map to `bigint`. Timestamps use `Date`, buffers use
|
|
408
|
+
`ArrayBuffer`, and a **void** result is returned as `undefined`. Arrays, objects, and functions use their corresponding
|
|
409
|
+
JavaScript values. Injected non-function values are checked against the types inferred or declared during compilation.
|
|
410
|
+
Injected functions are checked to be callable; their JavaScript parameter behavior and return values are trusted according
|
|
411
|
+
to their declared Affinirum types.
|
|
412
|
+
|
|
413
|
+
Use **val** for a local value that cannot be reassigned and **var** for a reassignable local variable. Statements are
|
|
414
|
+
separated with semicolons.
|
|
415
|
+
|
|
416
|
+
Sample code:
|
|
417
|
+
|
|
418
|
+
```ts
|
|
419
|
+
const expr = new Affinirum("x * (y + abc / 5) > 10");
|
|
420
|
+
const value1 = expr.evaluate({ x: 10, y: 20, abc: 10 }); // true
|
|
421
|
+
const value2 = expr.evaluate({ x: 1, y: 4, abc: 5 }); // false
|
|
422
|
+
|
|
423
|
+
const arrExpr = new Affinirum("Integer.Sum([1, 2, 3, a, b, c])");
|
|
424
|
+
const valueSum = arrExpr.evaluate({ a: 10n, b: 20n, c: 30n }); // 66n
|
|
425
|
+
|
|
426
|
+
const objExpr = new Affinirum('["prop1":a, "prop2":"abc"].prop1 + 10');
|
|
427
|
+
const oValue = objExpr.evaluate({ a: 50n }); // 60n
|
|
428
|
+
|
|
429
|
+
const iteratorExpr = new Affinirum(
|
|
430
|
+
"Float.Sum(arr1.Derive(~(a:float):float{a*2}).Filter(~(a:float):boolean{a>3}))"
|
|
431
|
+
);
|
|
432
|
+
const iValue = iteratorExpr.evaluate({ arr1: [1, 2, 3] }); // 10
|
|
433
|
+
|
|
434
|
+
const complexExpr = new Affinirum(
|
|
435
|
+
"var a = myvar1 / 10; val b = myvar2 - 100; a / b + b * a + 600"
|
|
436
|
+
);
|
|
437
|
+
const value = complexExpr.evaluate({ myvar1: 40, myvar2: 104 }); // 617
|
|
438
|
+
```
|