Initial commit

2025-11-29 18:25:07 +08:00
commit 52ed309701
7 changed files with 1590 additions and 0 deletions
--- a/skills/east-development/STDLIB.md
+++ b/skills/east-development/STDLIB.md
@@ -0,0 +1,345 @@
+# 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.