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.
Files changed (89) hide show
  1. package/README.md +226 -154
  2. package/dst/Affinirum.js +24 -15
  3. package/dst/Atom.d.ts +3 -1
  4. package/dst/Constant.js +1 -1
  5. package/dst/Functions.js +7 -4
  6. package/dst/Keywords.js +4 -4
  7. package/dst/ParserState.d.ts +2 -1
  8. package/dst/ParserState.js +43 -82
  9. package/dst/Type.d.ts +11 -7
  10. package/dst/Type.js +113 -38
  11. package/dst/Value.d.ts +1 -0
  12. package/dst/Value.js +19 -1
  13. package/dst/atom/ArrayAtom.d.ts +7 -3
  14. package/dst/atom/ArrayAtom.js +53 -8
  15. package/dst/atom/FunctionAtom.d.ts +4 -1
  16. package/dst/atom/FunctionAtom.js +65 -15
  17. package/dst/atom/ObjectAtom.d.ts +7 -5
  18. package/dst/atom/ObjectAtom.js +35 -13
  19. package/dst/atom/PrimitiveAtom.d.ts +3 -1
  20. package/dst/atom/PrimitiveAtom.js +10 -1
  21. package/dst/cjs/Affinirum.js +24 -15
  22. package/dst/cjs/Constant.js +1 -1
  23. package/dst/cjs/Functions.js +6 -3
  24. package/dst/cjs/Keywords.js +4 -4
  25. package/dst/cjs/ParserState.js +42 -81
  26. package/dst/cjs/Type.js +113 -38
  27. package/dst/cjs/Value.js +21 -0
  28. package/dst/cjs/atom/ArrayAtom.js +53 -8
  29. package/dst/cjs/atom/FunctionAtom.js +65 -15
  30. package/dst/cjs/atom/ObjectAtom.js +35 -13
  31. package/dst/cjs/atom/PrimitiveAtom.js +10 -1
  32. package/dst/cjs/native/Aggregable.js +3 -2
  33. package/dst/cjs/native/Array.js +10 -8
  34. package/dst/cjs/native/Boolean.js +8 -5
  35. package/dst/cjs/native/Buffer.js +32 -3
  36. package/dst/cjs/native/Enumerable.js +7 -4
  37. package/dst/cjs/native/Float.js +26 -13
  38. package/dst/cjs/native/Integer.js +64 -28
  39. package/dst/cjs/native/Iterable.js +8 -5
  40. package/dst/cjs/native/Number.js +62 -33
  41. package/dst/cjs/native/Object.js +2 -1
  42. package/dst/cjs/native/String.js +71 -24
  43. package/dst/cjs/native/Timestamp.js +76 -18
  44. package/dst/cjs/native/Unknown.js +1 -1
  45. package/dst/cjs/native/notation/AN.js +152 -11
  46. package/dst/cjs/native/notation/IP.js +4 -3
  47. package/dst/cjs/native/notation/JSON.js +1 -1
  48. package/dst/cjs/node/ArrayNode.js +6 -6
  49. package/dst/cjs/node/BlockNode.js +5 -4
  50. package/dst/cjs/node/CallNode.js +28 -22
  51. package/dst/cjs/node/CastNode.js +42 -0
  52. package/dst/cjs/node/ObjectNode.js +2 -4
  53. package/dst/cjs/node/SwitchNode.js +10 -10
  54. package/dst/cjs/node/VariableNode.js +3 -1
  55. package/dst/native/Aggregable.js +3 -2
  56. package/dst/native/Array.js +10 -8
  57. package/dst/native/Boolean.d.ts +1 -0
  58. package/dst/native/Boolean.js +7 -4
  59. package/dst/native/Buffer.d.ts +2 -0
  60. package/dst/native/Buffer.js +29 -2
  61. package/dst/native/Enumerable.js +7 -4
  62. package/dst/native/Float.d.ts +2 -0
  63. package/dst/native/Float.js +25 -12
  64. package/dst/native/Integer.d.ts +5 -1
  65. package/dst/native/Integer.js +61 -27
  66. package/dst/native/Iterable.js +8 -5
  67. package/dst/native/Number.d.ts +4 -3
  68. package/dst/native/Number.js +57 -32
  69. package/dst/native/Object.js +2 -1
  70. package/dst/native/String.d.ts +2 -7
  71. package/dst/native/String.js +68 -16
  72. package/dst/native/Timestamp.d.ts +4 -2
  73. package/dst/native/Timestamp.js +73 -17
  74. package/dst/native/Unknown.js +1 -1
  75. package/dst/native/notation/AN.d.ts +1 -0
  76. package/dst/native/notation/AN.js +152 -12
  77. package/dst/native/notation/IP.js +4 -3
  78. package/dst/native/notation/JSON.js +1 -1
  79. package/dst/node/ArrayNode.d.ts +1 -1
  80. package/dst/node/ArrayNode.js +6 -6
  81. package/dst/node/BlockNode.js +5 -4
  82. package/dst/node/CallNode.js +28 -22
  83. package/dst/node/CastNode.d.ts +15 -0
  84. package/dst/node/CastNode.js +38 -0
  85. package/dst/node/ObjectNode.d.ts +1 -1
  86. package/dst/node/ObjectNode.js +2 -4
  87. package/dst/node/SwitchNode.js +10 -10
  88. package/dst/node/VariableNode.js +3 -1
  89. 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, dynamic typing,
