345 lines
17 KiB
Markdown
345 lines
17 KiB
Markdown
# East Standard Library
|
|
|
|
The East Standard Library provides utility functions that extend East's core expression types with additional formatting, conversion, and generation capabilities.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [Boolean](#boolean)
|
|
- [Integer](#integer)
|
|
- [Float](#float)
|
|
- [String](#string)
|
|
- [DateTime](#datetime)
|
|
- [Blob](#blob)
|
|
- [Array](#array)
|
|
- [Set](#set)
|
|
- [Dict](#dict)
|
|
- [Struct](#struct)
|
|
- [Variant](#variant)
|
|
|
|
---
|
|
|
|
## Standard Library Expressions
|
|
|
|
This section documents the standard library expression available for each East type. These are accessed through the `East` namespace (e.g., `East.Integer.printCommaSeparated()`, `East.DateTime.fromEpochMilliseconds()`).
|
|
|
|
For core operations on expressions (like `.add()`, `.multiply()`, `.map()`), see [USAGE.md](./USAGE.md).
|
|
|
|
### Boolean
|
|
|
|
Boolean expressions currently have no standard library methods.
|
|
|
|
---
|
|
|
|
### Integer
|
|
|
|
The Integer standard library provides formatting and rounding utilities for integer values.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const formatNumber = East.function([IntegerType], StringType, ($, value) => {
|
|
// Format with thousand separators
|
|
const commaSeparated = East.Integer.printCommaSeperated(value);
|
|
// Alternative ways:
|
|
// const commaSeparated = $.let(East.Integer.printCommaSeperated);
|
|
// $(commaSeparated(value));
|
|
|
|
// Format with compact units (K, M, B, etc.)
|
|
const compact = East.Integer.printCompact(value);
|
|
|
|
// Round to nearest multiple
|
|
const rounded = East.Integer.roundNearest(value, 10n);
|
|
|
|
// Format as ordinal (1st, 2nd, 3rd, etc.)
|
|
const ordinal = East.Integer.printOrdinal(rounded);
|
|
|
|
$.return(East.str`${commaSeparated} = ${compact}, rounded to ${ordinal}`);
|
|
});
|
|
|
|
const compiled = East.compile(formatNumber, {});
|
|
console.log(compiled(1234567n)); // "1,234,567 = 1.23M, rounded to 1234570th"
|
|
console.log(compiled(47n)); // "47 = 47, rounded to 50th"
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| **Formatting** |
|
|
| `East.Integer.printCommaSeperated(x: IntegerExpr \| bigint): StringExpr` | Format with commas: `"1,234,567"` | `East.Integer.printCommaSeperated(1234567n)` |
|
|
| `East.Integer.printCompact(x: IntegerExpr \| bigint): StringExpr` | Business units: `"1.5M"`, `"21K"` | `East.Integer.printCompact(1500000n)` |
|
|
| `East.Integer.printCompactSI(x: IntegerExpr \| bigint): StringExpr` | SI units: `"1.5M"`, `"21k"` | `East.Integer.printCompactSI(21000n)` |
|
|
| `East.Integer.printCompactComputing(x: IntegerExpr \| bigint): StringExpr` | Binary units (1024): `"1.5Mi"`, `"21ki"` | `East.Integer.printCompactComputing(21504n)` |
|
|
| `East.Integer.printOrdinal(x: IntegerExpr \| bigint): StringExpr` | Ordinal: `"1st"`, `"2nd"`, `"3rd"` | `East.Integer.printOrdinal(1n)` |
|
|
| `East.Integer.printPercentage(x: IntegerExpr \| bigint): StringExpr` | Format as percentage: `"45%"` | `East.Integer.printPercentage(45n)` |
|
|
| **Utilities** |
|
|
| `East.Integer.digitCount(x: IntegerExpr \| bigint): IntegerExpr` | Count decimal digits (excluding sign) | `East.Integer.digitCount(1234n)` |
|
|
| **Rounding** |
|
|
| `East.Integer.roundNearest(x: IntegerExpr \| bigint, step: IntegerExpr \| bigint): IntegerExpr` | Round to nearest multiple of step | `East.Integer.roundNearest(47n, 10n)` |
|
|
| `East.Integer.roundUp(x: IntegerExpr \| bigint, step: IntegerExpr \| bigint): IntegerExpr` | Round up (ceiling) to multiple of step | `East.Integer.roundUp(41n, 10n)` |
|
|
| `East.Integer.roundDown(x: IntegerExpr \| bigint, step: IntegerExpr \| bigint): IntegerExpr` | Round down (floor) to multiple of step | `East.Integer.roundDown(47n, 10n)` |
|
|
| `East.Integer.roundTruncate(x: IntegerExpr \| bigint, step: IntegerExpr \| bigint): IntegerExpr` | Round towards zero to multiple of step | `East.Integer.roundTruncate(-47n, 10n)` |
|
|
|
|
|
|
---
|
|
|
|
### Float
|
|
|
|
The Float standard library provides rounding, comparison, and formatting utilities for floating-point values.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const formatNumber = East.function([FloatType], StringType, ($, value) => {
|
|
// Round to 2 decimal places
|
|
const rounded = East.Float.roundToDecimals(value, 2n);
|
|
|
|
// Format as currency with $ sign
|
|
const currency = East.Float.printCurrency(value);
|
|
|
|
// Format with comma separators
|
|
const formatted = East.Float.printCommaSeperated(value, 2n);
|
|
|
|
// Format as percentage
|
|
const percentage = East.Float.printPercentage(value, 1n);
|
|
|
|
// Format in compact form (21.5K, 1.82M, etc.)
|
|
const compact = East.Float.printCompact(value);
|
|
|
|
$.return(East.str`Currency: ${currency}, Formatted: ${formatted}, Compact: ${compact}`);
|
|
});
|
|
|
|
const compiled = East.compile(formatNumber, {});
|
|
console.log(compiled(1234567.89));
|
|
// "Currency: $1234567.89, Formatted: 1234567.89, Compact: 1.23M"
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| **Rounding to Integers** |
|
|
| `East.Float.roundFloor(x: FloatExpr \| number): IntegerExpr` | Round down to nearest integer (floor) | `East.Float.roundFloor(3.7)` → `3n` |
|
|
| `East.Float.roundCeil(x: FloatExpr \| number): IntegerExpr` | Round up to nearest integer (ceiling) | `East.Float.roundCeil(3.2)` → `4n` |
|
|
| `East.Float.roundHalf(x: FloatExpr \| number): IntegerExpr` | Round to nearest integer (half-away-from-zero) | `East.Float.roundHalf(3.5)` → `4n` |
|
|
| `East.Float.roundTrunc(x: FloatExpr \| number): IntegerExpr` | Truncate towards zero | `East.Float.roundTrunc(-3.7)` → `-3n` |
|
|
| **Rounding to Step Values** |
|
|
| `East.Float.roundNearest(x: FloatExpr \| number, step: FloatExpr \| number): FloatExpr` | Round to nearest multiple of step | `East.Float.roundNearest(47.3, 10.0)` → `50.0` |
|
|
| `East.Float.roundUp(x: FloatExpr \| number, step: FloatExpr \| number): FloatExpr` | Round up (ceiling) to multiple of step | `East.Float.roundUp(41.2, 10.0)` → `50.0` |
|
|
| `East.Float.roundDown(x: FloatExpr \| number, step: FloatExpr \| number): FloatExpr` | Round down (floor) to multiple of step | `East.Float.roundDown(47.8, 10.0)` → `40.0` |
|
|
| `East.Float.roundTruncate(x: FloatExpr \| number, step: FloatExpr \| number): FloatExpr` | Round towards zero to multiple of step | `East.Float.roundTruncate(-47.8, 10.0)` → `-40.0` |
|
|
| `East.Float.roundToDecimals(x: FloatExpr \| number, decimals: IntegerExpr \| bigint): FloatExpr` | Round to specified number of decimal places | `East.Float.roundToDecimals(3.14159, 2n)` → `3.14` |
|
|
| **Comparison** |
|
|
| `East.Float.approxEqual(x: FloatExpr \| number, y: FloatExpr \| number, epsilon: FloatExpr \| number): BooleanExpr` | Check if two floats are approximately equal within tolerance | `East.Float.approxEqual(0.1, 0.10001, 0.001)` → `true` |
|
|
| **Formatting** |
|
|
| `East.Float.printCommaSeperated(x: FloatExpr \| number, decimals: IntegerExpr \| bigint): StringExpr` | Format with comma separators | `East.Float.printCommaSeperated(1234.567, 2n)` → `"1,234.57"` |
|
|
| `East.Float.printCurrency(x: FloatExpr \| number): StringExpr` | Format as currency with $ and 2 decimals | `East.Float.printCurrency(1234.567)` → `"$1234.57"` |
|
|
| `East.Float.printFixed(x: FloatExpr \| number, decimals: IntegerExpr \| bigint): StringExpr` | Format with fixed decimal places | `East.Float.printFixed(3.1, 3n)` → `"3.100"` |
|
|
| `East.Float.printCompact(x: FloatExpr \| number): StringExpr` | Business units: `"21.5K"`, `"1.82M"`, `"314B"` | `East.Float.printCompact(1500000.0)` → `"1.5M"` |
|
|
| `East.Float.printPercentage(x: FloatExpr \| number, decimals: IntegerExpr \| bigint): StringExpr` | Format as percentage | `East.Float.printPercentage(0.452, 1n)` → `"45.2%"` |
|
|
|
|
---
|
|
|
|
### String
|
|
|
|
The String standard library provides error formatting utilities.
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `East.String.printError(message: StringExpr \| string, stack: ArrayExpr<StructType<{filename, line, column}>>): StringExpr` | Pretty-print error with stack trace | `East.String.printError(errorMsg, stackTrace)` |
|
|
|
|
|
|
---
|
|
|
|
### DateTime
|
|
|
|
The DateTime standard library provides construction and rounding utilities for date and time values.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const processDate = East.function([DateTimeType], StringType, ($, timestamp) => {
|
|
// Create from epoch milliseconds
|
|
const epoch = East.DateTime.fromEpochMilliseconds(1710498645123n);
|
|
|
|
// Create from components (year, month, day, hour, minute, second, millisecond)
|
|
const constructed = East.DateTime.fromComponents(2024n, 3n, 15n, 10n, 30n, 45n, 123n);
|
|
|
|
// Round timestamp to start of day
|
|
const dayStart = East.DateTime.roundDownDay(timestamp, 1n);
|
|
|
|
// Round to nearest hour
|
|
const nearestHour = East.DateTime.roundNearestHour(timestamp, 1n);
|
|
|
|
// Round to start of ISO week (Monday)
|
|
const weekStart = East.DateTime.roundDownWeek(timestamp, 1n);
|
|
|
|
$.return(East.str`Day: ${dayStart}, Hour: ${nearestHour}, Week: ${weekStart}`);
|
|
});
|
|
|
|
const compiled = East.compile(processDate, {});
|
|
const date = new Date("2024-03-15T14:30:45.123Z");
|
|
console.log(compiled(date));
|
|
// Output: Day: 2024-03-15T00:00:00.000, Hour: 2024-03-15T15:00:00.000, Week: 2024-03-11T00:00:00.000
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| **Construction** |
|
|
| `East.DateTime.fromEpochMilliseconds(ms: IntegerExpr \| bigint): DateTimeExpr` | Create from Unix epoch milliseconds | `East.DateTime.fromEpochMilliseconds(1640000000000n)` |
|
|
| `East.DateTime.fromComponents(y: IntegerExpr \| bigint, m: IntegerExpr \| bigint = 1n, d: IntegerExpr \| bigint = 1n, h: IntegerExpr \| bigint = 0n, min: IntegerExpr \| bigint = 0n, s: IntegerExpr \| bigint = 0n, ms: IntegerExpr \| bigint = 0n): DateTimeExpr` | Create from components | `East.DateTime.fromComponents(2025n, 1n, 15n)` |
|
|
| **Rounding - Seconds** |
|
|
| `East.DateTime.roundNearestSecond(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round to nearest multiple of seconds | `East.DateTime.roundNearestSecond(date, 30n)` |
|
|
| `East.DateTime.roundUpSecond(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round up to next multiple of seconds | `East.DateTime.roundUpSecond(date, 15n)` |
|
|
| `East.DateTime.roundDownSecond(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to previous multiple of seconds | `East.DateTime.roundDownSecond(date, 10n)` |
|
|
| **Rounding - Minutes** |
|
|
| `East.DateTime.roundNearestMinute(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round to nearest multiple of minutes | `East.DateTime.roundNearestMinute(date, 15n)` |
|
|
| `East.DateTime.roundUpMinute(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round up to next multiple of minutes | `East.DateTime.roundUpMinute(date, 5n)` |
|
|
| `East.DateTime.roundDownMinute(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to previous multiple of minutes | `East.DateTime.roundDownMinute(date, 30n)` |
|
|
| **Rounding - Hours** |
|
|
| `East.DateTime.roundNearestHour(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round to nearest multiple of hours | `East.DateTime.roundNearestHour(date, 1n)` |
|
|
| `East.DateTime.roundUpHour(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round up to next multiple of hours | `East.DateTime.roundUpHour(date, 6n)` |
|
|
| `East.DateTime.roundDownHour(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to previous multiple of hours | `East.DateTime.roundDownHour(date, 1n)` |
|
|
| **Rounding - Days** |
|
|
| `East.DateTime.roundNearestDay(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round to nearest multiple of days | `East.DateTime.roundNearestDay(date, 1n)` |
|
|
| `East.DateTime.roundUpDay(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round up to next multiple of days | `East.DateTime.roundUpDay(date, 7n)` |
|
|
| `East.DateTime.roundDownDay(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to previous multiple of days | `East.DateTime.roundDownDay(date, 1n)` |
|
|
| **Rounding - Weeks** |
|
|
| `East.DateTime.roundNearestWeek(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round to nearest Monday (ISO week start) | `East.DateTime.roundNearestWeek(date, 1n)` |
|
|
| `East.DateTime.roundUpWeek(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round up to next Monday (ISO week start) | `East.DateTime.roundUpWeek(date, 1n)` |
|
|
| `East.DateTime.roundDownWeek(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to previous Monday (ISO week start) | `East.DateTime.roundDownWeek(date, 1n)` |
|
|
| **Rounding - Months & Years** |
|
|
| `East.DateTime.roundDownMonth(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to start of month | `East.DateTime.roundDownMonth(date, 1n)` |
|
|
| `East.DateTime.roundDownYear(date: DateTimeExpr, step: IntegerExpr \| bigint): DateTimeExpr` | Round down to start of year | `East.DateTime.roundDownYear(date, 1n)` |
|
|
|
|
|
|
---
|
|
|
|
### Blob
|
|
|
|
The Blob standard library provides binary encoding utilities.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const serializeValue = East.function([IntegerType], BlobType, ($, value) => {
|
|
// Encode value to BEAST binary format (version 1 or 2)
|
|
const encoded = East.Blob.encodeBeast(value, 'v2');
|
|
// Alternative: const encoded = East.Blob.encodeBeast(value, 'v1');
|
|
|
|
$.return(encoded);
|
|
});
|
|
|
|
const compiled = East.compile(serializeValue, {});
|
|
const blob = compiled(42n);
|
|
console.log(blob); // Uint8Array containing BEAST-encoded 42n
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `East.Blob.encodeBeast(value: Expr, version: 'v1' \| 'v2' = 'v1'): BlobExpr` | Encode value to binary BEAST format (v1 or v2) | `East.Blob.encodeBeast(myValue, 'v2')` |
|
|
|
|
|
|
---
|
|
|
|
### Array
|
|
|
|
The Array standard library provides generation utilities for creating arrays.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const createSequences = East.function([], ArrayType(IntegerType), $ => {
|
|
// Generate integer range [0, 10) with step of 2
|
|
const range = East.Array.range(0n, 10n, 2n);
|
|
// Result: [0, 2, 4, 6, 8]
|
|
|
|
// Generate 11 equally-spaced floats from 0.0 to 1.0 (inclusive)
|
|
const linspace = East.Array.linspace(0.0, 1.0, 11n);
|
|
// Result: [0.0, 0.1, 0.2, ..., 0.9, 1.0]
|
|
|
|
// Generate array using function (index -> value)
|
|
const generated = East.Array.generate(5n, IntegerType, ($, i) => i.multiply(i));
|
|
// Result: [0, 1, 4, 9, 16]
|
|
|
|
$.return(range);
|
|
});
|
|
|
|
const compiled = East.compile(createSequences, {});
|
|
console.log(compiled()); // [0n, 2n, 4n, 6n, 8n]
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `East.Array.range(start: IntegerExpr \| bigint, end: IntegerExpr \| bigint, step: IntegerExpr \| bigint = 1n): ArrayExpr<IntegerType>` | Generate integer range [start, end) | `East.Array.range(0n, 10n, 2n)` |
|
|
| `East.Array.linspace(start: FloatExpr \| number, stop: FloatExpr \| number, size: IntegerExpr \| bigint): ArrayExpr<FloatType>` | Generate equally-spaced floats [start, stop] (inclusive) | `East.Array.linspace(0.0, 1.0, 11n)` |
|
|
| `East.Array.generate<T extends EastType>(size: IntegerExpr \| bigint, valueType: T, valueFn: FunctionType<[IntegerType], T>): ArrayExpr<T>` | Generate n elements using function from index | `East.Array.generate(10n, IntegerType, ($, i) => i.multiply(2n))` |
|
|
|
|
|
|
---
|
|
|
|
### Set
|
|
|
|
The Set standard library provides generation utilities for creating sets.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const createSet = East.function([], SetType(IntegerType), $ => {
|
|
// Generate set using function (index -> key)
|
|
const generated = East.Set.generate(5n, IntegerType, ($, i) => i.multiply(2n));
|
|
// Result: Set {0, 2, 4, 6, 8}
|
|
|
|
$.return(generated);
|
|
});
|
|
|
|
const compiled = East.compile(createSet, {});
|
|
console.log(compiled()); // Set {0n, 2n, 4n, 6n, 8n}
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `East.Set.generate<K extends DataType>(size: IntegerExpr \| bigint, keyType: K, keyFn: FunctionType<[IntegerType], K>, onConflict?: FunctionType<[K], K>): SetExpr<K>` | Generate set from function (errors on duplicates) | `East.Set.generate(10n, IntegerType, ($, i) => i)` |
|
|
|
|
|
|
---
|
|
|
|
### Dict
|
|
|
|
The Dict standard library provides generation utilities for creating dictionaries.
|
|
|
|
**Example:**
|
|
```typescript
|
|
const createDict = East.function([], DictType(IntegerType, IntegerType), $ => {
|
|
// Generate dict using functions (index -> key, index -> value)
|
|
const generated = East.Dict.generate(
|
|
5n,
|
|
IntegerType,
|
|
IntegerType,
|
|
($, i) => i, // key function
|
|
($, i) => i.multiply(10n) // value function
|
|
);
|
|
// Result: Map {0 => 0, 1 => 10, 2 => 20, 3 => 30, 4 => 40}
|
|
|
|
$.return(generated);
|
|
});
|
|
|
|
const compiled = East.compile(createDict, {});
|
|
console.log(compiled()); // Map {0n => 0n, 1n => 10n, 2n => 20n, 3n => 30n, 4n => 40n}
|
|
```
|
|
|
|
**Operations:**
|
|
| Signature | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `East.Dict.generate<K extends DataType, V extends EastType>(size: IntegerExpr \| bigint, keyType: K, valueType: V, keyFn: FunctionType<[IntegerType], K>, valueFn: FunctionType<[IntegerType], V>, onConflict?: FunctionType<[V, V, K], V>): DictExpr<K, V>` | Generate dict from functions (errors on duplicates) | `East.Dict.generate(10n, IntegerType, IntegerType, ($, i) => i, ($, i) => i.multiply(2n))` |
|
|
|
|
---
|
|
|
|
### Struct
|
|
|
|
Struct expressions currently have no standard library methods.
|
|
|
|
---
|
|
|
|
### Variant
|
|
|
|
Variant expressions currently have no standard library methods. |