5
- and extensibility for custom operations—enabling rapid prototyping, advanced rule evaluation,
6
- and safe script execution in constrained environments.
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 browser and NodeJS.
10
+ Runs in browsers and Node.js.
11
11
 
12
- Target: ES2022 [browser+NodeJS][ESM+CJS].
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-order function support for expressive scripting.
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
- Easy way to check if array contains an index is to use presence operator (**?**), like *theArray?50*.
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 pair enclosed in brackets (**[]**) where key is separated from value by colon (**:**),
47
- like *["key1":100, "key2":"abc"]*, *["a":0,"b":"str":"c":valueVar]*.
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
- Easy way to check if object contains a key is to use presence operator (**?**), like *theObject?myKey*.
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 set of built-in functions can be extended through configuration entries.
59
- Additionally, subroutines (functions defined in code) can be created.
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, millisecons since Unix epoch
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
- - **??** for unknown or variant type
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 definiton: **[item1, ...]**
92
- - Object definition: **[propery1-key: property1-value, ...]**
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 ommited second value deemed *null*
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
- - Null coalescence: **?:**
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 existance operator: **?**
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 null handling:
133
-
134
- - `Format` returns an empty string for a **null**.
135
- - `Encode` returns a zero-length buffer for a **null**.
136
- - `Decode` and `Parse` return **null** when their input value is **null**.
137
-
138
- Empty strings and zero-length buffers remain ordinary values; they are not serialized null markers.
139
- Invalid non-null inputs are function-specific and may raise an evaluation error.
140
-
141
- #### Boolean
142
- - **Boolean.Or(values: ...(boolean | array)):boolean** — Boolean disjunction of booleans and arrays of booleans
143
- - **Boolean.And(values: ...(boolean | array)):boolean** — Boolean conjunction of booleans and arrays of booleans
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 | array)):float** — Numeric sum
160
- - **Float.Min(values: ...(float | array)):float** — Numeric minimum
161
- - **Float.Max(values: ...(float | array)):float** — Numeric maximum
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 | array)):integer** — Numeric sum
175
- - **Integer.Min(values: ...(integer | array)):integer** — Numeric minimum
176
- - **Integer.Max(values: ...(integer | array)):integer** — Numeric maximum
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`, `n64`, or `n64le`
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(inclusiveFrom: integer, exclusiveTo: integer):array** — New array filled with integers in 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 | array)):object** — Merge objects and arrays of objects
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: array, search: ...(string | array)):boolean** — Check whether any searched IPv4 or IPv6 address belongs to the supplied addresses or CIDR ranges
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: function):??** — First item satisfying condition
233
- - **array.Last(condition: function):??** — Last item satisfying condition
234
- - **array.FirstIndex(condition: function):integer?** — First index satisfying condition, or **void** if none does
235
- - **array.LastIndex(condition: function):integer?** — Last index satisfying condition, or **void** if none does
236
- - **array.Every(condition: function):boolean** — All items satisfy condition
237
- - **array.Any(condition: function):boolean** — Any item satisfies condition
238
- - **array.Reverse():array** — Reversed array
239
- - **array.Flatten(depth: integer = 1):array** — Flatten array
240
- - **array.Derive(transformation: function):array** — Derived array
241
- - **array.Filter(condition: function):array** — Filtered array
242
- - **array.Reduce(reducer: function, initial: ?? = void):??** — Reduced value
243
- - **array.Compose(generator: function):object** — Compose object from array
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: ...array):buffer** — Splice section
255
- - **string.Splice(start: integer, remove: integer, inject: ...array):string** — Splice section
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: ...array):buffer** — Inject section
258
- - **string.Inject(start: integer, inject: ...array):string** — Inject section
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 value
278
- - **integer.Subtract(subtrahend):integer** — Subtract value
279
- - **float.Negate():float** — Negate number
280
- - **integer.Negate():integer** — Negate number
281
- - **float.Multiply(value: integer):float** — Multiply by an integer
282
- - **integer.Multiply(value: float):float** — Multiply by a float
283
- - **integer.Multiply(value: integer):integer** — Multiply by an integer
284
- - **float.Divide(divisor):float** — Divide value
285
- - **integer.Divide(divisor):integer** — Divide value
286
- - **float.Remainder(divisor):float** — Remainder
287
- - **integer.Remainder(divisor):integer** — Remainder
288
- - **float.Modulo(divisor):float** — Modulo
289
- - **integer.Modulo(divisor):integer** — Modulo
290
- - **float.Power(exponent):float** — Power
291
- - **integer.Power(exponent):integer** — Power
292
- - **float.Root(index):float** — Root
293
- - **integer.Root(index):integer** — Root
294
- - **float.Cast():integer** — Cast to integer
295
- - **integer.Cast():float** — Cast to float
296
- - **integer.CastToFloat():float** — Cast to float
297
- - **float.CastToInteger():integer** — Cast to integer
298
-
299
- #### Object Functions
300
- - **object.Entries():array** — Key-value pairs
301
- - **object.Keys():array** — Object keys
302
- - **object.Values():array** — Object values
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** — Character at position
310
- - **string.CharCode(pos: integer):integer** — Character code
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 = ' '):array** — Split into array
317
- - **string.ReplaceWith(replacement: string, search: ...(string | array)):string** — Replace all instances of the searched strings
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
- Create instance of Affinirum class with a string containing script and optional compilation configuration.
338
- During the parsing any alphanumeric sequence not identified as
339
- number value, string value, operator, or a function name is assumed to be variable.
340
- Evaluate the expression by providing variable values.
341
-
342
- Sample code:
343
-
344
- ```ts
345
- ...
346
- const expr = new Affinirum( 'x * (y + abc / 5) > 10' );
347
- const value1 = expr.evaluate( { x: 10, y: 20, abc: 10 } ); // true
348
- const value2 = expr.evaluate( { x: 1, y: 4, abc: 5 } ); // false
349
- ...
350
- const arrExpr = new Affinirum( 'Integer.Sum([ 1, 2, 3, a, b, c ])' );
351
- const valueSum = arrExpr.evaluate( { a: 10, b: 20, c: 30 } ); // 66
352
- ...
353
- const objExpr = new Affinirum( '[`prop1`:a,`prop2`:`abc`].prop1+10' );
354
- const oValue = objExpr.evaluate( { a: 50 } ); // 60
355
- ...
356
- const iteratorExpr = new Affinirum(
357
- 'Float.Sum(arr1.Derive(~(a:float):float{a*2}).Filter(~(a:float):boolean{a>3}))'
358
- );
359
- const iValue = iteratorExpr.evaluate( { arr1: [ 1, 2, 3 ] } ); // 10
360
- ...
361
- const complexExpr = new Affinirum(
362
- 'var a=myvar1/10, val b=myvar2-100, a/b + b*a + 600'
363
- );
364
- const value = complexExpr.evaluate( { myvar1: 40, myvar2: 104 } ); // 4761
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
+ ```