{ "format": 1, "modules": [ { "path": "@std/archive.ms", "declarations": [ { "name": "ArchiveEntry", "doc": "One file or directory in an archive. Paths use forward slashes.", "kind": "record", "type": "ArchiveEntry", "fields": [ "path: String", "data: Bytes", "directory: Bool" ], "members": [ { "name": "data", "kind": "field", "signature": "data: Bytes", "doc": "File contents as immutable bytes; directory entries must carry empty bytes." }, { "name": "directory", "kind": "field", "signature": "directory: Bool", "doc": "True for a directory entry rather than a regular file; links and special files are not supported." }, { "name": "path", "kind": "field", "signature": "path: String", "doc": "Relative forward-slash path; pack/unpack reject traversal, absolute paths and duplicate normalized names. Unpack returns directory paths without a trailing slash." } ] }, { "name": "ArchiveError", "doc": "Errors returned when an archive cannot be read or written.", "kind": "alternative", "type": "ArchiveError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "Unsupported", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "An explicit implementation-supplied archive diagnostic; native validation uses specific cases." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Archive bytes, duplicate or file/directory-conflicting paths, extracted entry paths or encoded metadata are invalid." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A format argument's entry paths, directory payloads or supplied output/unpack limits are invalid." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Encoded bytes, entry count or unpacked per-entry/total bytes exceed a supplied budget." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The selected format or an encountered entry kind is unsupported, such as links or special files." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Original diagnostic text, returned unchanged by message()." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns original Failed text, or an archive-prefixed diagnostic for other cases.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "ArchiveFormat", "doc": "Selects a supported archive format without a runtime string spelling check.\nExisting pack/unpack format: String calls remain available.", "kind": "alternative", "type": "ArchiveFormat", "cases": [ "Zip", "Tar" ], "operations": [ "pack: fn(entries: List[ArchiveEntry], max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, ArchiveError]", "unpack: fn(data: Bytes, limits: Optional[ArchiveLimits] = ...)-\u003eResult[List[ArchiveEntry], ArchiveError]" ], "members": [ { "name": "Tar", "kind": "case", "signature": "case Tar", "doc": "TAR files and directories." }, { "name": "Zip", "kind": "case", "signature": "case Zip", "doc": "ZIP files and directories." }, { "name": "pack", "kind": "operation", "signature": "fn pack(entries: List[ArchiveEntry], max_bytes: Optional[Int] = none) -\u003e Result[Bytes, ArchiveError]:", "doc": "Packs entries with the same optional output budget and path validation as pack." }, { "name": "unpack", "kind": "operation", "signature": "fn unpack(data: Bytes, limits: Optional[ArchiveLimits] = none) -\u003e Result[List[ArchiveEntry], ArchiveError]:", "doc": "Unpacks in memory with the same entry/byte limits and domain errors as unpack." } ] }, { "name": "ArchiveLimits", "doc": "Optional limits applied while unpacking untrusted archive data.", "kind": "record", "type": "ArchiveLimits", "fields": [ "max_entries: Optional[Int]", "max_entry_bytes: Optional[Int]", "max_total_bytes: Optional[Int]" ], "members": [ { "name": "max_entries", "kind": "field", "signature": "max_entries: Optional[Int] = none", "doc": "Maximum unpacked entries, including directories; none adds no entry-count budget." }, { "name": "max_entry_bytes", "kind": "field", "signature": "max_entry_bytes: Optional[Int] = none", "doc": "Maximum unpacked bytes for each entry; zero admits only empty data." }, { "name": "max_total_bytes", "kind": "field", "signature": "max_total_bytes: Optional[Int] = none", "doc": "Cumulative unpacked file bytes across all entries; none adds no total-output budget." } ] }, { "name": "pack", "doc": "Encodes entries as exactly `zip` or `tar` bytes (case-sensitive); others return Unsupported. `max_bytes` bounds output when supplied.", "kind": "fn", "type": "fn(entries: List[ArchiveEntry], format: String, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, ArchiveError]" }, { "name": "unpack", "doc": "Decodes exactly `zip` or `tar` (case-sensitive); other formats return Unsupported.\nApplies each supplied entry and total-size limit.", "kind": "fn", "type": "fn(data: Bytes, format: String, limits: Optional[ArchiveLimits] = ...)-\u003eResult[List[ArchiveEntry], ArchiveError]" } ] }, { "path": "@std/bigint.ms", "declarations": [ { "name": "BigInt", "doc": "An arbitrary-precision signed integer with explicit arithmetic operations.", "kind": "native", "type": "BigInt", "operations": [ "add: fn(other: BigInt)-\u003eBigInt", "bit_and: fn(other: BigInt)-\u003eBigInt", "bit_or: fn(other: BigInt)-\u003eBigInt", "bit_xor: fn(other: BigInt)-\u003eBigInt", "compare: fn(other: BigInt)-\u003eInt", "divide: fn(other: BigInt)-\u003eResult[BigInt, BigIntError]", "multiply: fn(other: BigInt)-\u003eBigInt", "remainder: fn(other: BigInt)-\u003eResult[BigInt, BigIntError]", "subtract: fn(other: BigInt)-\u003eBigInt", "to_int: fn()-\u003eOptional[Int]", "to_string: fn(radix: Int)-\u003eString" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(other: BigInt) -\u003e BigInt:", "doc": "Returns the exact sum; arbitrary precision means it cannot overflow." }, { "name": "bit_and", "kind": "operation", "signature": "fn bit_and(other: BigInt) -\u003e BigInt:", "doc": "Returns the bitwise AND using infinite-width two's-complement semantics, so negative operands behave as if sign-extended." }, { "name": "bit_or", "kind": "operation", "signature": "fn bit_or(other: BigInt) -\u003e BigInt:", "doc": "Returns the bitwise OR using infinite-width two's-complement semantics, so negative operands behave as if sign-extended." }, { "name": "bit_xor", "kind": "operation", "signature": "fn bit_xor(other: BigInt) -\u003e BigInt:", "doc": "Returns the bitwise XOR using infinite-width two's-complement semantics, so negative operands behave as if sign-extended." }, { "name": "compare", "kind": "operation", "signature": "fn compare(other: BigInt) -\u003e Int:", "doc": "Returns -1 when this value is less than `other`, 0 when equal, and 1 when greater." }, { "name": "divide", "kind": "operation", "signature": "fn divide(other: BigInt) -\u003e Result[BigInt, BigIntError]:", "doc": "Returns the quotient truncated toward zero, so -7 divided by 2 is -3.\nA zero divisor returns InvalidInput." }, { "name": "multiply", "kind": "operation", "signature": "fn multiply(other: BigInt) -\u003e BigInt:", "doc": "Returns the exact product; it cannot overflow, though very large operands take proportionally longer." }, { "name": "remainder", "kind": "operation", "signature": "fn remainder(other: BigInt) -\u003e Result[BigInt, BigIntError]:", "doc": "Returns the remainder whose sign follows the dividend, so -7 remainder 2 is -1.\nA zero divisor returns InvalidInput." }, { "name": "subtract", "kind": "operation", "signature": "fn subtract(other: BigInt) -\u003e BigInt:", "doc": "Returns the exact difference `self - other`; it cannot overflow." }, { "name": "to_int", "kind": "operation", "signature": "fn to_int() -\u003e Optional[Int]:", "doc": "Returns the value as an Int when it fits in signed 64 bits, or none when it is outside that range." }, { "name": "to_string", "kind": "operation", "signature": "fn to_string(radix: Int) -\u003e String:", "doc": "Formats the value in a radix from 2 through 36 using lowercase digits and a leading `-` for negatives.\nA radix outside 2 through 36 is a programming fault." } ] }, { "name": "BigIntError", "doc": "Errors returned while parsing or converting arbitrary-precision integers.", "kind": "alternative", "type": "BigIntError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "The text is not an optionally signed integer made only of digits valid in the radix." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "The radix is outside 2 through 36, `max_digits` is negative, or a division or remainder has a zero divisor." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The text has more digits than `max_digits`; the sign is not counted, and this check precedes syntax validation." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `big integer: \u003creason\u003e`, such as `big integer: invalid input`, without echoing the input text.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "from_int", "doc": "Converts a machine-sized integer without loss.", "kind": "fn", "type": "fn(value: Int)-\u003eBigInt" }, { "name": "parse", "doc": "Parses a base-2 through base-36 integer. `max_digits` bounds work when supplied.", "kind": "fn", "type": "fn(text: String, radix: Int, max_digits: Optional[Int] = ...)-\u003eResult[BigInt, BigIntError]" } ] }, { "path": "@std/binary.ms", "declarations": [ { "name": "BinaryError", "doc": "Errors returned when a byte range or numeric representation is invalid.", "kind": "alternative", "type": "BinaryError", "cases": [ "InvalidInput", "OutOfRange" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Integer width is unsupported; the native codec accepts only 1, 2, 4 or 8 bytes." }, { "name": "OutOfRange", "kind": "case", "signature": "case OutOfRange", "doc": "A read crosses the byte buffer or a number cannot fit the requested signedness/width or result type." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a binary-prefixed diagnostic without echoing source bytes or numeric input.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "read_float", "doc": "Reads a 64-bit floating-point value (binary64, 8 bytes) at `offset` using the selected byte order.", "kind": "fn", "type": "fn(data: Bytes, offset: Int, little_endian: Bool)-\u003eResult[Float, BinaryError]" }, { "name": "read_integer", "doc": "Reads an integer of `width` bytes. Signed values use two's-complement encoding.", "kind": "fn", "type": "fn(data: Bytes, offset: Int, width: Int, signed: Bool, little_endian: Bool)-\u003eResult[Int, BinaryError]" }, { "name": "write_float", "doc": "Encodes a 64-bit floating-point value (binary64) as 8 bytes using the selected byte order.", "kind": "fn", "type": "fn(value: Float, little_endian: Bool)-\u003eBytes" }, { "name": "write_integer", "doc": "Encodes an integer into `width` bytes, returning an error when it does not fit.", "kind": "fn", "type": "fn(value: Int, width: Int, signed: Bool, little_endian: Bool)-\u003eResult[Bytes, BinaryError]" } ] }, { "path": "@std/bytes.ms", "declarations": [ { "name": "Bytes", "doc": "An immutable sequence of bytes. Indices and slice bounds are zero-based.", "kind": "native", "type": "Bytes", "operations": [ "at: fn(index: Int)-\u003eOptional[Int]", "clone: fn()-\u003eBytes", "concat: fn(other: Bytes)-\u003eBytes", "contains: fn(value: Bytes)-\u003eBool", "ends_with: fn(suffix: Bytes)-\u003eBool", "index_of: fn(value: Bytes)-\u003eOptional[Int]", "is_empty: fn()-\u003eBool", "last_index_of: fn(value: Bytes)-\u003eOptional[Int]", "length: fn()-\u003eInt", "reversed: fn()-\u003eBytes", "slice: fn(start: Int, end: Int)-\u003eResult[Bytes, CollectionError]", "split: fn(separator: Bytes, max_parts: Optional[Int] = ...)-\u003eList[Bytes]", "starts_with: fn(prefix: Bytes)-\u003eBool", "to_text: fn()-\u003eOptional[String]", "values: fn()-\u003eList[Int]", "with_value: fn(index: Int, value: Int)-\u003eBytes" ], "members": [ { "name": "at", "kind": "operation", "signature": "fn at(index: Int) -\u003e Optional[Int]:", "doc": "Returns an unsigned byte; negative indexes are relative to the end, and out-of-range indexes return `none`." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e Bytes:", "doc": "Copies byte storage without changing the receiver." }, { "name": "concat", "kind": "operation", "signature": "fn concat(other: Bytes) -\u003e Bytes:", "doc": "Returns concatenated bytes without changing either operand." }, { "name": "contains", "kind": "operation", "signature": "fn contains(value: Bytes) -\u003e Bool:", "doc": "Tests whether `value` occurs as a byte subsequence." }, { "name": "ends_with", "kind": "operation", "signature": "fn ends_with(suffix: Bytes) -\u003e Bool:", "doc": "Tests whether the receiver ends with these bytes." }, { "name": "index_of", "kind": "operation", "signature": "fn index_of(value: Bytes) -\u003e Optional[Int]:", "doc": "Returns the first matching byte offset or `none`; empty `value` matches at zero." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Tests whether the receiver contains no bytes." }, { "name": "last_index_of", "kind": "operation", "signature": "fn last_index_of(value: Bytes) -\u003e Optional[Int]:", "doc": "Returns the last matching byte offset or `none`; empty `value` matches at length()." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of bytes, not the number of Unicode characters." }, { "name": "reversed", "kind": "operation", "signature": "fn reversed() -\u003e Bytes:", "doc": "Returns a reversed copy without changing the receiver." }, { "name": "slice", "kind": "operation", "signature": "fn slice(start: Int, end: Int) -\u003e Result[Bytes, CollectionError]:", "doc": "Selects [start, end) in bytes; negative bounds are relative to the end.\nBounds outside 0 \u003c= start \u003c= end \u003c= length() return CollectionError.OutOfRange.\nThe immutable result may share storage with the receiver." }, { "name": "split", "kind": "operation", "signature": "fn split(separator: Bytes, max_parts: Optional[Int] = none) -\u003e List[Bytes]:", "doc": "Splits exact byte separators into a fresh list of immutable byte views.\nNonempty separators retain empty parts; empty data then yields one empty Bytes.\nOmitted/none max_parts is unlimited; zero returns no parts, negatives fault.\nA cap truncates parts; empty separator yields one Bytes per byte, no parts for empty data." }, { "name": "starts_with", "kind": "operation", "signature": "fn starts_with(prefix: Bytes) -\u003e Bool:", "doc": "Tests whether the receiver begins with these bytes." }, { "name": "to_text", "kind": "operation", "signature": "fn to_text() -\u003e Optional[String]:", "doc": "Decodes valid UTF-8 as text, or returns `none` when the bytes are invalid." }, { "name": "values", "kind": "operation", "signature": "fn values() -\u003e List[Int]:", "doc": "Returns a fresh mutable list of unsigned byte values; changing it leaves the Bytes unchanged." }, { "name": "with_value", "kind": "operation", "signature": "fn with_value(index: Int, value: Int) -\u003e Bytes:", "doc": "Returns a copy with one byte replaced; negative indexes are relative to the end.\nAn out-of-range index or a value outside 0 through 255 faults." } ] }, { "name": "BytesBuilder", "doc": "Builds a byte sequence efficiently before freezing it into an immutable value.", "kind": "native", "type": "BytesBuilder", "operations": [ "append: fn(value: Int)-\u003eUnit", "concat: fn(values: Bytes)-\u003eUnit", "freeze: fn()-\u003eBytes" ], "members": [ { "name": "append", "kind": "operation", "signature": "fn append(value: Int) -\u003e Unit:", "doc": "Appends one unsigned byte; values outside 0 through 255 or writes after freeze fault." }, { "name": "concat", "kind": "operation", "signature": "fn concat(values: Bytes) -\u003e Unit:", "doc": "Appends all supplied bytes in order; the input is unchanged, and a sealed builder faults." }, { "name": "freeze", "kind": "operation", "signature": "fn freeze() -\u003e Bytes:", "doc": "Seals the builder and returns its immutable bytes; repeated freeze returns the same value." } ] }, { "name": "values", "doc": "Returns a fresh mutable list of byte values in the range 0 through 255, like data.values().", "kind": "fn", "type": "fn(data: Bytes)-\u003eList[Int]" } ] }, { "path": "@std/cleanup.ms", "declarations": [ { "name": "Closeable", "doc": "A resource that can be closed. `with` closes a bound resource on every exit.", "kind": "interface", "type": "Closeable", "operations": [ "close: fn()-\u003eUnit" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Releases the implementation's resource state; with calls this on every scope exit.\nCleanup runs during return, expected errors, faults, and cancellation too." } ] } ] }, { "path": "@std/cli.ms", "declarations": [ { "name": "arguments", "doc": "Returns the host-supplied startup arguments, excluding the executable path.\nRepeated calls share the same mutable list; mutations do not rewrite native argv.", "kind": "fn", "type": "fn()-\u003eList[String]" }, { "name": "environment", "doc": "Returns the startup environment snapshot, not the live process environment.\nRepeated calls share the same mutable map; mutations do not call set_environment.", "kind": "fn", "type": "fn()-\u003eMap[String, String]" } ] }, { "path": "@std/collections.ms", "declarations": [ { "name": "CollectionError", "doc": "Errors returned when a collection factory exceeds its supplied item limit.", "kind": "alternative", "type": "CollectionError", "cases": [ "InvalidInput", "LimitExceeded", "OutOfRange" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A count, item budget, or step is invalid: `count` or `max_items` is negative, or `range` has a zero `step`." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The result would hold more items than `max_items`, or more than the runtime's ceiling of 268435456 (2^28) items when `max_items` is omitted." }, { "name": "OutOfRange", "kind": "case", "signature": "case OutOfRange", "doc": "A slice bound lies outside 0 \u003c= start \u003c= end \u003c= length() after negative bounds are resolved from the end." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `collection: \u003creason\u003e`, such as `collection: limit exceeded`, without echoing values.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "List", "doc": "An ordered mutable collection with indexing, iteration, and transformations.\nPrimitive backing stores Int and Float values at 64 bits, Bool values as bytes, and String references without an element box.\nGeneric forwarding retains the same List identity; clone and slice copy outer storage.", "kind": "native", "type": "List[T]", "type_parameters": [ "T" ], "operations": [ "append: fn(value: T)-\u003eList[T]", "at: fn(index: Int)-\u003eOptional[T]", "clone: fn()-\u003eList[T]", "concat: fn(other: List[T])-\u003eList[T]", "contains: fn(value: T)-\u003eBool", "copy_within: fn(target: Int, start: Int, end: Int)-\u003eList[T]", "count: fn(predicate: fn(value: T)-\u003eBool)-\u003eInt", "distinct: fn()-\u003eList[T]", "drop: fn(count: Int)-\u003eList[T]", "entries: fn()-\u003eList[ListEntry[T]]", "every: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "fill: fn(value: T, start: Int, end: Int)-\u003eList[T]", "filter: fn(predicate: fn(value: T)-\u003eBool)-\u003eList[T]", "find: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "find_index: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[Int]", "find_last: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "find_last_index: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[Int]", "first: fn()-\u003eOptional[T]", "flat_map[U]: fn(transform: fn(value: T)-\u003eList[U])-\u003eList[U]", "fold[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "fold_right[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "for_each: fn(operation: fn(value: T)-\u003eUnit)-\u003eUnit", "group_by[K: Hashable]: fn(key: fn(value: T)-\u003eK)-\u003eMap[K, List[T]]", "index_of: fn(value: T)-\u003eOptional[Int]", "insert: fn(index: Int, value: T)-\u003eList[T]", "is_empty: fn()-\u003eBool", "join: fn(separator: String)-\u003eString", "keys: fn()-\u003eList[Int]", "last: fn()-\u003eOptional[T]", "last_index_of: fn(value: T)-\u003eOptional[Int]", "length: fn()-\u003eInt", "map[U]: fn(transform: fn(value: T)-\u003eU)-\u003eList[U]", "pop: fn()-\u003eOptional[T]", "prepend: fn(value: T)-\u003eList[T]", "remove: fn(index: Int)-\u003eList[T]", "reverse_in_place: fn()-\u003eList[T]", "reversed: fn()-\u003eList[T]", "set: fn(index: Int, value: T)-\u003eList[T]", "slice: fn(start: Int, end: Int)-\u003eResult[List[T], CollectionError]", "some: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "sorted: fn(compare: fn(left: T, right: T)-\u003eInt)-\u003eList[T]", "splice: fn(start: Int, delete_count: Int, replacement: List[T])-\u003eList[T]", "take: fn(count: Int)-\u003eList[T]", "to_set: fn()-\u003eSet[T]" ], "members": [ { "name": "append", "kind": "operation", "signature": "fn append(value: T) -\u003e List[T]:", "doc": "Adds `value` at the end in place and returns this same list." }, { "name": "at", "kind": "operation", "signature": "fn at(index: Int) -\u003e Optional[T]:", "doc": "Returns an element; negative indexes are relative to the end, and out-of-range indexes return none." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e List[T]:", "doc": "Returns a shallow copy with independent list storage." }, { "name": "concat", "kind": "operation", "signature": "fn concat(other: List[T]) -\u003e List[T]:", "doc": "Returns a new list holding this list's elements followed by `other`; neither operand is changed." }, { "name": "contains", "kind": "operation", "signature": "fn contains(value: T) -\u003e Bool:", "doc": "Reports whether any element equals `value`, using the element type's Equal implementation; an empty list returns false." }, { "name": "copy_within", "kind": "operation", "signature": "fn copy_within(target: Int, start: Int, end: Int) -\u003e List[T]:", "doc": "Copies the elements in [start, end) to begin at index `target`, in place, and returns this list.\nThe list never grows: copying stops at the end of the list. Source bounds must satisfy 0 \u003c= start \u003c= end \u003c= length() and a target must be within 0 through length(); otherwise the call faults." }, { "name": "count", "kind": "operation", "signature": "fn count(predicate: fn(value: T) -\u003e Bool) -\u003e Int:", "doc": "Counts values satisfying the predicate, calling it once per element in order." }, { "name": "distinct", "kind": "operation", "signature": "fn distinct() -\u003e List[T]:", "doc": "Returns a new shallow List keeping each first equal element in order; elements require Equal." }, { "name": "drop", "kind": "operation", "signature": "fn drop(count: Int) -\u003e List[T]:", "doc": "Copies the remainder after min(count, length) into fresh shallow List storage.\nLeaves the receiver unchanged; negative count is a programming fault." }, { "name": "entries", "kind": "operation", "signature": "fn entries() -\u003e List[ListEntry[T]]:", "doc": "Returns a new list of `ListEntry` records pairing each zero-based index with its element, in order." }, { "name": "every", "kind": "operation", "signature": "fn every(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Returns true when every value satisfies the predicate; empty lists return true." }, { "name": "fill", "kind": "operation", "signature": "fn fill(value: T, start: Int, end: Int) -\u003e List[T]:", "doc": "Sets elements in [start, end) to `value` in place and returns this list.\nBounds must satisfy 0 \u003c= start \u003c= end \u003c= length(); negative or larger bounds fault rather than counting from the end, and an empty range changes nothing." }, { "name": "filter", "kind": "operation", "signature": "fn filter(predicate: fn(value: T) -\u003e Bool) -\u003e List[T]:", "doc": "Keeps matching values in their original order." }, { "name": "find", "kind": "operation", "signature": "fn find(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Returns the first element for which `predicate` is true, or none; later elements are not tested after a match." }, { "name": "find_index", "kind": "operation", "signature": "fn find_index(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[Int]:", "doc": "Returns the zero-based index of the first element for which `predicate` is true, or none." }, { "name": "find_last", "kind": "operation", "signature": "fn find_last(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Searches from the end and returns the last element for which `predicate` is true, or none." }, { "name": "find_last_index", "kind": "operation", "signature": "fn find_last_index(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[Int]:", "doc": "Searches from the end and returns the last matching zero-based index, or none." }, { "name": "first", "kind": "operation", "signature": "fn first() -\u003e Optional[T]:", "doc": "Returns the first element, or none when the list is empty." }, { "name": "flat_map[U]", "kind": "operation", "signature": "fn flat_map[U](transform: fn(value: T) -\u003e List[U]) -\u003e List[U]:", "doc": "Calls `transform` on each element in order and concatenates the returned lists into one new list; the receiver is unchanged." }, { "name": "fold[A]", "kind": "operation", "signature": "fn fold[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces values from left to right, starting with `initial`." }, { "name": "fold_right[A]", "kind": "operation", "signature": "fn fold_right[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces values from right to left, starting with `initial`." }, { "name": "for_each", "kind": "operation", "signature": "fn for_each(operation: fn(value: T) -\u003e Unit) -\u003e Unit:", "doc": "Calls operation(value:) over the initial backing slice and length; element writes can affect later calls, and append does not extend traversal." }, { "name": "group_by[K: Hashable]", "kind": "operation", "signature": "fn group_by[K: Hashable](key: fn(value: T) -\u003e K) -\u003e Map[K, List[T]]:", "doc": "Calls `key` once per element in order and returns a map from each distinct key to the elements that produced it.\nKeys appear in first-seen order and each group keeps the original element order." }, { "name": "index_of", "kind": "operation", "signature": "fn index_of(value: T) -\u003e Optional[Int]:", "doc": "Returns the first equal element's zero-based index, or none; elements require Equal." }, { "name": "insert", "kind": "operation", "signature": "fn insert(index: Int, value: T) -\u003e List[T]:", "doc": "Inserts value before index in place and returns this list; negative indexes count from the end.\nRequires -length() \u003c= index \u003c= length(); index length() appends, and invalid indexes fault." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether the list has no elements." }, { "name": "join", "kind": "operation", "signature": "fn join(separator: String) -\u003e String:", "doc": "Concatenates the strings with `separator` between neighbors; an empty list returns an empty string.\nAvailable only on List[String]." }, { "name": "keys", "kind": "operation", "signature": "fn keys() -\u003e List[Int]:", "doc": "Returns a new list of the zero-based indexes 0 through length() - 1." }, { "name": "last", "kind": "operation", "signature": "fn last() -\u003e Optional[T]:", "doc": "Returns the last element, or none when the list is empty." }, { "name": "last_index_of", "kind": "operation", "signature": "fn last_index_of(value: T) -\u003e Optional[Int]:", "doc": "Returns the last equal element's zero-based index, or none; elements require Equal." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of elements." }, { "name": "map[U]", "kind": "operation", "signature": "fn map[U](transform: fn(value: T) -\u003e U) -\u003e List[U]:", "doc": "Returns a new list holding `transform` applied to each element in order; the receiver is unchanged." }, { "name": "pop", "kind": "operation", "signature": "fn pop() -\u003e Optional[T]:", "doc": "Removes and returns the last element in place, or none for an empty list." }, { "name": "prepend", "kind": "operation", "signature": "fn prepend(value: T) -\u003e List[T]:", "doc": "Inserts `value` at index 0 in place, shifting existing elements one position later, and returns this same list." }, { "name": "remove", "kind": "operation", "signature": "fn remove(index: Int) -\u003e List[T]:", "doc": "Removes an element in place and returns this list; negative indexes count from the end.\nInvalid indexes fault.\nShifts the suffix without clearing prior values retained in spare backing capacity." }, { "name": "reverse_in_place", "kind": "operation", "signature": "fn reverse_in_place() -\u003e List[T]:", "doc": "Reverses this list in place and returns the same instance." }, { "name": "reversed", "kind": "operation", "signature": "fn reversed() -\u003e List[T]:", "doc": "Returns a reversed shallow copy with independent outer storage; nested references remain shared." }, { "name": "set", "kind": "operation", "signature": "fn set(index: Int, value: T) -\u003e List[T]:", "doc": "Replaces an element in place and returns this list; negative indexes count from the end.\nInvalid indexes fault." }, { "name": "slice", "kind": "operation", "signature": "fn slice(start: Int, end: Int) -\u003e Result[List[T], CollectionError]:", "doc": "Returns a new shallow List containing [start, end); outer storage is independent.\nNegative bounds are relative to the end; bounds outside 0 \u003c= start \u003c= end \u003c= length() return CollectionError.OutOfRange." }, { "name": "some", "kind": "operation", "signature": "fn some(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Returns true when at least one value satisfies the predicate." }, { "name": "sorted", "kind": "operation", "signature": "fn sorted(compare: fn(left: T, right: T) -\u003e Int) -\u003e List[T]:", "doc": "Returns a new list sorted by negative/zero/positive comparator results." }, { "name": "splice", "kind": "operation", "signature": "fn splice(start: Int, delete_count: Int, replacement: List[T]) -\u003e List[T]:", "doc": "Replaces delete_count elements starting at start, mutating and returning this List.\nRequires 0 \u003c= start \u003c= length and 0 \u003c= delete_count \u003c= length - start; invalid bounds fault without clamping.\nReplacement references stay shallow; using this same List as replacement stages its prior values.\nShrinking retains prior values in spare backing capacity, following captured Go slice traversal." }, { "name": "take", "kind": "operation", "signature": "fn take(count: Int) -\u003e List[T]:", "doc": "Copies the first min(count, length) elements into fresh shallow List storage.\nLeaves the receiver unchanged; negative count is a programming fault." }, { "name": "to_set", "kind": "operation", "signature": "fn to_set() -\u003e Set[T]:", "doc": "Returns a new set of the distinct elements, using Hashable equality; the first of equal elements is kept in insertion order." } ] }, { "name": "ListBuilder", "doc": "Appends values efficiently before freezing them into a list.", "kind": "native", "type": "ListBuilder[T]", "type_parameters": [ "T" ], "operations": [ "append: fn(value: T)-\u003eUnit", "freeze: fn()-\u003eList[T]" ], "members": [ { "name": "append", "kind": "operation", "signature": "fn append(value: T) -\u003e Unit:", "doc": "Adds `value` to the end of the shared builder and returns Unit.\nA frozen builder faults." }, { "name": "freeze", "kind": "operation", "signature": "fn freeze() -\u003e List[T]:", "doc": "Seals the builder and returns the accumulated list without copying it.\nLater `append` calls fault." } ] }, { "name": "ListEntry", "doc": "One list index and its corresponding value.", "kind": "record", "type": "ListEntry[T]", "type_parameters": [ "T" ], "fields": [ "index: Int", "value: T" ], "members": [ { "name": "index", "kind": "field", "signature": "index: Int", "doc": "Zero-based position of the element in the list that produced this entry." }, { "name": "value", "kind": "field", "signature": "value: T", "doc": "The element found at `index`." } ] }, { "name": "Map", "doc": "A mutable key-value collection. Keys use explicit `Hashable` value semantics.", "kind": "native", "type": "Map[T, U]", "type_parameters": [ "T: Hashable", "U" ], "operations": [ "add: fn(key: T, value: U)-\u003eMap[T, U]", "add_default: fn(key: T, value: U)-\u003eMap[T, U]", "add_default_from: fn(key: T, create: fn(key: T)-\u003eU)-\u003eMap[T, U]", "clear: fn()-\u003eMap[T, U]", "clone: fn()-\u003eMap[T, U]", "contains: fn(key: T)-\u003eBool", "entries: fn()-\u003eList[MapEntry[T, U]]", "every: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eBool", "filter: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eMap[T, U]", "find: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eOptional[MapEntry[T, U]]", "find_last: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eOptional[MapEntry[T, U]]", "fold[A]: fn(initial: A, step: fn(accumulator: A, key: T, value: U)-\u003eA)-\u003eA", "fold_right[A]: fn(initial: A, step: fn(accumulator: A, key: T, value: U)-\u003eA)-\u003eA", "for_each: fn(operation: fn(key: T, value: U)-\u003eUnit)-\u003eUnit", "get: fn(key: T)-\u003eOptional[U]", "get_or: fn(key: T, fallback: U)-\u003eU", "is_empty: fn()-\u003eBool", "keys: fn()-\u003eList[T]", "length: fn()-\u003eInt", "map[W]: fn(transform: fn(key: T, value: U)-\u003eW)-\u003eMap[T, W]", "map_keys[W: Hashable]: fn(transform: fn(key: T, value: U)-\u003eW)-\u003eMap[W, U]", "merge: fn(other: Map[T, U])-\u003eMap[T, U]", "remove: fn(key: T)-\u003eMap[T, U]", "some: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eBool", "values: fn()-\u003eList[U]" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(key: T, value: U) -\u003e Map[T, U]:", "doc": "Inserts or replaces a value and returns this map; replacement keeps the original key and insertion position." }, { "name": "add_default", "kind": "operation", "signature": "fn add_default(key: T, value: U) -\u003e Map[T, U]:", "doc": "Inserts a default only when the key is absent and returns this map.\nThe supplied value evaluates normally even when the key already exists." }, { "name": "add_default_from", "kind": "operation", "signature": "fn add_default_from(key: T, create: fn(key: T) -\u003e U) -\u003e Map[T, U]:", "doc": "Creates and inserts a default only when the key is absent, then returns this map.\nCalls create(key:) once for absence; an existing key leaves its value and position unchanged." }, { "name": "clear", "kind": "operation", "signature": "fn clear() -\u003e Map[T, U]:", "doc": "Removes every entry in place and returns this same map; aliases observe the empty map." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e Map[T, U]:", "doc": "Returns a shallow copy with independent map storage." }, { "name": "contains", "kind": "operation", "signature": "fn contains(key: T) -\u003e Bool:", "doc": "Reports whether an equal key is present, using the key type's Hashable implementation." }, { "name": "entries", "kind": "operation", "signature": "fn entries() -\u003e List[MapEntry[T, U]]:", "doc": "Returns a new list of fresh `MapEntry` records in insertion order; keys and values keep their original references." }, { "name": "every", "kind": "operation", "signature": "fn every(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first nonmatching entry; empty maps return true." }, { "name": "filter", "kind": "operation", "signature": "fn filter(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Map[T, U]:", "doc": "Copies matching entries in insertion order, retaining payload references.\nCallbacks traverse a snapshot even when they mutate the receiver." }, { "name": "find", "kind": "operation", "signature": "fn find(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Optional[MapEntry[T, U]]:", "doc": "Returns the first matching entry as a fresh record with shallow references." }, { "name": "find_last", "kind": "operation", "signature": "fn find_last(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Optional[MapEntry[T, U]]:", "doc": "Searches a snapshot from the end, stopping at the last matching entry.\nReturns a fresh entry record retaining its original key/value references." }, { "name": "fold[A]", "kind": "operation", "signature": "fn fold[A](initial: A, step: fn(accumulator: A, key: T, value: U) -\u003e A) -\u003e A:", "doc": "Reduces an entry snapshot in insertion order, starting with initial." }, { "name": "fold_right[A]", "kind": "operation", "signature": "fn fold_right[A](initial: A, step: fn(accumulator: A, key: T, value: U) -\u003e A) -\u003e A:", "doc": "Reduces an entry snapshot in reverse insertion order, starting with initial." }, { "name": "for_each", "kind": "operation", "signature": "fn for_each(operation: fn(key: T, value: U) -\u003e Unit) -\u003e Unit:", "doc": "Calls operation(key:, value:) sequentially over an insertion-order membership snapshot." }, { "name": "get", "kind": "operation", "signature": "fn get(key: T) -\u003e Optional[U]:", "doc": "Returns the value stored for an equal key, or none when the key is absent." }, { "name": "get_or", "kind": "operation", "signature": "fn get_or(key: T, fallback: U) -\u003e U:", "doc": "Returns the stored value or an eagerly evaluated fallback without inserting." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether this map has no entries." }, { "name": "keys", "kind": "operation", "signature": "fn keys() -\u003e List[T]:", "doc": "Returns a new list of the keys in insertion order." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of entries." }, { "name": "map[W]", "kind": "operation", "signature": "fn map[W](transform: fn(key: T, value: U) -\u003e W) -\u003e Map[T, W]:", "doc": "Transforms values in snapshot insertion order, retaining original keys.\nReturns independent outer storage with shallow key and result references." }, { "name": "map_keys[W: Hashable]", "kind": "operation", "signature": "fn map_keys[W: Hashable](transform: fn(key: T, value: U) -\u003e W) -\u003e Map[W, U]:", "doc": "Transforms keys in snapshot insertion order, retaining value references.\nEqual outputs keep the first key/position and the last input value." }, { "name": "merge", "kind": "operation", "signature": "fn merge(other: Map[T, U]) -\u003e Map[T, U]:", "doc": "Copies every entry of `other` into this map in place and returns this map.\nExisting keys keep their position and key but take the value from `other`; new keys append in `other` order. `other` is unchanged." }, { "name": "remove", "kind": "operation", "signature": "fn remove(key: T) -\u003e Map[T, U]:", "doc": "Removes an equal key and returns this same Map; remaining entries retain insertion order.\nAn absent key leaves values and ordering unchanged; lookup uses the selected Equal/Hashable scope." }, { "name": "some", "kind": "operation", "signature": "fn some(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first matching entry; empty maps return false." }, { "name": "values", "kind": "operation", "signature": "fn values() -\u003e List[U]:", "doc": "Returns a new list of the values in insertion order." } ] }, { "name": "MapBuilder", "doc": "Adds entries efficiently before freezing them into a map.", "kind": "native", "type": "MapBuilder[T, U]", "type_parameters": [ "T: Hashable", "U" ], "operations": [ "add: fn(key: T, value: U)-\u003eUnit", "freeze: fn()-\u003eMap[T, U]" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(key: T, value: U) -\u003e Unit:", "doc": "Inserts or replaces an entry in the shared builder; returns Unit like all builder mutations.\nReplacement retains the original key and insertion position; a sealed builder faults." }, { "name": "freeze", "kind": "operation", "signature": "fn freeze() -\u003e Map[T, U]:", "doc": "Seals the builder and returns the accumulated map without copying it.\nLater `add` calls fault." } ] }, { "name": "MapEntry", "doc": "One key-value pair returned by `Map.entries`.", "kind": "record", "type": "MapEntry[T, U]", "type_parameters": [ "T: Hashable", "U" ], "fields": [ "key: T", "value: U" ], "members": [ { "name": "key", "kind": "field", "signature": "key: T", "doc": "The lookup identity of the pair; unique within its map under Hashable equality." }, { "name": "value", "kind": "field", "signature": "value: U", "doc": "The payload stored for `key`; the reference is shared with the map, not copied." } ] }, { "name": "Set", "doc": "A mutable collection of unique values using explicit `Hashable` value semantics.", "kind": "native", "type": "Set[T]", "type_parameters": [ "T: Hashable" ], "operations": [ "add: fn(value: T)-\u003eSet[T]", "clear: fn()-\u003eSet[T]", "clone: fn()-\u003eSet[T]", "contains: fn(value: T)-\u003eBool", "difference: fn(other: Set[T])-\u003eSet[T]", "entries: fn()-\u003eList[List[T]]", "every: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "filter: fn(predicate: fn(value: T)-\u003eBool)-\u003eSet[T]", "find: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "find_last: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "fold[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "fold_right[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "for_each: fn(operation: fn(value: T)-\u003eUnit)-\u003eUnit", "intersection: fn(other: Set[T])-\u003eSet[T]", "is_disjoint_from: fn(other: Set[T])-\u003eBool", "is_empty: fn()-\u003eBool", "is_subset_of: fn(other: Set[T])-\u003eBool", "is_superset_of: fn(other: Set[T])-\u003eBool", "length: fn()-\u003eInt", "map[U: Hashable]: fn(transform: fn(value: T)-\u003eU)-\u003eSet[U]", "remove: fn(value: T)-\u003eSet[T]", "some: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "symmetric_difference: fn(other: Set[T])-\u003eSet[T]", "union: fn(other: Set[T])-\u003eSet[T]", "values: fn()-\u003eList[T]" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(value: T) -\u003e Set[T]:", "doc": "Adds a value in place and returns this set; an equal value retains its original payload and position." }, { "name": "clear", "kind": "operation", "signature": "fn clear() -\u003e Set[T]:", "doc": "Removes all values in place and returns this set; aliases observe the empty set." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e Set[T]:", "doc": "Copies outer storage, retaining element references and insertion order." }, { "name": "contains", "kind": "operation", "signature": "fn contains(value: T) -\u003e Bool:", "doc": "Reports whether an equal value is present, using the element's Hashable implementation." }, { "name": "difference", "kind": "operation", "signature": "fn difference(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set of receiver values absent from right, preserving receiver insertion order." }, { "name": "entries", "kind": "operation", "signature": "fn entries() -\u003e List[List[T]]:", "doc": "Returns a new list of [value, value] lists in insertion order." }, { "name": "every", "kind": "operation", "signature": "fn every(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first nonmatching element; empty sets return true." }, { "name": "filter", "kind": "operation", "signature": "fn filter(predicate: fn(value: T) -\u003e Bool) -\u003e Set[T]:", "doc": "Copies matching elements in insertion order, retaining payload references.\nCallbacks traverse a snapshot even when they mutate the receiver." }, { "name": "find", "kind": "operation", "signature": "fn find(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Returns the original first matching element, or none." }, { "name": "find_last", "kind": "operation", "signature": "fn find_last(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Searches a snapshot from the end, returning the original last matching element." }, { "name": "fold[A]", "kind": "operation", "signature": "fn fold[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces an element snapshot in insertion order, starting with initial." }, { "name": "fold_right[A]", "kind": "operation", "signature": "fn fold_right[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces an element snapshot in reverse insertion order, starting with initial." }, { "name": "for_each", "kind": "operation", "signature": "fn for_each(operation: fn(value: T) -\u003e Unit) -\u003e Unit:", "doc": "Calls operation(value:) sequentially over an insertion-order membership snapshot." }, { "name": "intersection", "kind": "operation", "signature": "fn intersection(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set of receiver values also in right, preserving receiver insertion order." }, { "name": "is_disjoint_from", "kind": "operation", "signature": "fn is_disjoint_from(other: Set[T]) -\u003e Bool:", "doc": "Tests whether the operands have no common values." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether this set has no elements." }, { "name": "is_subset_of", "kind": "operation", "signature": "fn is_subset_of(other: Set[T]) -\u003e Bool:", "doc": "Tests whether every receiver value also occurs in right." }, { "name": "is_superset_of", "kind": "operation", "signature": "fn is_superset_of(other: Set[T]) -\u003e Bool:", "doc": "Tests whether every right value also occurs in the receiver." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of distinct values currently stored." }, { "name": "map[U: Hashable]", "kind": "operation", "signature": "fn map[U: Hashable](transform: fn(value: T) -\u003e U) -\u003e Set[U]:", "doc": "Transforms a snapshot into a fresh set, retaining the first equal result." }, { "name": "remove", "kind": "operation", "signature": "fn remove(value: T) -\u003e Set[T]:", "doc": "Removes an equal value in place and returns this set; an absent value leaves it unchanged." }, { "name": "some", "kind": "operation", "signature": "fn some(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first matching element; empty sets return false." }, { "name": "symmetric_difference", "kind": "operation", "signature": "fn symmetric_difference(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set of values in exactly one operand; leaves both operands unchanged." }, { "name": "union", "kind": "operation", "signature": "fn union(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set with receiver values followed by right-only values in insertion order." }, { "name": "values", "kind": "operation", "signature": "fn values() -\u003e List[T]:", "doc": "Returns a shallow list of values in insertion order." } ] }, { "name": "SetBuilder", "doc": "Adds unique values efficiently before freezing them into a set.", "kind": "native", "type": "SetBuilder[T]", "type_parameters": [ "T: Hashable" ], "operations": [ "add: fn(value: T)-\u003eUnit", "freeze: fn()-\u003eSet[T]" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(value: T) -\u003e Unit:", "doc": "Adds a value to the shared builder; returns Unit like all builder mutations.\nEqual values retain the first payload and position; a sealed builder faults." }, { "name": "freeze", "kind": "operation", "signature": "fn freeze() -\u003e Set[T]:", "doc": "Seals the builder and returns the accumulated set without copying it.\nLater `add` calls fault." } ] }, { "name": "filled", "doc": "Creates a list containing `value` repeated `count` times.", "kind": "fn", "type": "fn(value: T, count: Int, max_items: Optional[Int] = ...)-\u003eResult[List[T], CollectionError]", "type_parameters": [ "T" ] }, { "name": "map_from_entries", "doc": "Builds a map from entries. Later entries replace earlier values for duplicate keys.", "kind": "fn", "type": "fn(entries: List[MapEntry[K, V]])-\u003eMap[K, V]", "type_parameters": [ "K: Hashable", "V" ] }, { "name": "range", "doc": "Creates integers from `start` up to but excluding `end` using `step`.", "kind": "fn", "type": "fn(start: Int, end: Int, step: Int, max_items: Optional[Int] = ...)-\u003eResult[List[Int], CollectionError]" } ] }, { "path": "@std/compress.ms", "declarations": [ { "name": "CompressionError", "doc": "Errors returned when compressed data is unsupported, invalid, or exceeds a limit.", "kind": "alternative", "type": "CompressionError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "Unsupported", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "An explicit implementation-supplied compression diagnostic; native codecs use specific cases." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Compressed framing, checksum, payload or trailing data is invalid for the chosen format." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Compression level is outside 0..9, or a supplied encoded/decoded byte budget is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Encoded or decompressed output exceeds the supplied byte budget." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "A String selector is not exactly gzip, zlib or deflate; typed selectors avoid spelling errors." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Original diagnostic text, returned unchanged by message()." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns original Failed text, or a compression-prefixed diagnostic for other cases.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "CompressionFormat", "doc": "Selects a supported compression format; Deflate is raw DEFLATE without a wrapper.\nExisting compress/decompress format: String calls remain available.", "kind": "alternative", "type": "CompressionFormat", "cases": [ "Gzip", "Zlib", "Deflate" ], "operations": [ "compress: fn(data: Bytes, level: Int = ..., max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, CompressionError]", "decompress: fn(data: Bytes, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, CompressionError]" ], "members": [ { "name": "Deflate", "kind": "case", "signature": "case Deflate", "doc": "Raw DEFLATE without framing." }, { "name": "Gzip", "kind": "case", "signature": "case Gzip", "doc": "DEFLATE data wrapped in GZIP headers and a checksum trailer." }, { "name": "Zlib", "kind": "case", "signature": "case Zlib", "doc": "DEFLATE data with ZLIB header and Adler-32 checksum framing." }, { "name": "compress", "kind": "operation", "signature": "fn compress(data: Bytes, level: Int = 6, max_bytes: Optional[Int] = none) -\u003e Result[Bytes, CompressionError]:", "doc": "Compresses with level 6 by default; explicit levels remain 0..9 (0 stores data).\nUses the same optional output budget/domain errors as compress." }, { "name": "decompress", "kind": "operation", "signature": "fn decompress(data: Bytes, max_bytes: Optional[Int] = none) -\u003e Result[Bytes, CompressionError]:", "doc": "Decompresses with the same cumulative output limit and validation as decompress." } ] }, { "name": "compress", "doc": "Compresses using exactly `gzip`, `zlib`, or raw `deflate` (case-sensitive).\nOther formats return Unsupported; level defaults to 6 (balanced DEFLATE compression).\nExplicit levels must be 0..9 (0 stores data), else InvalidInput.\n`max_bytes` bounds the encoded output when supplied.", "kind": "fn", "type": "fn(data: Bytes, format: String, level: Int = ..., max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, CompressionError]" }, { "name": "decompress", "doc": "Decompresses exactly `gzip`, `zlib`, or raw `deflate` (case-sensitive); others return Unsupported.\nStops when the supplied output limit is reached.", "kind": "fn", "type": "fn(data: Bytes, format: String, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, CompressionError]" } ] }, { "path": "@std/crypto.ms", "declarations": [ { "name": "CryptoError", "doc": "Errors returned when cryptographic input is invalid or an algorithm is unavailable.", "kind": "alternative", "type": "CryptoError", "cases": [ "InvalidInput", "Unsupported", "AuthenticationFailed" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "AuthenticationFailed", "kind": "case", "signature": "case AuthenticationFailed", "doc": "AES-GCM authentication failed, including a wrong key, nonce, associated data or altered ciphertext." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Key/seed/nonce length, derivation iteration/count arguments or AES key size is invalid." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The HMAC String selector is not exactly sha256, sha384 or sha512." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a cryptography-prefixed diagnostic without exposing keys, plaintext or ciphertext.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "HashAlgorithm", "doc": "Selects a supported SHA-2 algorithm without a runtime string spelling check.\nExisting hash functions and hmac(algorithm: String) remain available.", "kind": "alternative", "type": "HashAlgorithm", "cases": [ "Sha256", "Sha384", "Sha512" ], "operations": [ "digest: fn(data: Bytes)-\u003eBytes", "hmac: fn(key: Bytes, data: Bytes)-\u003eResult[Bytes, CryptoError]" ], "members": [ { "name": "Sha256", "kind": "case", "signature": "case Sha256", "doc": "SHA-256, producing a 32-byte digest or HMAC." }, { "name": "Sha384", "kind": "case", "signature": "case Sha384", "doc": "SHA-384, producing a 48-byte digest or HMAC." }, { "name": "Sha512", "kind": "case", "signature": "case Sha512", "doc": "SHA-512, producing a 64-byte digest or HMAC." }, { "name": "digest", "kind": "operation", "signature": "fn digest(data: Bytes) -\u003e Bytes:", "doc": "Computes this algorithm's digest, checking cancellation between chunks." }, { "name": "hmac", "kind": "operation", "signature": "fn hmac(key: Bytes, data: Bytes) -\u003e Result[Bytes, CryptoError]:", "doc": "Computes HMAC with this algorithm and retains CryptoError results." } ] }, { "name": "constant_time_equal", "doc": "Compares byte strings without making the comparison time depend on their contents.", "kind": "fn", "type": "fn(left: Bytes, right: Bytes)-\u003eBool" }, { "name": "derive_key", "doc": "Derives a key with PBKDF2-HMAC-SHA-256 using the supplied iteration count and length.", "kind": "fn", "type": "fn(password: Bytes, salt: Bytes, iterations: Int, length: Int)-\u003eResult[Bytes, CryptoError]" }, { "name": "hmac", "doc": "Computes an HMAC using exactly `sha256`, `sha384`, or `sha512` (case-sensitive).\nOther algorithms return CryptoError.Unsupported.", "kind": "fn", "type": "fn(key: Bytes, data: Bytes, algorithm: String)-\u003eResult[Bytes, CryptoError]" }, { "name": "open", "doc": "Authenticates and decrypts a value produced by `seal` using AES-GCM.", "kind": "fn", "type": "fn(key: Bytes, nonce: Bytes, ciphertext: Bytes, associated_data: Bytes)-\u003eResult[Bytes, CryptoError]" }, { "name": "public_key", "doc": "Derives the Ed25519 public key corresponding to a 32-byte private seed.", "kind": "fn", "type": "fn(seed: Bytes)-\u003eResult[Bytes, CryptoError]" }, { "name": "seal", "doc": "Encrypts and authenticates plaintext with AES-GCM. The caller supplies a unique nonce.", "kind": "fn", "type": "fn(key: Bytes, nonce: Bytes, plaintext: Bytes, associated_data: Bytes)-\u003eResult[Bytes, CryptoError]" }, { "name": "sha256", "doc": "Returns the SHA-256 digest of the input.", "kind": "fn", "type": "fn(data: Bytes)-\u003eBytes" }, { "name": "sha384", "doc": "Returns the SHA-384 digest of the input.", "kind": "fn", "type": "fn(data: Bytes)-\u003eBytes" }, { "name": "sha512", "doc": "Returns the SHA-512 digest of the input.", "kind": "fn", "type": "fn(data: Bytes)-\u003eBytes" }, { "name": "sign", "doc": "Signs data with an Ed25519 private seed.", "kind": "fn", "type": "fn(seed: Bytes, data: Bytes)-\u003eResult[Bytes, CryptoError]" }, { "name": "verify", "doc": "Verifies an Ed25519 signature with a public key.", "kind": "fn", "type": "fn(key: Bytes, data: Bytes, signature: Bytes)-\u003eBool" } ] }, { "path": "@std/csv.ms", "declarations": [ { "name": "CsvError", "doc": "Errors returned for malformed CSV input or configured size limits.", "kind": "alternative", "type": "CsvError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Quoting or another CSV record syntax rule is violated by the input." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "The delimiter, line ending or a supplied row/cell/output budget is invalid." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Parsed row/cell counts or the encoded output exceed a supplied budget." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a CSV-prefixed diagnostic without exposing input cells or parser text.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "CsvOptions", "doc": "Delimiter and line ending used when parsing or writing CSV; defaults are comma and LF.", "kind": "record", "type": "CsvOptions", "fields": [ "delimiter: String", "line_ending: String" ], "members": [ { "name": "delimiter", "kind": "field", "signature": "delimiter: String = \",\"", "doc": "One non-NUL ASCII delimiter other than quote, CR or LF; defaults to comma." }, { "name": "line_ending", "kind": "field", "signature": "line_ending: String = \"\\n\"", "doc": "Row terminator for encoding, either LF or CRLF; defaults to LF." } ] }, { "name": "parse", "doc": "Parses CSV into rows of cells, using fresh default options when omitted.\nOptional row and cell limits bound large inputs.", "kind": "fn", "type": "fn(text: String, options: CsvOptions = ..., max_rows: Optional[Int] = ..., max_cells: Optional[Int] = ...)-\u003eResult[List[List[String]], CsvError]" }, { "name": "stringify", "doc": "Encodes rows as CSV with comma delimiters and LF endings by default.\nQuotes cells when required by the delimiter or line ending.", "kind": "fn", "type": "fn(rows: List[List[String]], options: CsvOptions = ..., max_bytes: Optional[Int] = ...)-\u003eResult[String, CsvError]" } ] }, { "path": "@std/decimal.ms", "declarations": [ { "name": "Decimal", "doc": "An exact decimal value. Conversions are explicit because binary floats may round.", "kind": "native", "type": "Decimal", "operations": [ "round: fn(places: Int, mode: Optional[RoundingMode] = ...)-\u003eResult[Decimal, NumberError]", "to_fixed: fn(digits: Int, mode: Optional[RoundingMode] = ...)-\u003eResult[String, NumberError]", "to_float: fn()-\u003eFloat", "truncate_to_int: fn()-\u003eOptional[Int]" ], "members": [ { "name": "round", "kind": "operation", "signature": "fn round(places: Int, mode: Optional[RoundingMode] = none) -\u003e Result[Decimal, NumberError]:", "doc": "Rounds exactly to a multiple of `10^-places`, without converting to Float.\nPlaces range from -6144 through 6176; negative places round tens, hundreds, etc.\nInvalid places return InvalidInput; an unrepresentable result returns OutOfRange.\nOmitted or `none` mode selects HalfEven. This does not preserve trailing zeros or change arithmetic." }, { "name": "to_fixed", "kind": "operation", "signature": "fn to_fixed(digits: Int, mode: Optional[RoundingMode] = none) -\u003e Result[String, NumberError]:", "doc": "Rounds exactly and prints plain decimal notation with exactly `digits` fractional digits.\nDigits range from 0 through 6176; invalid digits return InvalidInput.\nHalfEven is the default; rounded zero has no minus sign. Trailing zeros are retained." }, { "name": "to_float", "kind": "operation", "signature": "fn to_float() -\u003e Float:", "doc": "Converts to the nearest Float, which can lose precision because binary floats cannot represent most decimal fractions exactly.\nValues beyond the Float range convert to an infinity." }, { "name": "truncate_to_int", "kind": "operation", "signature": "fn truncate_to_int() -\u003e Optional[Int]:", "doc": "Discards the fractional part toward zero and returns the integer, so -2.9 gives -2.\nReturns none when the integer part does not fit in signed 64 bits." } ] }, { "name": "RoundingMode", "doc": "How a Decimal rounds to a multiple of the requested power of ten.", "kind": "alternative", "type": "RoundingMode", "cases": [ "HalfEven", "HalfAwayFromZero", "TowardZero", "Floor", "Ceil" ], "members": [ { "name": "Ceil", "kind": "case", "signature": "case Ceil", "doc": "Rounds toward positive infinity." }, { "name": "Floor", "kind": "case", "signature": "case Floor", "doc": "Rounds toward negative infinity." }, { "name": "HalfAwayFromZero", "kind": "case", "signature": "case HalfAwayFromZero", "doc": "Nearest value; an exact tie rounds away from zero." }, { "name": "HalfEven", "kind": "case", "signature": "case HalfEven", "doc": "Nearest value; an exact tie chooses the even coefficient." }, { "name": "TowardZero", "kind": "case", "signature": "case TowardZero", "doc": "Discards the fractional coefficient toward zero." } ] } ] }, { "path": "@std/encoding.ms", "declarations": [ { "name": "EncodingError", "doc": "Errors returned when encoded text is invalid or exceeds a supplied byte limit.", "kind": "alternative", "type": "EncodingError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Hexadecimal digits or strict padded Base64 syntax/characters are invalid." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A supplied decoded-output byte budget is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The decoded byte count exceeds the supplied output budget." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns an encoding-prefixed diagnostic without echoing the encoded input.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "base64_decode", "doc": "Decodes standard Base64 by default; set `url_safe: true` for the URL-safe alphabet.", "kind": "fn", "type": "fn(text: String, url_safe: Bool = ..., max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, EncodingError]" }, { "name": "base64_encode", "doc": "Encodes bytes as standard Base64 by default; set `url_safe: true` for URL-safe text.", "kind": "fn", "type": "fn(data: Bytes, url_safe: Bool = ...)-\u003eString" }, { "name": "hex_decode", "doc": "Decodes hexadecimal text. `max_bytes` bounds decoded output when supplied.", "kind": "fn", "type": "fn(text: String, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, EncodingError]" }, { "name": "hex_encode", "doc": "Encodes each byte as two lowercase hexadecimal digits.", "kind": "fn", "type": "fn(data: Bytes)-\u003eString" } ] }, { "path": "@std/equality.ms", "declarations": [ { "name": "Equal", "doc": "Equality and hashing are ordinary operation interfaces. Built-in data retains\nits value semantics; an explicit implementation selects domain identity.", "kind": "interface", "type": "Equal", "operations": [ "equals: fn(other: Equal)-\u003eBool" ], "members": [ { "name": "equals", "kind": "operation", "signature": "fn equals(other: Equal) -\u003e Bool", "doc": "Compares this value with another value in the same domain." } ] }, { "name": "Hashable", "doc": "A type with a stable hash consistent with its `Equal` implementation.", "kind": "interface", "type": "Hashable", "operations": [ "hash: fn()-\u003eInt" ], "members": [ { "name": "hash", "kind": "operation", "signature": "fn hash() -\u003e Int", "doc": "Returns a stable hash consistent with `equals` for the same value." } ] } ] }, { "path": "@std/errors.ms", "declarations": [ { "name": "Error", "doc": "A contract for expected failures that can provide a human-readable message.", "kind": "interface", "type": "Error", "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String", "doc": "Returns a human-readable description of this expected error." } ] }, { "name": "ErrorCategory", "doc": "Portable categories for shared standard error cases. Domain errors retain their types and payloads.", "kind": "alternative", "type": "ErrorCategory", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "NotFound", "AlreadyExists", "PermissionDenied", "Unsupported", "Closed", "Timeout", "Unavailable" ], "members": [ { "name": "AlreadyExists", "kind": "case", "signature": "case AlreadyExists", "doc": "A requested exclusive resource already exists." }, { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The resource has been closed." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Input data is malformed." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Caller input is invalid." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "An operation budget or implementation limit was exceeded." }, { "name": "NotFound", "kind": "case", "signature": "case NotFound", "doc": "A requested resource was not found." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "Host authority denied the operation." }, { "name": "Timeout", "kind": "case", "signature": "case Timeout", "doc": "A local operation or group deadline expired." }, { "name": "Unavailable", "kind": "case", "signature": "case Unavailable", "doc": "The service/resource is unavailable; this does not imply NotFound or PermissionDenied." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The requested operation is unsupported." } ] }, { "name": "MissingValue", "doc": "The error `Optional.ok_or()` returns when no cause is given. Its message names the source file and line of the call.", "kind": "alternative", "type": "MissingValue", "cases": [ "Missing(location: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Missing", "kind": "case", "signature": "case Missing(location: String)", "doc": "Records where the absent value was converted to an error." }, { "name": "Missing.location", "kind": "field", "signature": "location: String", "doc": "The calling source position, as `file:line`." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns \"missing value at\" followed by the recorded source position.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "TextError", "doc": "An error that carries only intentional text, for callers that have no domain error to return.", "kind": "alternative", "type": "TextError", "cases": [ "Text(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Text", "kind": "case", "signature": "case Text(message: String)", "doc": "Wraps the human-readable description returned by message()." }, { "name": "Text.message", "kind": "field", "signature": "message: String", "doc": "Description returned verbatim by message()." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the wrapped text verbatim.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "category", "doc": "Queries a shared category without changing or invoking the error.\nRecognized standard cases use their same-name category.\nCustom errors and domain-specific cases (including Failed, Full, OutputLimit, OutOfRange,\nAuthenticationFailed and wrapped LogError causes) return none. Messages are never parsed.", "kind": "fn", "type": "fn(cause: Error)-\u003eOptional[ErrorCategory]" } ] }, { "path": "@std/faults.ms", "declarations": [ { "name": "panic", "doc": "Raises a programming fault with the supplied message and stops the current operation.", "kind": "fn", "type": "fn(message: String)-\u003eNever" } ] }, { "path": "@std/fs.ms", "declarations": [ { "name": "CopyOptions", "doc": "Policies for recursive copies, including replacement, symlinks, and optional limits.", "kind": "record", "type": "CopyOptions", "fields": [ "recursive: Bool", "replace: Bool", "error_on_exists: Bool", "dereference: Bool", "preserve_timestamps: Bool", "verbatim_symlinks: Bool", "clone: String", "max_entries: Optional[Int]", "max_bytes: Optional[Int]" ], "members": [ { "name": "clone", "kind": "field", "signature": "clone: String", "doc": "Exactly `none`, `try`, or `force`; other strings return InvalidInput.\ntry falls back to byte copying; force requires a native clone operation." }, { "name": "dereference", "kind": "field", "signature": "dereference: Bool", "doc": "When true, symbolic links are followed and their targets copied; when false, links are recreated as links." }, { "name": "error_on_exists", "kind": "field", "signature": "error_on_exists: Bool", "doc": "When true and `replace` is false, an existing destination file returns AlreadyExists instead of being skipped silently." }, { "name": "max_bytes", "kind": "field", "signature": "max_bytes: Optional[Int] = none", "doc": "Most file bytes copied in total. Exceeding it returns LimitExceeded. none sets no limit." }, { "name": "max_entries", "kind": "field", "signature": "max_entries: Optional[Int] = none", "doc": "Most files, directories, and links visited, counting the root. Exceeding it returns LimitExceeded. none sets no limit." }, { "name": "preserve_timestamps", "kind": "field", "signature": "preserve_timestamps: Bool", "doc": "When true, copied files and directories keep the source's access and modification times." }, { "name": "recursive", "kind": "field", "signature": "recursive: Bool", "doc": "When true, directories are copied with their contents; when false, a directory source returns InvalidInput." }, { "name": "replace", "kind": "field", "signature": "replace: Bool", "doc": "When true, an existing destination file or link is replaced; when false, it is kept, or reported when `error_on_exists` is true." }, { "name": "verbatim_symlinks", "kind": "field", "signature": "verbatim_symlinks: Bool", "doc": "When true, a copied link keeps its target text unchanged. When false, a relative target is rewritten relative to the source directory so it still reaches the original file." } ] }, { "name": "Directory", "doc": "An open directory that yields one child per read and must be closed.", "kind": "interface", "type": "Directory", "operations": [ "close: fn()-\u003eUnit", "path: fn()-\u003eString", "read: fn()-\u003eResult[Optional[DirectoryEntry], FileSystemError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Releases the directory handle.\nSafe to call repeatedly; later reads return Closed." }, { "name": "path", "kind": "operation", "signature": "fn path() -\u003e String", "doc": "Returns the path this cursor was opened with." }, { "name": "read", "kind": "operation", "signature": "fn read() -\u003e Result[Optional[DirectoryEntry], FileSystemError]", "doc": "Returns the next child in native directory order, or none after the last one.\nThe order is not sorted." } ] }, { "name": "DirectoryEntry", "doc": "The name and kind flags for one child returned by a directory listing.", "kind": "record", "type": "DirectoryEntry", "fields": [ "name: String", "directory: Bool", "symlink: Bool" ], "members": [ { "name": "directory", "kind": "field", "signature": "directory: Bool", "doc": "True when the child is a directory; a symbolic link is reported by `symlink`, not as a directory." }, { "name": "name", "kind": "field", "signature": "name: String", "doc": "The child's file name only, without any directory part, in the host's spelling." }, { "name": "symlink", "kind": "field", "signature": "symlink: Bool", "doc": "True when the child itself is a symbolic link, whatever it points to." } ] }, { "name": "FileEvent", "doc": "One filesystem change and the affected path.", "kind": "record", "type": "FileEvent", "fields": [ "path: String", "kind: String" ], "members": [ { "name": "kind", "kind": "field", "signature": "kind: String", "doc": "Exactly `rename` (appearance/disappearance/rename) or `change` (contents/metadata)." }, { "name": "path", "kind": "field", "signature": "path: String", "doc": "Path of the affected entry, formed from the watched path plus any child components." } ] }, { "name": "FileHandle", "doc": "An open file supporting sequential and positional I/O.", "kind": "interface", "type": "FileHandle", "operations": [ "append_file: fn(data: Bytes)-\u003eResult[Unit, FileSystemError]", "chmod: fn(mode: Int)-\u003eResult[Unit, FileSystemError]", "chown: fn(uid: Int, gid: Int)-\u003eResult[Unit, FileSystemError]", "close: fn()-\u003eUnit", "data_sync: fn()-\u003eResult[Unit, FileSystemError]", "read: fn(max_bytes: Optional[Int] = ...)-\u003eResult[Optional[Bytes], FileSystemError]", "read_at: fn(offset: Int, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, FileSystemError]", "read_file: fn(max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, FileSystemError]", "read_lines: fn(max_bytes: Optional[Int] = ..., max_lines: Optional[Int] = ...)-\u003eResult[List[String], FileSystemError]", "read_vectors: fn(sizes: List[Int], offset: Int)-\u003eResult[List[Bytes], FileSystemError]", "reader: fn()-\u003eReadStream", "seek: fn(offset: Int, origin: Int)-\u003eResult[Int, FileSystemError]", "set_times: fn(accessed: Timestamp, modified: Timestamp)-\u003eResult[Unit, FileSystemError]", "stat: fn()-\u003eResult[FileInfo, FileSystemError]", "sync: fn()-\u003eResult[Unit, FileSystemError]", "truncate: fn(size: Int)-\u003eResult[Unit, FileSystemError]", "write: fn(data: Bytes)-\u003eResult[Unit, FileSystemError]", "write_at: fn(offset: Int, data: Bytes)-\u003eResult[Unit, FileSystemError]", "write_vectors: fn(buffers: List[Bytes], offset: Int)-\u003eResult[Unit, FileSystemError]", "writer: fn()-\u003eWriteStream" ], "members": [ { "name": "append_file", "kind": "operation", "signature": "fn append_file(data: Bytes) -\u003e Result[Unit, FileSystemError]", "doc": "Writes at the current position; appends only when the handle was opened in append mode." }, { "name": "chmod", "kind": "operation", "signature": "fn chmod(mode: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the permission bits of the open file to `mode` (0 through 4095)." }, { "name": "chown", "kind": "operation", "signature": "fn chown(uid: Int, gid: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the owner and group of the open file by numeric id; -1 leaves that id unchanged. Usually needs privilege." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Closes the file, interrupts calls in progress, and waits for them to stop.\nSafe to call repeatedly; later operations return Closed." }, { "name": "data_sync", "kind": "operation", "signature": "fn data_sync() -\u003e Result[Unit, FileSystemError]", "doc": "Flushes the file's data to stable storage, skipping metadata that is not needed to read it back where the host allows.\nHosts without a separate data sync perform a full sync." }, { "name": "read", "kind": "operation", "signature": "fn read(max_bytes: Optional[Int] = none) -\u003e Result[Optional[Bytes], FileSystemError]", "doc": "Returns a positive chunk (at most 64 KiB), or none at EOF; a supplied size must be positive." }, { "name": "read_at", "kind": "operation", "signature": "fn read_at(offset: Int, max_bytes: Optional[Int] = none) -\u003e Result[Bytes, FileSystemError]", "doc": "Reads at a nonnegative byte offset without moving the position; short/empty Bytes mark EOF." }, { "name": "read_file", "kind": "operation", "signature": "fn read_file(max_bytes: Optional[Int] = none) -\u003e Result[Bytes, FileSystemError]", "doc": "Reads remaining bytes from the current position; EOF returns empty Bytes." }, { "name": "read_lines", "kind": "operation", "signature": "fn read_lines(max_bytes: Optional[Int] = none, max_lines: Optional[Int] = none) -\u003e Result[List[String], FileSystemError]", "doc": "Reads from the current position to the end and returns the lines with their `\\n` or `\\r\\n` terminators removed.\nInvalid UTF-8 returns InvalidData, and more bytes than `max_bytes` or lines than `max_lines` returns LimitExceeded." }, { "name": "read_vectors", "kind": "operation", "signature": "fn read_vectors(sizes: List[Int], offset: Int) -\u003e Result[List[Bytes], FileSystemError]", "doc": "Reads consecutive buffers of the given `sizes` in bytes, each up to 65536 and all together up to 16 MiB, and returns the bytes obtained for each.\n`offset` -1 reads from the current position; other offsets read without moving it. A buffer is shorter than requested at end of file. A negative size or offset below -1 returns InvalidInput." }, { "name": "reader", "kind": "operation", "signature": "fn reader() -\u003e ReadStream", "doc": "Adapts this handle to IoError/Optional chunk reads; closing either view closes all aliases." }, { "name": "seek", "kind": "operation", "signature": "fn seek(offset: Int, origin: Int) -\u003e Result[Int, FileSystemError]", "doc": "Seeks in bytes with origin exactly 0 (start), 1 (current), or 2 (end).\nOther origins return InvalidInput; the OS validates the resulting offset." }, { "name": "set_times", "kind": "operation", "signature": "fn set_times(accessed: Timestamp, modified: Timestamp) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the access and modification times of the open file. Returns Unsupported on hosts without descriptor timestamps." }, { "name": "stat", "kind": "operation", "signature": "fn stat() -\u003e Result[FileInfo, FileSystemError]", "doc": "Returns metadata for the open file." }, { "name": "sync", "kind": "operation", "signature": "fn sync() -\u003e Result[Unit, FileSystemError]", "doc": "Flushes the file's data and metadata to stable storage." }, { "name": "truncate", "kind": "operation", "signature": "fn truncate(size: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the file length to `size` bytes, discarding the excess or extending with zero bytes. The current position is not moved.\nA negative size returns InvalidInput." }, { "name": "write", "kind": "operation", "signature": "fn write(data: Bytes) -\u003e Result[Unit, FileSystemError]", "doc": "Writes all bytes at the current position; errors can leave a prefix. Does not truncate or reposition this handle." }, { "name": "write_at", "kind": "operation", "signature": "fn write_at(offset: Int, data: Bytes) -\u003e Result[Unit, FileSystemError]", "doc": "Writes all bytes at a nonnegative offset without moving the position; errors can leave a prefix." }, { "name": "write_vectors", "kind": "operation", "signature": "fn write_vectors(buffers: List[Bytes], offset: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Writes every buffer; offset -1 uses the current position." }, { "name": "writer", "kind": "operation", "signature": "fn writer() -\u003e WriteStream", "doc": "Adapts complete writes to IoError/Unit; flush synchronizes the file." } ] }, { "name": "FileInfo", "doc": "File metadata, including portable fields and exact platform-specific numeric values.", "kind": "record", "type": "FileInfo", "fields": [ "name: String", "size: Int", "directory: Bool", "symlink: Bool", "modified: Timestamp", "accessed: Timestamp", "changed: Timestamp", "mode: Int", "permissions: Int", "created: Optional[Timestamp]", "block_size: Int", "blocks: Int", "rdev: Int", "fifo: Bool", "socket: Bool", "block_device: Bool", "char_device: Bool", "exact: Map[String, BigInt]", "regular: Bool", "device: Int", "inode: Int", "links: Int", "uid: Int", "gid: Int" ], "members": [ { "name": "accessed", "kind": "field", "signature": "accessed: Timestamp", "doc": "Time the file was last read; it falls back to `modified` where the host lacks access times." }, { "name": "block_device", "kind": "field", "signature": "block_device: Bool", "doc": "True for a block special device." }, { "name": "block_size", "kind": "field", "signature": "block_size: Int", "doc": "Preferred I/O block size in bytes; unavailable fields are zero." }, { "name": "blocks", "kind": "field", "signature": "blocks: Int", "doc": "Allocated 512-byte blocks on POSIX hosts; unavailable fields are zero." }, { "name": "changed", "kind": "field", "signature": "changed: Timestamp", "doc": "Time the file's metadata or contents last changed; it falls back to `modified` where the host lacks it." }, { "name": "char_device", "kind": "field", "signature": "char_device: Bool", "doc": "True for a character special device." }, { "name": "created", "kind": "field", "signature": "created: Optional[Timestamp]", "doc": "Birth time of the file, or none when the host or filesystem does not record it." }, { "name": "device", "kind": "field", "signature": "device: Int", "doc": "Id of the device that holds the file; with `inode` it identifies the file. 0 where unavailable." }, { "name": "directory", "kind": "field", "signature": "directory: Bool", "doc": "True when the entry is a directory." }, { "name": "exact", "kind": "field", "signature": "exact: Map[String, BigInt]", "doc": "Unbounded copies of the numeric fields `size`, `mode`, `device`, `inode`, `links`, `uid`, `gid`, `block_size`, `blocks`, and `rdev`, which cannot overflow, plus the times as nanoseconds since the Unix epoch under `accessed_ns`, `modified_ns`, `changed_ns`, and `created_ns`.\nUnavailable values are 0." }, { "name": "fifo", "kind": "field", "signature": "fifo: Bool", "doc": "True for a named pipe." }, { "name": "gid", "kind": "field", "signature": "gid: Int", "doc": "Numeric id of the owning group; 0 where unavailable." }, { "name": "inode", "kind": "field", "signature": "inode: Int", "doc": "The file's index number on its device; 0 where unavailable." }, { "name": "links", "kind": "field", "signature": "links: Int", "doc": "Number of hard links to the file; 0 where unavailable." }, { "name": "mode", "kind": "field", "signature": "mode: Int", "doc": "POSIX mode bits: the file-type bits such as 0100000 for a regular file, plus permission and setuid, setgid, and sticky bits." }, { "name": "modified", "kind": "field", "signature": "modified: Timestamp", "doc": "Time the file's contents were last changed." }, { "name": "name", "kind": "field", "signature": "name: String", "doc": "The final path component's file name only." }, { "name": "permissions", "kind": "field", "signature": "permissions: Int", "doc": "Only the permission, setuid, setgid, and sticky bits of `mode`, 0 through 4095." }, { "name": "rdev", "kind": "field", "signature": "rdev: Int", "doc": "Device id the entry represents when it is a device file, otherwise 0." }, { "name": "regular", "kind": "field", "signature": "regular: Bool", "doc": "True for an ordinary file, as opposed to a directory, link, or special file." }, { "name": "size", "kind": "field", "signature": "size: Int", "doc": "File length in bytes." }, { "name": "socket", "kind": "field", "signature": "socket: Bool", "doc": "True for a Unix domain socket file." }, { "name": "symlink", "kind": "field", "signature": "symlink: Bool", "doc": "True when the entry is itself a symbolic link, which only happens when links were not followed." }, { "name": "uid", "kind": "field", "signature": "uid: Int", "doc": "Numeric id of the owning user; 0 where unavailable." } ] }, { "name": "FileSystem", "doc": "Filesystem operations and resource factories for the current host.", "kind": "interface", "type": "FileSystem", "operations": [ "access: fn(path: String, mode: Int)-\u003eResult[Unit, FileSystemError]", "append_file: fn(path: String, data: Bytes)-\u003eResult[Unit, FileSystemError]", "canonicalize: fn(path: String)-\u003eResult[String, FileSystemError]", "chmod: fn(path: String, mode: Int)-\u003eResult[Unit, FileSystemError]", "chmod_link: fn(path: String, mode: Int)-\u003eResult[Unit, FileSystemError]", "chown: fn(path: String, uid: Int, gid: Int, follow_links: Bool)-\u003eResult[Unit, FileSystemError]", "copy: fn(source: String, destination: String, options: CopyOptions, filter: Optional[fn(source: String, destination: String)-\u003eBool])-\u003eResult[Unit, FileSystemError]", "copy_file: fn(source: String, destination: String, replace: Bool = ..., max_bytes: Optional[Int] = ...)-\u003eResult[Unit, FileSystemError]", "copy_tree: fn(source: String, destination: String, replace: Bool = ..., max_entries: Optional[Int] = ..., max_bytes: Optional[Int] = ...)-\u003eResult[Unit, FileSystemError]", "create_directory: fn(path: String, recursive: Bool = ...)-\u003eResult[Unit, FileSystemError]", "create_link: fn(path: String, target: String)-\u003eResult[Unit, FileSystemError]", "glob: fn(path: String, pattern: String, max_entries: Optional[Int] = ...)-\u003eResult[List[String], FileSystemError]", "glob_entries: fn(path: String, options: GlobOptions, exclude: Optional[fn(entry: PathEntry)-\u003eBool])-\u003eResult[List[PathEntry], FileSystemError]", "hard_link: fn(source: String, destination: String)-\u003eResult[Unit, FileSystemError]", "list: fn(path: String, max_entries: Optional[Int] = ...)-\u003eResult[List[DirectoryEntry], FileSystemError]", "open: fn(path: String, flags: String, mode: Int)-\u003eResult[FileHandle, FileSystemError]", "open_directory: fn(path: String)-\u003eResult[Directory, FileSystemError]", "open_flags: fn(path: String, flags: Int, mode: Int)-\u003eResult[FileHandle, FileSystemError]", "read_file: fn(path: String, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, FileSystemError]", "read_link: fn(path: String)-\u003eResult[String, FileSystemError]", "remove: fn(path: String, recursive: Bool = ...)-\u003eResult[Unit, FileSystemError]", "rename: fn(source: String, destination: String)-\u003eResult[Unit, FileSystemError]", "set_times: fn(path: String, accessed: Timestamp, modified: Timestamp, follow_links: Bool)-\u003eResult[Unit, FileSystemError]", "stat: fn(path: String, follow_links: Bool)-\u003eResult[FileInfo, FileSystemError]", "stat_filesystem: fn(path: String)-\u003eResult[FileSystemInfo, FileSystemError]", "temporary: fn(prefix: String)-\u003eResult[TemporaryDirectory, FileSystemError]", "temporary_directory: fn(prefix: String)-\u003eResult[String, FileSystemError]", "truncate: fn(path: String, size: Int)-\u003eResult[Unit, FileSystemError]", "watch: fn(path: String, recursive: Bool, interval: Duration, max_entries: Optional[Int] = ...)-\u003eResult[FileWatcher, FileSystemError]", "watch_native: fn(path: String, recursive: Bool, max_entries: Optional[Int] = ..., max_events: Optional[Int] = ..., overflow: String)-\u003eResult[FileWatcher, FileSystemError]", "write_file: fn(path: String, data: Bytes, replace: Bool = ...)-\u003eResult[Unit, FileSystemError]" ], "members": [ { "name": "access", "kind": "operation", "signature": "fn access(path: String, mode: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Checks access with mode 0..7: existence 0, read 4, write 2, execute 1, or combined bits.\nNative permissions and Windows access policy still apply." }, { "name": "append_file", "kind": "operation", "signature": "fn append_file(path: String, data: Bytes) -\u003e Result[Unit, FileSystemError]", "doc": "Appends `data` to the end of the file, creating it with mode 0600 when absent. Writes every byte or fails, possibly leaving a partial append." }, { "name": "canonicalize", "kind": "operation", "signature": "fn canonicalize(path: String) -\u003e Result[String, FileSystemError]", "doc": "Resolves symlinks and returns the canonical absolute path." }, { "name": "chmod", "kind": "operation", "signature": "fn chmod(path: String, mode: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Changes target permissions with mode 0..4095; follows a final symbolic link." }, { "name": "chmod_link", "kind": "operation", "signature": "fn chmod_link(path: String, mode: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Changes the link itself without following it; Unsupported on hosts lacking this operation." }, { "name": "chown", "kind": "operation", "signature": "fn chown(path: String, uid: Int, gid: Int, follow_links: Bool) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the owning user and group of `path` by numeric id; -1 leaves that id unchanged.\n`follow_links` chooses the link target (true) or the link itself (false). Usually needs privilege, and Windows returns Unsupported." }, { "name": "copy", "kind": "operation", "signature": "fn copy(source: String, destination: String, options: CopyOptions, filter: Optional[fn(source: String, destination: String) -\u003e Bool]) -\u003e Result[Unit, FileSystemError]", "doc": "Copies a file or tree according to the supplied replacement and size policies." }, { "name": "copy_file", "kind": "operation", "signature": "fn copy_file(source: String, destination: String, replace: Bool = false, max_bytes: Optional[Int] = none) -\u003e Result[Unit, FileSystemError]", "doc": "Copies one file; replace defaults to false, refusing an existing destination." }, { "name": "copy_tree", "kind": "operation", "signature": "fn copy_tree(source: String, destination: String, replace: Bool = false, max_entries: Optional[Int] = none, max_bytes: Optional[Int] = none) -\u003e Result[Unit, FileSystemError]", "doc": "Copies a tree; replace defaults to false, refusing existing destinations.\nEntry and byte limits remain separate and apply cumulatively across the copy." }, { "name": "create_directory", "kind": "operation", "signature": "fn create_directory(path: String, recursive: Bool = false) -\u003e Result[Unit, FileSystemError]", "doc": "Creates one directory; recursive defaults to false, requiring its parent to exist." }, { "name": "create_link", "kind": "operation", "signature": "fn create_link(path: String, target: String) -\u003e Result[Unit, FileSystemError]", "doc": "Creates a symbolic link at `path` pointing to `target`." }, { "name": "glob", "kind": "operation", "signature": "fn glob(path: String, pattern: String, max_entries: Optional[Int] = none) -\u003e Result[List[String], FileSystemError]", "doc": "Returns the sorted relative paths under `path` matching `pattern`, without following directory symlinks.\nA malformed pattern, or one over 4096 bytes, or a negative `max_entries` returns InvalidInput. Matches beyond `max_entries` return LimitExceeded." }, { "name": "glob_entries", "kind": "operation", "signature": "fn glob_entries(path: String, options: GlobOptions, exclude: Optional[fn(entry: PathEntry) -\u003e Bool]) -\u003e Result[List[PathEntry], FileSystemError]", "doc": "Returns entries matching the supplied include and exclude patterns." }, { "name": "hard_link", "kind": "operation", "signature": "fn hard_link(source: String, destination: String) -\u003e Result[Unit, FileSystemError]", "doc": "Creates `destination` as another name for the file at `source`.\nAn existing destination returns AlreadyExists; it must be on the same filesystem as `source`." }, { "name": "list", "kind": "operation", "signature": "fn list(path: String, max_entries: Optional[Int] = none) -\u003e Result[List[DirectoryEntry], FileSystemError]", "doc": "Lists a directory, optionally limiting the number of returned entries." }, { "name": "open", "kind": "operation", "signature": "fn open(path: String, flags: String, mode: Int) -\u003e Result[FileHandle, FileSystemError]", "doc": "Opens with exactly r, r+, w, wx, w+, wx+, a, ax, a+, or ax+; other strings return InvalidInput.\nMode is permission bits in 0..4095, applied on creation subject to umask/OS policy." }, { "name": "open_directory", "kind": "operation", "signature": "fn open_directory(path: String) -\u003e Result[Directory, FileSystemError]", "doc": "Opens `path` as a directory cursor that yields one child per `read` in native order; close it when done.\nA path that is not a directory returns InvalidInput." }, { "name": "open_flags", "kind": "operation", "signature": "fn open_flags(path: String, flags: Int, mode: Int) -\u003e Result[FileHandle, FileSystemError]", "doc": "Opens a path using host flag bits in 0..2147483647 and permission bits in 0..4095.\nUse fs.constants() on this host; unknown bits/combinations are left to the OS." }, { "name": "read_file", "kind": "operation", "signature": "fn read_file(path: String, max_bytes: Optional[Int] = none) -\u003e Result[Bytes, FileSystemError]", "doc": "Reads a file fully into memory. Supply `max_bytes` for untrusted or large files." }, { "name": "read_link", "kind": "operation", "signature": "fn read_link(path: String) -\u003e Result[String, FileSystemError]", "doc": "Returns the target text stored in the symbolic link at `path`, without resolving it.\nA path that is not a link returns InvalidInput." }, { "name": "remove", "kind": "operation", "signature": "fn remove(path: String, recursive: Bool = false) -\u003e Result[Unit, FileSystemError]", "doc": "Removes a file or empty directory; recursive defaults to false, retaining nonempty trees." }, { "name": "rename", "kind": "operation", "signature": "fn rename(source: String, destination: String) -\u003e Result[Unit, FileSystemError]", "doc": "Moves `source` to `destination` using the operating system's rename, applying its rules for replacing an existing destination.\nIt never falls back to copying, so a move across devices returns an error." }, { "name": "set_times", "kind": "operation", "signature": "fn set_times(path: String, accessed: Timestamp, modified: Timestamp, follow_links: Bool) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the access and modification times of `path`.\n`follow_links` chooses the link target (true) or the link itself (false); no-follow updates return Unsupported where the host lacks them, such as Windows." }, { "name": "stat", "kind": "operation", "signature": "fn stat(path: String, follow_links: Bool) -\u003e Result[FileInfo, FileSystemError]", "doc": "Returns metadata for `path`. `follow_links` true describes the link target and false describes the link itself." }, { "name": "stat_filesystem", "kind": "operation", "signature": "fn stat_filesystem(path: String) -\u003e Result[FileSystemInfo, FileSystemError]", "doc": "Returns capacity and free-space statistics for the filesystem containing `path`.\nHosts without the query return Unsupported." }, { "name": "temporary", "kind": "operation", "signature": "fn temporary(prefix: String) -\u003e Result[TemporaryDirectory, FileSystemError]", "doc": "Creates a new temp directory whose contents are removed by scoped close.\nPrefix has the same validation as temporary_directory; this does not query the temp root." }, { "name": "temporary_directory", "kind": "operation", "signature": "fn temporary_directory(prefix: String) -\u003e Result[String, FileSystemError]", "doc": "Creates a new directory under the host temp root; the caller must remove it.\nPrefix must be nonempty and contain no slash, backslash, or NUL." }, { "name": "truncate", "kind": "operation", "signature": "fn truncate(path: String, size: Int) -\u003e Result[Unit, FileSystemError]", "doc": "Sets the target size in bytes; follows a final symbolic link." }, { "name": "watch", "kind": "operation", "signature": "fn watch(path: String, recursive: Bool, interval: Duration, max_entries: Optional[Int] = none) -\u003e Result[FileWatcher, FileSystemError]", "doc": "Returns a polling watcher that compares snapshots of `path` every `interval`, which must be positive.\n`max_entries` bounds the tracked paths; exceeding it returns LimitExceeded. Transient changes between polls can be missed." }, { "name": "watch_native", "kind": "operation", "signature": "fn watch_native(path: String, recursive: Bool, max_entries: Optional[Int] = none, max_events: Optional[Int] = none, overflow: String) -\u003e Result[FileWatcher, FileSystemError]", "doc": "Watches native OS events; overflow is exactly `error` or `ignore` (case-sensitive).\nOther policies return InvalidInput. Limits bound tracked paths and queued events." }, { "name": "write_file", "kind": "operation", "signature": "fn write_file(path: String, data: Bytes, replace: Bool = false) -\u003e Result[Unit, FileSystemError]", "doc": "Creates a file exclusively; replace defaults to false, retaining an existing file." } ] }, { "name": "FileSystemError", "doc": "Errors returned by filesystem operations. `Failed` retains the host error text.", "kind": "alternative", "type": "FileSystemError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "NotFound", "AlreadyExists", "NotEmpty", "PermissionDenied", "Unsupported", "Closed", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "AlreadyExists", "kind": "case", "signature": "case AlreadyExists", "doc": "The destination exists and the operation refuses to replace it, such as exclusive creation with `replace: false`." }, { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The file, directory, or watcher was already closed." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "The host reported an unexpected failure not covered by another case." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "File content could not be interpreted, such as invalid UTF-8 text in `read_lines`." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A path is empty or holds NUL, an argument is outside its range (mode bits, offset, size, flags string, origin), the handle lacks the needed read or write mode, or the operation targets the wrong kind of entry." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "A byte, line, or entry budget such as `max_bytes` or `max_entries` was exceeded, rather than returning a truncated result." }, { "name": "NotEmpty", "kind": "case", "signature": "case NotEmpty", "doc": "Removal failed because the directory still contains entries." }, { "name": "NotFound", "kind": "case", "signature": "case NotFound", "doc": "The path, or a parent directory it needs, does not exist." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "The operating system refused access to the path or operation." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The host or filesystem cannot perform the operation, or a file name is not valid UTF-8." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name paths." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `filesystem: \u003creason\u003e`, such as `filesystem: file or directory not found`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "FileSystemInfo", "doc": "Capacity/free-space statistics: block_size is bytes, blocks/free/available are counts\nin those blocks, and files/files_free are native file-node counts (zero if unavailable).", "kind": "record", "type": "FileSystemInfo", "fields": [ "type_id: Int", "block_size: Int", "blocks: Int", "blocks_free: Int", "blocks_available: Int", "files: Int", "files_free: Int" ], "members": [ { "name": "block_size", "kind": "field", "signature": "block_size: Int", "doc": "Size in bytes of the blocks that `blocks`, `blocks_free`, and `blocks_available` count." }, { "name": "blocks", "kind": "field", "signature": "blocks: Int", "doc": "Total number of blocks in the filesystem." }, { "name": "blocks_available", "kind": "field", "signature": "blocks_available: Int", "doc": "Number of unused blocks available to unprivileged users." }, { "name": "blocks_free", "kind": "field", "signature": "blocks_free: Int", "doc": "Number of unused blocks, including space reserved for privileged users." }, { "name": "files", "kind": "field", "signature": "files: Int", "doc": "Total number of file nodes, such as inodes, the filesystem can hold; 0 where unavailable." }, { "name": "files_free", "kind": "field", "signature": "files_free: Int", "doc": "Number of unused file nodes; 0 where unavailable." }, { "name": "type_id", "kind": "field", "signature": "type_id: Int", "doc": "The host's numeric filesystem type code, such as the magic number reported by Linux; 0 where unavailable." } ] }, { "name": "FileWatcher", "doc": "A change stream returned by a filesystem watch operation.", "kind": "interface", "type": "FileWatcher", "operations": [ "close: fn()-\u003eUnit", "next: fn()-\u003eResult[List[FileEvent], FileSystemError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Stops the watcher, wakes a pending `next` with Closed, and waits for its worker to stop.\nSafe to call repeatedly." }, { "name": "next", "kind": "operation", "signature": "fn next() -\u003e Result[List[FileEvent], FileSystemError]", "doc": "Waits for filesystem activity and returns events. A native watcher returns one event per call; a polling watcher returns every difference seen after an interval.\nCancelling the waiting task unwinds it, and a closed watcher returns Closed. A native watcher that overflowed with policy `error` returns LimitExceeded." } ] }, { "name": "GlobOptions", "doc": "Include and exclude patterns and limits used by filesystem glob operations.", "kind": "record", "type": "GlobOptions", "fields": [ "patterns: List[String]", "exclude: List[String]", "follow_links: Bool", "max_entries: Optional[Int]", "max_results: Optional[Int]" ], "members": [ { "name": "exclude", "kind": "field", "signature": "exclude: List[String]", "doc": "Glob patterns for entries to skip; a match is neither returned nor searched further." }, { "name": "follow_links", "kind": "field", "signature": "follow_links: Bool", "doc": "When true, symbolic links to directories are traversed, with cycles detected; when false, links are reported but not entered." }, { "name": "max_entries", "kind": "field", "signature": "max_entries: Optional[Int] = none", "doc": "Most filesystem entries visited while searching. Exceeding it returns LimitExceeded. none sets no limit." }, { "name": "max_results", "kind": "field", "signature": "max_results: Optional[Int] = none", "doc": "Most distinct matches returned. Exceeding it returns LimitExceeded. none sets no limit." }, { "name": "patterns", "kind": "field", "signature": "patterns: List[String]", "doc": "Glob patterns to include; an entry that matches any of them is returned." } ] }, { "name": "PathEntry", "doc": "A matched path together with its filesystem entry metadata.", "kind": "record", "type": "PathEntry", "fields": [ "path: String", "entry: DirectoryEntry" ], "members": [ { "name": "entry", "kind": "field", "signature": "entry: DirectoryEntry", "doc": "The directory entry record for the match: name, directory flag, and symlink flag." }, { "name": "path", "kind": "field", "signature": "path: String", "doc": "The matched path relative to the glob root, using the host's separators." } ] }, { "name": "TemporaryDirectory", "doc": "A temporary directory whose contents are removed when it is closed.", "kind": "interface", "type": "TemporaryDirectory", "operations": [ "close: fn()-\u003eUnit", "path: fn()-\u003eString" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Removes the directory and everything inside it.\nSafe to call repeatedly." }, { "name": "path", "kind": "operation", "signature": "fn path() -\u003e String", "doc": "Returns the absolute path of the directory, created under the host's temporary root." } ] }, { "name": "constants", "doc": "Returns this host's filesystem flag, mode, and permission constants by name.\nNames and values vary by host; absent entries are not supported constants or portable enum cases.", "kind": "fn", "type": "fn()-\u003eMap[String, Int]" }, { "name": "filesystem", "doc": "Returns filesystem operations for the current host.", "kind": "fn", "type": "fn()-\u003eFileSystem" } ] }, { "path": "@std/html.ms", "declarations": [ { "name": "HtmlAttribute", "doc": "An HTML attribute, including its namespace and decoded value.", "kind": "record", "type": "HtmlAttribute", "fields": [ "name: String", "namespace: String", "value: String" ], "members": [ { "name": "name", "kind": "field", "signature": "name: String", "doc": "Local attribute name after native HTML parsing and normalization." }, { "name": "namespace", "kind": "field", "signature": "namespace: String", "doc": "Attribute namespace prefix, or empty text for an unqualified attribute." }, { "name": "value", "kind": "field", "signature": "value: String", "doc": "Decoded attribute contents, with character references resolved." } ] }, { "name": "HtmlError", "doc": "Errors returned for malformed HTML or parser resource limits.", "kind": "alternative", "type": "HtmlError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Input encoding or a native parser/tree conversion is invalid; HTML syntax can be recovered normally." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A supplied input-byte, tree-depth or node-count budget is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Input bytes or the normalized returned tree exceed a supplied budget." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns an HTML-prefixed diagnostic without echoing source markup.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "HtmlLimits", "doc": "Optional bounds for HTML input bytes, tree depth, and node count.", "kind": "record", "type": "HtmlLimits", "fields": [ "max_bytes: Optional[Int]", "max_depth: Optional[Int]", "max_nodes: Optional[Int]" ], "members": [ { "name": "max_bytes", "kind": "field", "signature": "max_bytes: Optional[Int] = none", "doc": "Maximum UTF-8 input bytes before parsing; none adds no input-size budget." }, { "name": "max_depth", "kind": "field", "signature": "max_depth: Optional[Int] = none", "doc": "Maximum normalized node depth; the document is depth zero and direct children depth one." }, { "name": "max_nodes", "kind": "field", "signature": "max_nodes: Optional[Int] = none", "doc": "Maximum returned nodes, including document/text/comment/doctype and implied element nodes." } ] }, { "name": "HtmlNode", "doc": "A parsed HTML document tree with document, element, text, comment, and doctype nodes.", "kind": "alternative", "type": "HtmlNode", "cases": [ "Document(children: List[HtmlNode])", "Element(tag: String, namespace: String, attributes: List[HtmlAttribute], children: List[HtmlNode])", "Text(text: String)", "Comment(text: String)", "Doctype(name: String, public_id: String, system_id: String)" ], "members": [ { "name": "Comment", "kind": "case", "signature": "case Comment(text: String)", "doc": "An HTML comment retained as a node rather than element text." }, { "name": "Doctype", "kind": "case", "signature": "case Doctype(name: String, public_id: String, system_id: String)", "doc": "A document-type declaration retained from the parsed HTML." }, { "name": "Document", "kind": "case", "signature": "case Document(children: List[HtmlNode])", "doc": "Root document node, including any elements implied by HTML tree normalization." }, { "name": "Element", "kind": "case", "signature": "case Element(tag: String, namespace: String, attributes: List[HtmlAttribute], children: List[HtmlNode])", "doc": "An element with normalized attributes and its ordered child nodes." }, { "name": "Text", "kind": "case", "signature": "case Text(text: String)", "doc": "Text node contents after HTML entity decoding and tree normalization." }, { "name": "Comment.text", "kind": "field", "signature": "text: String", "doc": "Comment contents without the opening and closing comment delimiters." }, { "name": "Doctype.name", "kind": "field", "signature": "name: String", "doc": "Doctype name supplied by the native HTML parser." }, { "name": "Doctype.public_id", "kind": "field", "signature": "public_id: String", "doc": "Public identifier, or empty text when no public identifier is present." }, { "name": "Doctype.system_id", "kind": "field", "signature": "system_id: String", "doc": "System identifier, or empty text when no system identifier is present." }, { "name": "Document.children", "kind": "field", "signature": "children: List[HtmlNode]", "doc": "Direct child nodes in normalized document order." }, { "name": "Element.attributes", "kind": "field", "signature": "attributes: List[HtmlAttribute]", "doc": "Attributes in parser order, with decoded values and namespace information." }, { "name": "Element.children", "kind": "field", "signature": "children: List[HtmlNode]", "doc": "Direct child nodes in normalized tree order; mutable list storage is retained." }, { "name": "Element.namespace", "kind": "field", "signature": "namespace: String", "doc": "Element namespace, such as svg/math, or empty text for ordinary HTML." }, { "name": "Element.tag", "kind": "field", "signature": "tag: String", "doc": "Local element tag name produced by the HTML parser." }, { "name": "Text.text", "kind": "field", "signature": "text: String", "doc": "Unicode text belonging to this node, without surrounding markup." } ] }, { "name": "escape", "doc": "Escapes text for insertion into an HTML text or quoted attribute context.", "kind": "fn", "type": "fn(text: String)-\u003eString" }, { "name": "parse", "doc": "Parses HTML into a normalized tree and applies the supplied resource limits.", "kind": "fn", "type": "fn(text: String, limits: Optional[HtmlLimits] = ...)-\u003eResult[HtmlNode, HtmlError]" }, { "name": "unescape", "doc": "Decodes HTML5 named and numeric character references in text context, once.\nRecognized references can omit semicolons; unrecognized text remains literal.\nDoes not parse markup or normalize text; invalid numeric scalars become U+FFFD.", "kind": "fn", "type": "fn(text: String)-\u003eString" } ] }, { "path": "@std/http.ms", "declarations": [ { "name": "ClientResponse", "doc": "Buffered response body with explicit common metadata access.", "kind": "record", "type": "ClientResponse", "fields": [ "head: HttpResponseMetadata", "body: Bytes" ], "operations": [ "metadata: fn()-\u003eHttpResponseMetadata" ], "members": [ { "name": "body", "kind": "field", "signature": "body: Bytes", "doc": "The complete response payload within the supplied byte bound." }, { "name": "head", "kind": "field", "signature": "head: HttpResponseMetadata", "doc": "Current mutable metadata; replacing head detaches existing metadata aliases." }, { "name": "metadata", "kind": "operation", "signature": "fn metadata() -\u003e HttpResponseMetadata:", "doc": "Returns current head without copying; record clone is shallow.\nClone headers explicitly when separate mutable membership is needed." } ] }, { "name": "HttpClient", "doc": "Reusable HTTP client with connection pooling and explicit response limits.\nOutbound headers retain separate values in their stored order.", "kind": "interface", "type": "HttpClient", "operations": [ "close: fn()-\u003eUnit", "request: fn(method: HttpMethod, url: String, headers: HttpHeaders, body: Bytes = ..., max_response_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[ResponseBody, HttpError]", "request_stream: fn(method: HttpMethod, url: String, headers: HttpHeaders, body: ReadStream, max_response_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[ResponseBody, HttpError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Cancels in-flight requests, closes open response bodies, and drops idle pooled connections.\nSafe to call repeatedly; later requests return Closed." }, { "name": "request", "kind": "operation", "signature": "fn request(method: HttpMethod, url: String, headers: HttpHeaders, body: Bytes = \"\".to_bytes(), max_response_bytes: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[ResponseBody, HttpError]", "doc": "Sends immutable Bytes and returns a scoped streaming response body." }, { "name": "request_stream", "kind": "operation", "signature": "fn request_stream(method: HttpMethod, url: String, headers: HttpHeaders, body: ReadStream, max_response_bytes: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[ResponseBody, HttpError]", "doc": "Borrows ReadStream upload data through the scoped response lifetime." } ] }, { "name": "HttpClientOptions", "doc": "Connection, redirect, cookie, decompression, and TLS settings for an HTTP client.", "kind": "record", "type": "HttpClientOptions", "fields": [ "max_redirects: Optional[Int]", "max_idle_connections: Optional[Int]", "max_header_bytes: Optional[Int]", "idle_timeout: Optional[Duration]", "decompress: Bool", "cookies: Bool", "tls: TlsOptions" ], "members": [ { "name": "cookies", "kind": "field", "signature": "cookies: Bool = false", "doc": "When true, the client keeps an in-memory cookie jar for its lifetime, respecting public-suffix boundaries; when false (the default), no cookies are stored or sent automatically." }, { "name": "decompress", "kind": "field", "signature": "decompress: Bool = false", "doc": "When true, gzip-encoded responses are decoded transparently, with `max_response_bytes` bounding the decoded size; when false (the default), bodies arrive exactly as sent." }, { "name": "idle_timeout", "kind": "field", "signature": "idle_timeout: Optional[Duration] = none", "doc": "How long an idle pooled connection is kept before it is closed. none never expires it, and a negative duration is rejected." }, { "name": "max_header_bytes", "kind": "field", "signature": "max_header_bytes: Optional[Int] = none", "doc": "Largest accepted size of a response header block, in bytes. Must be positive; none sets no cap." }, { "name": "max_idle_connections", "kind": "field", "signature": "max_idle_connections: Optional[Int] = none", "doc": "Number of idle connections kept for reuse. Must be nonnegative; none sets no explicit cap." }, { "name": "max_redirects", "kind": "field", "signature": "max_redirects: Optional[Int] = none", "doc": "Most redirects followed per request. 0 returns the redirect response itself, none sets no cap, and a negative count is rejected.\nRedirects that downgrade from HTTPS, leave the network's restrictions, or carry user info are refused." }, { "name": "tls", "kind": "field", "signature": "tls: TlsOptions = TlsOptions(\n server_name: \"\",\n roots_pem: \"\",\n certificate_pem: \"\",\n private_key_pem: \"\",\n alpn: [],\n require_client_certificate: false\n )", "doc": "TLS trust and client-certificate settings for `https` requests. The host name is taken from each URL, so `server_name` is ignored." } ] }, { "name": "HttpError", "doc": "Errors returned for invalid requests, transport failures, timeouts, and limits.", "kind": "alternative", "type": "HttpError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "PermissionDenied", "Closed", "Timeout", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The client or network was closed before or during the request." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "Transport, TLS, or protocol failure reported by the host, such as a refused connection or an exceeded redirect limit." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "The response headers are not valid UTF-8, so they cannot become Strings." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "The URL is not an `http` or `https` URL with a host, valid port, and no user info; a method, header name, or value is malformed or host-managed; or a limit or timeout is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "A buffered response body is larger than `max_response_bytes`." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "The network's restrictions disallow the host, a resolved address, or a redirect destination." }, { "name": "Timeout", "kind": "case", "signature": "case Timeout", "doc": "The request timeout elapsed before the response completed." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name addresses." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `HTTP: \u003creason\u003e`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "HttpExchange", "doc": "One streaming server exchange. Read or write incrementally and close when done.\nReceived headers are one shared mutable object; repeated values stay separate.", "kind": "interface", "type": "HttpExchange", "operations": [ "close: fn()-\u003eUnit", "headers: fn()-\u003eHttpHeaders", "method: fn()-\u003eHttpMethod", "path: fn()-\u003eString", "query: fn()-\u003eString", "read: fn(max_bytes: Optional[Int] = ...)-\u003eResult[Optional[Bytes], IoError]", "send_headers: fn(status: Int, headers: HttpHeaders)-\u003eResult[Unit, HttpError]", "upgrade: fn(allowed_origins: List[String], subprotocols: List[String], max_message_bytes: Optional[Int] = ...)-\u003eResult[WebSocket, WebSocketError]", "write: fn(data: Bytes)-\u003eResult[Unit, IoError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Ends the exchange, interrupting reads or writes in progress.\nLater operations return Closed." }, { "name": "headers", "kind": "operation", "signature": "fn headers() -\u003e HttpHeaders", "doc": "Returns the request headers as shared mutable fields with every repeated value retained." }, { "name": "method", "kind": "operation", "signature": "fn method() -\u003e HttpMethod", "doc": "Returns the request method, using the Custom case for extension tokens." }, { "name": "path", "kind": "operation", "signature": "fn path() -\u003e String", "doc": "Returns the percent-decoded request path with dot segments resolved.\nRequests with an encoded slash or NUL are rejected before the handler runs." }, { "name": "query", "kind": "operation", "signature": "fn query() -\u003e String", "doc": "Returns the raw query string without the leading `?`; it is empty when there is none." }, { "name": "read", "kind": "operation", "signature": "fn read(max_bytes: Optional[Int] = none) -\u003e Result[Optional[Bytes], IoError]", "doc": "Returns the next chunk of the request body, at most `max_bytes` and never more than 65536, or none at the end of the body.\nReading past `max_body_bytes` returns IoError.Failed, and a non-positive `max_bytes` returns InvalidInput." }, { "name": "send_headers", "kind": "operation", "signature": "fn send_headers(status: Int, headers: HttpHeaders) -\u003e Result[Unit, HttpError]", "doc": "Sends the status line and headers once, before any body is written.\nThe status must be 200 through 599, header names cannot be `Content-Length`, `Transfer-Encoding`, or `Connection`, and header bytes are bounded by `max_header_bytes`. A second call returns InvalidInput and a closed exchange returns Closed." }, { "name": "upgrade", "kind": "operation", "signature": "fn upgrade(allowed_origins: List[String], subprotocols: List[String], max_message_bytes: Optional[Int] = none) -\u003e Result[WebSocket, WebSocketError]", "doc": "Switches the connection to a WebSocket after checking the `Origin` header. Requests without an Origin are accepted; otherwise it must exactly match an entry of `allowed_origins`, or, when that list is empty, match the request's own scheme and host.\n`subprotocols` lists the protocols the server accepts, and `max_message_bytes` must be positive when given. An exchange that already sent headers or upgraded returns InvalidInput, and a request that is not a valid WebSocket upgrade returns Failed." }, { "name": "write", "kind": "operation", "signature": "fn write(data: Bytes) -\u003e Result[Unit, IoError]", "doc": "Writes one chunk of the response body and flushes it.\n`send_headers` must come first, and writing beyond `max_response_bytes` returns IoError.Failed. Responses to HEAD requests and with status 204 or 304 cannot have a body." } ] }, { "name": "HttpHeaders", "doc": "Mutable HTTP fields with ASCII case-insensitive names and separate byte values.\nNames keep first-insertion order and spelling; values keep append order.\nLookup shares list membership. Use clone() to separate mutable membership.", "kind": "native", "type": "HttpHeaders", "operations": [ "append: fn(name: String, value: Bytes)-\u003eResult[Unit, HttpError]", "clone: fn()-\u003eHttpHeaders", "names: fn()-\u003eList[String]", "remove: fn(name: String)-\u003eBool", "text: fn(name: String)-\u003eResult[Optional[List[String]], HttpError]", "values: fn(name: String)-\u003eOptional[List[Bytes]]" ], "members": [ { "name": "append", "kind": "operation", "signature": "fn append(name: String, value: Bytes) -\u003e Result[Unit, HttpError]:", "doc": "Appends raw bytes under a valid HTTP name; invalid names return InvalidInput.\nTransport operations additionally validate UTF-8, framing and field values." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e HttpHeaders:", "doc": "Copies name/list membership and shares immutable Bytes values." }, { "name": "names", "kind": "operation", "signature": "fn names() -\u003e List[String]:", "doc": "Returns first-inserted spellings in insertion order." }, { "name": "remove", "kind": "operation", "signature": "fn remove(name: String) -\u003e Bool:", "doc": "Removes a name; existing list aliases are detached from this header object." }, { "name": "text", "kind": "operation", "signature": "fn text(name: String) -\u003e Result[Optional[List[String]], HttpError]:", "doc": "Decodes every value; invalid UTF-8 returns InvalidData without partial success." }, { "name": "values", "kind": "operation", "signature": "fn values(name: String) -\u003e Optional[List[Bytes]]:", "doc": "Returns shared mutable membership, or none for an absent name." } ] }, { "name": "HttpMethod", "doc": "Known HTTP methods, plus extension tokens validated by outgoing operations.", "kind": "alternative", "type": "HttpMethod", "cases": [ "Get", "Head", "Post", "Put", "Patch", "Delete", "Connect", "Options", "Trace", "Custom(value: String)" ], "operations": [ "text: fn()-\u003eString" ], "members": [ { "name": "Connect", "kind": "case", "signature": "case Connect", "doc": "Establishes a tunnel to the request target." }, { "name": "Custom", "kind": "case", "signature": "case Custom(value: String)", "doc": "Carries an extension token; requests reject empty or malformed tokens." }, { "name": "Delete", "kind": "case", "signature": "case Delete", "doc": "Removes the selected representation." }, { "name": "Get", "kind": "case", "signature": "case Get", "doc": "Requests the selected representation." }, { "name": "Head", "kind": "case", "signature": "case Head", "doc": "Requests response metadata without a body." }, { "name": "Options", "kind": "case", "signature": "case Options", "doc": "Asks which communication options the target supports, without transferring a body." }, { "name": "Patch", "kind": "case", "signature": "case Patch", "doc": "Applies a partial modification." }, { "name": "Post", "kind": "case", "signature": "case Post", "doc": "Submits a representation for processing." }, { "name": "Put", "kind": "case", "signature": "case Put", "doc": "Replaces the selected representation." }, { "name": "Trace", "kind": "case", "signature": "case Trace", "doc": "Requests a diagnostic loopback." }, { "name": "Custom.value", "kind": "field", "signature": "value: String", "doc": "The method token; it must be a non-empty HTTP token such as PURGE." }, { "name": "text", "kind": "operation", "signature": "fn text() -\u003e String:", "doc": "Returns the method token; outgoing requests reject malformed Custom tokens." } ] }, { "name": "HttpRequest", "doc": "Buffered request accepted by the simple HTTP server handler.", "kind": "record", "type": "HttpRequest", "fields": [ "method: HttpMethod", "path: String", "query: String", "headers: HttpHeaders", "body: Bytes" ], "members": [ { "name": "body", "kind": "field", "signature": "body: Bytes", "doc": "The complete request body, at most `max_body_bytes` long." }, { "name": "headers", "kind": "field", "signature": "headers: HttpHeaders", "doc": "The request headers as mutable fields with every repeated value retained." }, { "name": "method", "kind": "field", "signature": "method: HttpMethod", "doc": "The request method, using the Custom case for extension tokens." }, { "name": "path", "kind": "field", "signature": "path: String", "doc": "The percent-decoded request path with dot segments resolved, so `/a/../b` arrives as `/b`." }, { "name": "query", "kind": "field", "signature": "query: String", "doc": "The raw query string without the leading `?`; empty when there is none." } ] }, { "name": "HttpResponse", "doc": "Buffered response returned by the simple HTTP server handler.", "kind": "record", "type": "HttpResponse", "fields": [ "status: Int", "headers: HttpHeaders", "body: Bytes" ], "members": [ { "name": "body", "kind": "field", "signature": "body: Bytes", "doc": "The response body bytes, which must not exceed `max_response_bytes`; the server sets the content length." }, { "name": "headers", "kind": "field", "signature": "headers: HttpHeaders", "doc": "The response headers to send; `Content-Length`, `Transfer-Encoding`, and `Connection` are rejected with a 500 error." }, { "name": "status", "kind": "field", "signature": "status: Int", "doc": "The HTTP status code, which must be 200 through 599; other values are answered with a 500 error." } ] }, { "name": "HttpResponseMetadata", "doc": "Response status and headers shared by buffered and streaming response access.", "kind": "record", "type": "HttpResponseMetadata", "fields": [ "status: Int", "headers: HttpHeaders" ], "members": [ { "name": "headers", "kind": "field", "signature": "headers: HttpHeaders", "doc": "The shared mutable fields, with every repeated value retained." }, { "name": "status", "kind": "field", "signature": "status: Int", "doc": "The received status; editing metadata leaves wire/body behavior unchanged." } ] }, { "name": "HttpServer", "doc": "A running HTTP server. Close it to stop accepting new requests.", "kind": "interface", "type": "HttpServer", "operations": [ "address: fn()-\u003eString", "close: fn()-\u003eUnit", "wait: fn()-\u003eResult[Unit, IoError]" ], "members": [ { "name": "address", "kind": "operation", "signature": "fn address() -\u003e String", "doc": "Returns the bound local address as `host:port` text, which reveals the port chosen when listening on port 0." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Stops accepting connections, waits up to the grace period for in-flight requests, then cancels the rest and waits for them.\nSafe to call repeatedly. A request handler calling close on its own server faults, and a shutdown error is raised as a fault." }, { "name": "wait", "kind": "operation", "signature": "fn wait() -\u003e Result[Unit, IoError]", "doc": "Blocks until the server stops. Returns Ok after a normal `close`, or IoError.Failed with the host's text if serving ended with an error.\nCancelling the waiting task stops the wait." } ] }, { "name": "HttpServerOptions", "doc": "Request and response limits, deadlines, graceful shutdown, and TLS server settings.", "kind": "record", "type": "HttpServerOptions", "fields": [ "max_requests: Optional[Int]", "max_body_bytes: Optional[Int]", "max_response_bytes: Optional[Int]", "max_header_bytes: Optional[Int]", "timeout: Optional[Duration]", "grace: Optional[Duration]", "tls: Optional[TlsOptions]" ], "members": [ { "name": "grace", "kind": "field", "signature": "grace: Optional[Duration] = none", "doc": "How long `close` waits for in-flight requests to finish before cancelling them. none waits without limit and 0 cancels immediately." }, { "name": "max_body_bytes", "kind": "field", "signature": "max_body_bytes: Optional[Int] = none", "doc": "Largest accepted request body, in bytes. Must be nonnegative; none sets no cap." }, { "name": "max_header_bytes", "kind": "field", "signature": "max_header_bytes: Optional[Int] = none", "doc": "Largest accepted request header block and largest response header block, in bytes. Must be positive; none sets no cap." }, { "name": "max_requests", "kind": "field", "signature": "max_requests: Optional[Int] = none", "doc": "Most requests handled at once; further requests are answered with 503. Must be positive; none sets no cap." }, { "name": "max_response_bytes", "kind": "field", "signature": "max_response_bytes: Optional[Int] = none", "doc": "Most response body bytes a handler may write, in bytes. Must be nonnegative; none sets no cap." }, { "name": "timeout", "kind": "field", "signature": "timeout: Optional[Duration] = none", "doc": "Per-request time budget covering reading the request, running the handler, and writing the response. none sets no deadline." }, { "name": "tls", "kind": "field", "signature": "tls: Optional[TlsOptions] = none", "doc": "Some(options) serves HTTPS and negotiates HTTP/2 or HTTP/1.1 through ALPN; none, the default, serves plain HTTP/1.1." } ] }, { "name": "ResponseBody", "doc": "Streaming response body returned by reusable HTTP client operations.\nMetadata remains available after close and shares one mutable header object.", "kind": "interface", "type": "ResponseBody", "operations": [ "close: fn()-\u003eUnit", "metadata: fn()-\u003eHttpResponseMetadata", "read: fn(max_bytes: Optional[Int] = ...)-\u003eResult[Optional[Bytes], IoError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Cancels the rest of the response and releases its connection.\nSafe to call repeatedly; reads afterwards return Closed. A fully read body lets the connection be reused." }, { "name": "metadata", "kind": "operation", "signature": "fn metadata() -\u003e HttpResponseMetadata", "doc": "Returns the response head (status and headers) without copying; it stays available after close." }, { "name": "read", "kind": "operation", "signature": "fn read(max_bytes: Optional[Int] = none) -\u003e Result[Optional[Bytes], IoError]", "doc": "Returns the next chunk of the response body, at most `max_bytes` and never more than 65536, or none at the end of the body.\nReading past the request's `max_response_bytes` returns IoError.Failed, and a non-positive `max_bytes` returns InvalidInput." } ] }, { "name": "headers", "doc": "Creates empty mutable headers. No header values are joined or comma-combined.", "kind": "fn", "type": "fn()-\u003eHttpHeaders" } ] }, { "path": "@std/io.ms", "declarations": [ { "name": "File", "doc": "A file-like byte stream that returns `none` at end of input.", "kind": "interface", "type": "File", "operations": [ "close: fn()-\u003eUnit", "read: fn(max_bytes: Optional[Int] = ...)-\u003eResult[Optional[Bytes], IoError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Releases the file resource; retained aliases do not extend its open lifetime." }, { "name": "read", "kind": "operation", "signature": "fn read(max_bytes: Optional[Int] = none) -\u003e Result[Optional[Bytes], IoError]", "doc": "Returns a byte chunk or none at EOF; max_bytes is a positive chunk size, not a total budget.\nOmission/none uses the native 64 KiB chunk; source implementations define their own buffering." } ] }, { "name": "Files", "doc": "Opens read-only file resources using the current host's default filesystem.\nNative open failures (including missing paths and permission denial) become IoError.Unavailable.", "kind": "interface", "type": "Files", "operations": [ "open: fn(path: String)-\u003eResult[File, IoError]" ], "members": [ { "name": "open", "kind": "operation", "signature": "fn open(path: String) -\u003e Result[File, IoError]", "doc": "Opens path for read-only access; native missing, denied, and other open failures become Unavailable." } ] }, { "name": "IoError", "doc": "Errors returned while reading, writing, or closing an I/O resource.", "kind": "alternative", "type": "IoError", "cases": [ "Closed", "InvalidInput", "Unavailable", "InvalidData", "LimitExceeded", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The stream or shared native handle was closed before the operation completed." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "A native or adapter failure outside the more specific I/O cases." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Read bytes are invalid for the requested decoding, such as malformed UTF-8 text." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "An explicit chunk size, byte limit, or handle mode is invalid for this operation." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "A supplied byte budget was exceeded; already consumed input may not be recoverable." }, { "name": "Unavailable", "kind": "case", "signature": "case Unavailable", "doc": "The native service could not open or provide the requested stream." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Original diagnostic text; message() returns it unchanged rather than redacting it." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns original Failed text, or an I/O-prefixed diagnostic for the other cases.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "ReadStream", "doc": "A readable byte stream. Each read returns a chunk or `none` at end of stream.", "kind": "interface", "type": "ReadStream", "operations": [ "close: fn()-\u003eUnit", "read: fn(max_bytes: Optional[Int] = ...)-\u003eResult[Optional[Bytes], IoError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Releases this implementation's read resource; ownership of underlying handles is implementation-defined." }, { "name": "read", "kind": "operation", "signature": "fn read(max_bytes: Optional[Int] = none) -\u003e Result[Optional[Bytes], IoError]", "doc": "Returns a chunk or none at EOF; a final nonempty chunk can precede EOF.\nA supplied positive max_bytes requests a chunk size; native omission/none uses 64 KiB." } ] }, { "name": "WriteStream", "doc": "A writable byte stream. Successful write accepts all bytes; failure may leave an external prefix.\nBuffering/flush depends on the implementation: native stdout/stderr are unbuffered (flush is a no-op),\nwhile FileHandle.writer().flush synchronizes the file. Success does not acknowledge peer processing.", "kind": "interface", "type": "WriteStream", "operations": [ "close: fn()-\u003eUnit", "flush: fn()-\u003eResult[Unit, IoError]", "write: fn(data: Bytes)-\u003eResult[Unit, IoError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Releases this implementation's write resource; close does not imply a successful flush." }, { "name": "flush", "kind": "operation", "signature": "fn flush() -\u003e Result[Unit, IoError]", "doc": "Completes implementation-specific buffering or synchronization; native stdout/stderr use a no-op.\nFile-handle writers synchronize the file, and failures retain IoError identity." }, { "name": "write", "kind": "operation", "signature": "fn write(data: Bytes) -\u003e Result[Unit, IoError]", "doc": "Accepts the complete input on success; a source implementation may buffer until flush." } ] }, { "name": "copy", "doc": "Copies bytes until end of input or the supplied byte limit; returns bytes copied.", "kind": "fn", "type": "fn(input: ReadStream, output: WriteStream, max_bytes: Optional[Int] = ...)-\u003eResult[Int, IoError]" }, { "name": "files", "doc": "Returns file operations for the current host.", "kind": "fn", "type": "fn()-\u003eFiles" }, { "name": "read_all", "doc": "Reads a stream completely into memory. Supply a limit for untrusted streams.", "kind": "fn", "type": "fn(input: ReadStream, max_bytes: Optional[Int] = ...)-\u003eResult[Bytes, IoError]" }, { "name": "read_line", "doc": "Reads one line, omitting its line ending; returns `none` at end of stream.", "kind": "fn", "type": "fn(input: ReadStream, max_bytes: Optional[Int] = ...)-\u003eResult[Optional[String], IoError]" }, { "name": "stderr", "doc": "Returns the process standard-error stream.", "kind": "fn", "type": "fn()-\u003eWriteStream" }, { "name": "stdin", "doc": "Returns the process standard-input stream.", "kind": "fn", "type": "fn()-\u003eReadStream" }, { "name": "stdout", "doc": "Returns the process standard-output stream.", "kind": "fn", "type": "fn()-\u003eWriteStream" } ] }, { "path": "@std/json.ms", "declarations": [ { "name": "JsonError", "doc": "Errors returned for malformed JSON or configured input and nesting limits.", "kind": "alternative", "type": "JsonError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "JSON syntax, Unicode escapes, duplicate keys, number text or a cyclic value is invalid." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "An explicit input, depth, value-count or output budget is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The input, nesting, value count or encoded output exceeds a supplied budget." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a JSON-prefixed diagnostic without echoing input text or number tokens.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "JsonLimits", "doc": "Optional bounds for JSON input bytes, nesting depth, and parsed values.", "kind": "record", "type": "JsonLimits", "fields": [ "max_bytes: Optional[Int]", "max_depth: Optional[Int]", "max_values: Optional[Int]" ], "members": [ { "name": "max_bytes", "kind": "field", "signature": "max_bytes: Optional[Int] = none", "doc": "Maximum UTF-8 input bytes before parsing; none adds no input-size budget." }, { "name": "max_depth", "kind": "field", "signature": "max_depth: Optional[Int] = none", "doc": "Maximum container nesting; a root scalar has depth zero, and a root container depth one." }, { "name": "max_values", "kind": "field", "signature": "max_values: Optional[Int] = none", "doc": "Maximum parsed containers and scalar values, excluding object keys; none adds no count budget." } ] }, { "name": "JsonValue", "doc": "A JSON value. Number text is retained to avoid losing precision during parsing.", "kind": "alternative", "type": "JsonValue", "cases": [ "Null", "BoolValue(value: Bool)", "NumberValue(text: String)", "StringValue(value: String)", "ArrayValue(values: List[JsonValue])", "ObjectValue(values: Map[String, JsonValue])" ], "members": [ { "name": "ArrayValue", "kind": "case", "signature": "case ArrayValue(values: List[JsonValue])", "doc": "An ordered JSON array whose mutable list can be updated before serialization." }, { "name": "BoolValue", "kind": "case", "signature": "case BoolValue(value: Bool)", "doc": "A JSON true or false value." }, { "name": "Null", "kind": "case", "signature": "case Null", "doc": "JSON null, represented without a payload value." }, { "name": "NumberValue", "kind": "case", "signature": "case NumberValue(text: String)", "doc": "An exact JSON number token; parsing does not coerce it into Float." }, { "name": "ObjectValue", "kind": "case", "signature": "case ObjectValue(values: Map[String, JsonValue])", "doc": "A JSON object retaining insertion order and rejecting duplicate keys during parsing." }, { "name": "StringValue", "kind": "case", "signature": "case StringValue(value: String)", "doc": "A decoded JSON string, with escapes resolved into Unicode text." }, { "name": "ArrayValue.values", "kind": "field", "signature": "values: List[JsonValue]", "doc": "Element values in source order; nested mutable payloads retain their references." }, { "name": "BoolValue.value", "kind": "field", "signature": "value: Bool", "doc": "The decoded boolean, without a textual representation requirement." }, { "name": "NumberValue.text", "kind": "field", "signature": "text: String", "doc": "Original numeric token text; stringify validates its JSON number syntax." }, { "name": "ObjectValue.values", "kind": "field", "signature": "values: Map[String, JsonValue]", "doc": "String-keyed members in insertion order; stringify reads their current values." }, { "name": "StringValue.value", "kind": "field", "signature": "value: String", "doc": "Decoded UTF-8 text, preserving scalar contents without normalization." } ] }, { "name": "parse", "doc": "Parses one JSON value and applies the supplied input, depth, and value limits.", "kind": "fn", "type": "fn(text: String, limits: Optional[JsonLimits] = ...)-\u003eResult[JsonValue, JsonError]" }, { "name": "stringify", "doc": "Serializes a JSON value. `max_bytes` bounds output when supplied.", "kind": "fn", "type": "fn(value: JsonValue, max_bytes: Optional[Int] = ...)-\u003eResult[String, JsonError]" } ] }, { "path": "@std/jsonstream.ms", "declarations": [ { "name": "JsonDecoder", "doc": "Decodes a sequence of JSON values from byte chunks of any size.\n\nThe decoder buffers only the value being read, so tokens, escapes, and UTF-8 scalars\nmay be split across chunks. Values may be separated by JSON whitespace or directly\nadjacent when they are strings, arrays, or objects, which covers JSON Lines and\nconcatenated JSON. Top-level numbers, `true`, `false`, and `null` end at whitespace\nor at `finish()`. The decoder never reads, closes, or owns a stream.", "kind": "interface", "type": "JsonDecoder", "operations": [ "feed: fn(chunk: Bytes)-\u003eResult[List[JsonValue], JsonError]", "finish: fn()-\u003eResult[List[JsonValue], JsonError]" ], "members": [ { "name": "feed", "kind": "operation", "signature": "fn feed(chunk: Bytes) -\u003e Result[List[JsonValue], JsonError]", "doc": "Adds a chunk and returns every value it completes, in order; the list is empty when\nthe chunk ends inside a value. An error discards values completed earlier in the same\nchunk, and the decoder stays failed and returns that error again. Returns `InvalidInput` after `finish()`." }, { "name": "finish", "kind": "operation", "signature": "fn finish() -\u003e Result[List[JsonValue], JsonError]", "doc": "Signals end of input and returns a final unterminated scalar, if any. Input that\nends inside a string, array, or object returns `InvalidData`. The decoder rejects\nlater calls with `InvalidInput`." } ] }, { "name": "decoder", "doc": "Creates a decoder. `limits` applies to each value separately: `max_bytes` counts the\nvalue's UTF-8 bytes, `max_depth` its nesting, and `max_values` its parsed values, and\nan exceeded limit returns `LimitExceeded`. Omit limits only for trusted input, because\nan unterminated value is otherwise buffered without bound. Negative limits return\n`InvalidInput`.", "kind": "fn", "type": "fn(limits: Optional[JsonLimits] = ...)-\u003eResult[JsonDecoder, JsonError]" } ] }, { "path": "@std/log.ms", "declarations": [ { "name": "LogError", "doc": "Errors returned while validating or writing a structured log record.", "kind": "alternative", "type": "LogError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "Closed", "Io(cause: IoError)", "FileSystem(cause: FileSystemError)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The native transport has closed, so an admitted write or flush cannot complete." }, { "name": "FileSystem", "kind": "case", "signature": "case FileSystem(cause: FileSystemError)", "doc": "Opening the owned file transport returned a filesystem error." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Structured fields cannot be encoded as valid JSON, including cyclic values." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "The selected record level or an explicit record-size budget is invalid." }, { "name": "Io", "kind": "case", "signature": "case Io(cause: IoError)", "doc": "A transport's underlying byte-stream operation returned its original I/O error." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The JSON record plus its terminating newline exceeds the supplied byte budget." }, { "name": "FileSystem.cause", "kind": "field", "signature": "cause: FileSystemError", "doc": "Original filesystem error retained from file acquisition." }, { "name": "Io.cause", "kind": "field", "signature": "cause: IoError", "doc": "Original stream error; its message and concrete case are preserved." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the preserved I/O/filesystem cause message, or a logging-prefixed diagnostic.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "LogLevel", "doc": "Severity levels accepted by a logger, ordered from Trace through Fatal.", "kind": "alternative", "type": "LogLevel", "cases": [ "Trace", "Debug", "Info", "Warn", "Error", "Fatal", "Silent" ], "members": [ { "name": "Debug", "kind": "case", "signature": "case Debug", "doc": "Development diagnostics, encoded with numeric level 20." }, { "name": "Error", "kind": "case", "signature": "case Error", "doc": "Failure records, encoded with numeric level 50." }, { "name": "Fatal", "kind": "case", "signature": "case Fatal", "doc": "Critical records at numeric level 60; logging does not terminate the process." }, { "name": "Info", "kind": "case", "signature": "case Info", "doc": "Ordinary operational records, encoded with numeric level 30; the default threshold." }, { "name": "Silent", "kind": "case", "signature": "case Silent", "doc": "Filtering threshold that disables records; passing it to log returns InvalidInput." }, { "name": "Trace", "kind": "case", "signature": "case Trace", "doc": "Most detailed records, encoded with numeric level 10." }, { "name": "Warn", "kind": "case", "signature": "case Warn", "doc": "Warning records, encoded with numeric level 40." } ] }, { "name": "Logger", "doc": "A structured logger with level filtering, bound fields, and pluggable transports.", "kind": "interface", "type": "Logger", "operations": [ "child: fn(bindings: Map[String, JsonValue])-\u003eLogger", "debug: fn(message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]", "enabled: fn(level: LogLevel)-\u003eBool", "error: fn(message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]", "fatal: fn(message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]", "flush: fn()-\u003eResult[Unit, LogError]", "info: fn(message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]", "level: fn()-\u003eLogLevel", "log: fn(level: LogLevel, message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]", "set_level: fn(level: LogLevel)-\u003eUnit", "trace: fn(message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]", "warn: fn(message: String, fields: Optional[Map[String, JsonValue]] = ...)-\u003eResult[Unit, LogError]" ], "members": [ { "name": "child", "kind": "operation", "signature": "fn child(bindings: Map[String, JsonValue]) -\u003e Logger", "doc": "Returns a logger that adds these fields to each record." }, { "name": "debug", "kind": "operation", "signature": "fn debug(message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Logs at Debug when enabled, with call fields overriding child bindings for duplicate keys." }, { "name": "enabled", "kind": "operation", "signature": "fn enabled(level: LogLevel) -\u003e Bool", "doc": "Tests the current filtering threshold; Silent is never enabled as a record level." }, { "name": "error", "kind": "operation", "signature": "fn error(message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Logs at Error when enabled; it records an expected diagnostic rather than raising a fault." }, { "name": "fatal", "kind": "operation", "signature": "fn fatal(message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Logs at Fatal when enabled; the caller remains responsible for process termination." }, { "name": "flush", "kind": "operation", "signature": "fn flush() -\u003e Result[Unit, LogError]", "doc": "Flushes the logger's transport." }, { "name": "info", "kind": "operation", "signature": "fn info(message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Logs at Info when enabled; reserved level, msg, and time fields remain controlled by the logger." }, { "name": "level", "kind": "operation", "signature": "fn level() -\u003e LogLevel", "doc": "Returns this logger's current threshold, independent of its parent or children." }, { "name": "log", "kind": "operation", "signature": "fn log(level: LogLevel, message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Writes a record at the selected level with optional JSON fields." }, { "name": "set_level", "kind": "operation", "signature": "fn set_level(level: LogLevel) -\u003e Unit", "doc": "Changes only this logger's threshold; existing child loggers retain their copied threshold." }, { "name": "trace", "kind": "operation", "signature": "fn trace(message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Logs at Trace when enabled; a filtered call returns ok without encoding or transport access." }, { "name": "warn", "kind": "operation", "signature": "fn warn(message: String, fields: Optional[Map[String, JsonValue]] = none) -\u003e Result[Unit, LogError]", "doc": "Logs at Warn when enabled, returning encoding, size-budget, or transport errors unchanged." } ] }, { "name": "Transport", "doc": "A destination that accepts encoded log records and can be flushed and closed.", "kind": "interface", "type": "Transport", "operations": [ "close: fn()-\u003eUnit", "flush: fn()-\u003eResult[Unit, LogError]", "write: fn(data: Bytes)-\u003eResult[Unit, LogError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Releases owned resources; native close cancels admitted operations and leaves borrowed streams open." }, { "name": "flush", "kind": "operation", "signature": "fn flush() -\u003e Result[Unit, LogError]", "doc": "Delegates flush to the destination; persistence and buffering depend on that destination." }, { "name": "write", "kind": "operation", "signature": "fn write(data: Bytes) -\u003e Result[Unit, LogError]", "doc": "Accepts encoded record bytes; native transports serialize writes and may return the original I/O cause.\nErrors can follow a partial external write, without rollback." } ] }, { "name": "create", "doc": "Creates a logger. Defaults to `Info`, no bound fields, timestamps enabled, and no record-size limit.", "kind": "fn", "type": "fn(transport: Transport, level: Optional[LogLevel] = ..., bindings: Optional[Map[String, JsonValue]] = ..., timestamp: Optional[Bool] = ..., max_bytes: Optional[Int] = ...)-\u003eResult[Logger, LogError]" }, { "name": "file_transport", "doc": "Appends log records to a file at `path`.", "kind": "fn", "type": "fn(path: String)-\u003eResult[Transport, LogError]" }, { "name": "stdout_transport", "doc": "Writes log records to the process standard-output stream.", "kind": "fn", "type": "fn()-\u003eTransport" }, { "name": "stream_transport", "doc": "Writes log records to an existing byte stream.", "kind": "fn", "type": "fn(output: WriteStream)-\u003eTransport" } ] }, { "path": "@std/math.ms", "declarations": [ { "name": "abs", "doc": "Returns the absolute value of a floating-point number.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "abs_int", "doc": "Returns the absolute value of an integer.", "kind": "fn", "type": "fn(value: Int)-\u003eInt" }, { "name": "acos", "doc": "Returns the inverse cosine in radians.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "asin", "doc": "Returns the inverse sine in radians.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "atan", "doc": "Returns the inverse tangent in radians.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "atan2", "doc": "Returns the angle in radians for `(x, y)`, preserving its quadrant.", "kind": "fn", "type": "fn(y: Float, x: Float)-\u003eFloat" }, { "name": "ceil", "doc": "Rounds upward to the nearest whole number.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "cos", "doc": "Returns the cosine of an angle in radians.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "cosh", "doc": "Returns the hyperbolic cosine.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "e", "doc": "Returns Euler's number, the base of natural logarithms.", "kind": "fn", "type": "fn()-\u003eFloat" }, { "name": "exp", "doc": "Returns e raised to `value`.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "floor", "doc": "Rounds downward to the nearest whole number.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "hypot", "doc": "Returns the length of the hypotenuse for sides `left` and `right`.", "kind": "fn", "type": "fn(left: Float, right: Float)-\u003eFloat" }, { "name": "log", "doc": "Returns the natural logarithm.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "log10", "doc": "Returns the base-10 logarithm.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "log2", "doc": "Returns the base-2 logarithm.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "max", "doc": "Returns the greater of two floating-point values.", "kind": "fn", "type": "fn(left: Float, right: Float)-\u003eFloat" }, { "name": "min", "doc": "Returns the lesser of two floating-point values.", "kind": "fn", "type": "fn(left: Float, right: Float)-\u003eFloat" }, { "name": "pi", "doc": "Returns π, the ratio of a circle's circumference to its diameter.", "kind": "fn", "type": "fn()-\u003eFloat" }, { "name": "pow", "doc": "Returns `base` raised to `exponent`.", "kind": "fn", "type": "fn(base: Float, exponent: Float)-\u003eFloat" }, { "name": "remainder", "doc": "Returns the floating-point remainder after division.", "kind": "fn", "type": "fn(left: Float, right: Float)-\u003eFloat" }, { "name": "round", "doc": "Rounds to the nearest whole number, with ties toward positive infinity.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "sin", "doc": "Returns the sine of an angle in radians.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "sinh", "doc": "Returns the hyperbolic sine.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "sqrt", "doc": "Returns the non-negative square root.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "tan", "doc": "Returns the tangent of an angle in radians.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "tanh", "doc": "Returns the hyperbolic tangent.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" }, { "name": "truncate", "doc": "Truncates a value toward zero.", "kind": "fn", "type": "fn(value: Float)-\u003eFloat" } ] }, { "path": "@std/net.ms", "declarations": [ { "name": "Cidr", "doc": "A validated, masked numeric CIDR range.", "kind": "native", "type": "Cidr", "operations": [ "text: fn()-\u003eString" ], "members": [ { "name": "text", "kind": "operation", "signature": "fn text() -\u003e String:", "doc": "Returns the canonical masked prefix without reparsing." } ] }, { "name": "Connection", "doc": "A connected stream socket, optionally protected by TLS.", "kind": "interface", "type": "Connection", "operations": [ "close: fn()-\u003eUnit", "local_address: fn()-\u003eString", "peer_address: fn()-\u003eString", "read: fn(max_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[Optional[Bytes], IoError]", "shutdown_write: fn()-\u003eResult[Unit, NetworkError]", "tls_info: fn()-\u003eResult[TlsInfo, TlsError]", "write: fn(data: Bytes, timeout: Optional[Duration] = ...)-\u003eResult[Unit, IoError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Closes the socket, interrupting calls in progress, and waits for them to stop.\nSafe to call repeatedly; later calls wait for the first. Reads and writes afterwards return Closed." }, { "name": "local_address", "kind": "operation", "signature": "fn local_address() -\u003e String", "doc": "Returns this end's address as `host:port` text, with IPv6 hosts in brackets; for Unix sockets it is the socket path." }, { "name": "peer_address", "kind": "operation", "signature": "fn peer_address() -\u003e String", "doc": "Returns the remote end's address as `host:port` text, with IPv6 hosts in brackets." }, { "name": "read", "kind": "operation", "signature": "fn read(max_bytes: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[Optional[Bytes], IoError]", "doc": "Returns a positive chunk or none at EOF; local timeout uses IoError.Failed, not NetworkError.Timeout." }, { "name": "shutdown_write", "kind": "operation", "signature": "fn shutdown_write() -\u003e Result[Unit, NetworkError]", "doc": "Half-closes the connection so the peer sees end of stream, while this side can keep reading.\nReturns Unsupported for stream kinds that cannot half-close, and Closed on a closed connection." }, { "name": "tls_info", "kind": "operation", "signature": "fn tls_info() -\u003e Result[TlsInfo, TlsError]", "doc": "Returns the negotiated TLS version, cipher suite, protocol, and peer certificates.\nA connection that is not TLS returns InvalidInput." }, { "name": "write", "kind": "operation", "signature": "fn write(data: Bytes, timeout: Optional[Duration] = none) -\u003e Result[Unit, IoError]", "doc": "Writes all bytes on success; failure can leave a prefix. Local timeout uses IoError.Failed." } ] }, { "name": "Datagram", "doc": "One datagram and the address from which it was received.", "kind": "record", "type": "Datagram", "fields": [ "data: Bytes", "sender: String" ], "members": [ { "name": "data", "kind": "field", "signature": "data: Bytes", "doc": "The payload bytes of this datagram, never longer than the receive call's `max_bytes`." }, { "name": "sender", "kind": "field", "signature": "sender: String", "doc": "Native host:port text, with bracketed IPv6 addresses." } ] }, { "name": "DatagramSocket", "doc": "A connectionless socket for sending and receiving datagrams.", "kind": "interface", "type": "DatagramSocket", "operations": [ "address: fn()-\u003eString", "close: fn()-\u003eUnit", "receive: fn(max_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[Datagram, NetworkError]", "send: fn(data: Bytes, address: String, timeout: Optional[Duration] = ...)-\u003eResult[Unit, NetworkError]" ], "members": [ { "name": "address", "kind": "operation", "signature": "fn address() -\u003e String", "doc": "Returns the bound local address as `host:port` text, which reveals the port chosen when binding port 0." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Closes the socket, interrupting calls in progress, and waits for them to stop.\nSafe to call repeatedly." }, { "name": "receive", "kind": "operation", "signature": "fn receive(max_bytes: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[Datagram, NetworkError]", "doc": "Waits for one datagram and returns its bytes with the sender's address. `max_bytes` is 1 through 65535 and defaults to 65535.\nA larger datagram returns LimitExceeded and is discarded. A timeout returns Timeout and a closed socket returns Closed." }, { "name": "send", "kind": "operation", "signature": "fn send(data: Bytes, address: String, timeout: Optional[Duration] = none) -\u003e Result[Unit, NetworkError]", "doc": "Sends `data` as a single datagram to `address` (`host:port`), resolving a host name with the network's resolver.\nThe network's restrictions apply to both the name and the resolved address. A short send returns Failed; a timeout returns Timeout." } ] }, { "name": "DnsKind", "doc": "Supported DNS query categories; unknown spellings are rejected by checking.", "kind": "alternative", "type": "DnsKind", "cases": [ "A", "AAAA", "CNAME", "MX", "NS", "TXT", "PTR", "SRV" ], "operations": [ "text: fn()-\u003eString" ], "members": [ { "name": "A", "kind": "case", "signature": "case A", "doc": "IPv4 address records for the queried name." }, { "name": "AAAA", "kind": "case", "signature": "case AAAA", "doc": "IPv6 address records for the queried name." }, { "name": "CNAME", "kind": "case", "signature": "case CNAME", "doc": "Canonical name alias records for the queried name." }, { "name": "MX", "kind": "case", "signature": "case MX", "doc": "Mail exchange records with priority values." }, { "name": "NS", "kind": "case", "signature": "case NS", "doc": "Name server records for the queried zone." }, { "name": "PTR", "kind": "case", "signature": "case PTR", "doc": "Reverse address pointer records for an IP." }, { "name": "SRV", "kind": "case", "signature": "case SRV", "doc": "Service location records with priority, weight and port." }, { "name": "TXT", "kind": "case", "signature": "case TXT", "doc": "Text records returned as string values." }, { "name": "text", "kind": "operation", "signature": "fn text() -\u003e String:", "doc": "Returns the uppercase wire category." } ] }, { "name": "DnsRecord", "doc": "DNS record data returned by a typed lookup.", "kind": "record", "type": "DnsRecord", "fields": [ "kind: DnsKind", "value: String", "priority: Int", "weight: Int", "port: Int" ], "members": [ { "name": "kind", "kind": "field", "signature": "kind: DnsKind", "doc": "The same typed category used by the query." }, { "name": "port", "kind": "field", "signature": "port: Int", "doc": "The service port of an SRV record; 0 for other kinds." }, { "name": "priority", "kind": "field", "signature": "priority: Int", "doc": "The preference of an MX record or the priority of an SRV record, where lower values are tried first; 0 for other kinds." }, { "name": "value", "kind": "field", "signature": "value: String", "doc": "The record's answer: an IP address for A and AAAA, the target host name for CNAME, MX, NS, PTR, and SRV, or the text for TXT." }, { "name": "weight", "kind": "field", "signature": "weight: Int", "doc": "The relative weight of an SRV record among targets with the same priority; 0 for other kinds." } ] }, { "name": "IpAddress", "doc": "A validated numeric IPv4/IPv6 address without a port or zone.", "kind": "native", "type": "IpAddress", "operations": [ "family: fn()-\u003eIpFamily", "text: fn()-\u003eString" ], "members": [ { "name": "family", "kind": "operation", "signature": "fn family() -\u003e IpFamily:", "doc": "Returns the normalized address family." }, { "name": "text", "kind": "operation", "signature": "fn text() -\u003e String:", "doc": "Returns canonical text; mapped IPv6 input is normalized to IPv4." } ] }, { "name": "IpFamily", "doc": "Numeric address families reported by IP values and host interfaces.", "kind": "alternative", "type": "IpFamily", "cases": [ "IPv4", "IPv6" ], "operations": [ "text: fn()-\u003eString" ], "members": [ { "name": "IPv4", "kind": "case", "signature": "case IPv4", "doc": "A four-byte numeric address." }, { "name": "IPv6", "kind": "case", "signature": "case IPv6", "doc": "A sixteen-byte numeric address." }, { "name": "text", "kind": "operation", "signature": "fn text() -\u003e String:", "doc": "Returns IPv4 or IPv6." } ] }, { "name": "Listener", "doc": "A listening socket that accepts incoming connections.", "kind": "interface", "type": "Listener", "operations": [ "accept: fn(timeout: Optional[Duration] = ...)-\u003eResult[Connection, NetworkError]", "address: fn()-\u003eString", "close: fn()-\u003eUnit" ], "members": [ { "name": "accept", "kind": "operation", "signature": "fn accept(timeout: Optional[Duration] = none) -\u003e Result[Connection, NetworkError]", "doc": "Waits for the next incoming connection and returns it. A timeout returns Timeout and a closed listener returns Closed.\nOn a TLS listener the handshake completes before the connection is returned; a failed handshake drops that connection and returns Failed." }, { "name": "address", "kind": "operation", "signature": "fn address() -\u003e String", "doc": "Returns the bound local address as `host:port` text, which reveals the port chosen when listening on port 0." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Stops accepting, interrupts a pending `accept`, and waits for it to stop.\nSafe to call repeatedly; connections already accepted stay open." } ] }, { "name": "Network", "doc": "Network, DNS, HTTP, and WebSocket operations for the current host.", "kind": "interface", "type": "Network", "operations": [ "bind_datagram: fn(address: String)-\u003eResult[DatagramSocket, NetworkError]", "close: fn()-\u003eUnit", "connect: fn(address: String, timeout: Optional[Duration] = ...)-\u003eResult[Connection, NetworkError]", "connect_tls: fn(address: String, server_name: String, timeout: Optional[Duration] = ...)-\u003eResult[Connection, NetworkError]", "connect_tls_config: fn(address: String, options: TlsOptions, timeout: Optional[Duration] = ...)-\u003eResult[Connection, NetworkError]", "connect_unix: fn(path: String, timeout: Optional[Duration] = ...)-\u003eResult[Connection, NetworkError]", "http_client: fn(options: HttpClientOptions)-\u003eResult[HttpClient, HttpError]", "listen: fn(address: String)-\u003eResult[Listener, NetworkError]", "listen_tls: fn(address: String, options: TlsOptions, handshake_timeout: Optional[Duration] = ...)-\u003eResult[Listener, NetworkError]", "listen_unix: fn(path: String)-\u003eResult[Listener, NetworkError]", "lookup: fn(name: String, max_records: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[List[String], NetworkError]", "request: fn(method: HttpMethod, url: String, headers: HttpHeaders, body: Bytes = ..., max_response_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[ClientResponse, HttpError]", "resolve: fn(name: String, kind: DnsKind, max_records: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[List[DnsRecord], NetworkError]", "restrict: fn(hosts: List[String], cidrs: List[String], allow_listen: Bool)-\u003eResult[Network, NetworkError]", "serve: fn(address: String, handler: fn(request: HttpRequest)-\u003eHttpResponse, max_requests: Optional[Int] = ..., max_body_bytes: Optional[Int] = ..., max_response_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ..., grace: Optional[Duration] = ...)-\u003eResult[HttpServer, IoError]", "serve_stream: fn(address: String, handler: fn(exchange: HttpExchange)-\u003eResult[Unit, HttpError], options: HttpServerOptions)-\u003eResult[HttpServer, HttpError]", "web_socket: fn(url: String, headers: HttpHeaders, subprotocols: List[String], options: WebSocketOptions)-\u003eResult[WebSocket, WebSocketError]", "with_resolver: fn(address: String)-\u003eResult[Network, NetworkError]" ], "members": [ { "name": "bind_datagram", "kind": "operation", "signature": "fn bind_datagram(address: String) -\u003e Result[DatagramSocket, NetworkError]", "doc": "Binds a UDP socket to `address` (`host:port`; port 0 picks a free port).\nA restricted network without listening permission, or an address outside its CIDRs, returns PermissionDenied." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Cancels in-flight calls and closes every connection, listener, socket, HTTP client, and server this network opened, including those of derived networks.\nSafe to call repeatedly. A request handler of a server on this network cannot close it and faults." }, { "name": "connect", "kind": "operation", "signature": "fn connect(address: String, timeout: Optional[Duration] = none) -\u003e Result[Connection, NetworkError]", "doc": "Resolves `address` (`host:port`) and opens a TCP connection to the first reachable permitted address.\nReturns PermissionDenied for names or addresses a restricted network disallows, Timeout when `timeout` elapses, and Failed when every address refuses." }, { "name": "connect_tls", "kind": "operation", "signature": "fn connect_tls(address: String, server_name: String, timeout: Optional[Duration] = none) -\u003e Result[Connection, NetworkError]", "doc": "Connects over TCP to `address` and completes a TLS handshake verifying the server certificate against the system roots for `server_name`, with at least TLS 1.2.\nAn empty `server_name` returns InvalidInput, and `timeout` bounds the whole attempt." }, { "name": "connect_tls_config", "kind": "operation", "signature": "fn connect_tls_config(address: String, options: TlsOptions, timeout: Optional[Duration] = none) -\u003e Result[Connection, NetworkError]", "doc": "Connects over TCP to `address` and completes a TLS handshake using `options`, with at least TLS 1.2.\nInvalid options return InvalidInput, handshake and verification failures return Failed, and `timeout` bounds the whole attempt." }, { "name": "connect_unix", "kind": "operation", "signature": "fn connect_unix(path: String, timeout: Optional[Duration] = none) -\u003e Result[Connection, NetworkError]", "doc": "Connects to the Unix domain socket at `path`.\nAny restricted network returns PermissionDenied because Unix sockets bypass host and CIDR checks. `timeout` bounds the attempt." }, { "name": "http_client", "kind": "operation", "signature": "fn http_client(options: HttpClientOptions) -\u003e Result[HttpClient, HttpError]", "doc": "Creates a reusable HTTP client with connection pooling that dials through this network, so its restrictions and resolver apply to every request and redirect.\nInvalid or negative options return InvalidInput. Closing the network closes the client." }, { "name": "listen", "kind": "operation", "signature": "fn listen(address: String) -\u003e Result[Listener, NetworkError]", "doc": "Listens for TCP connections on `address` (`host:port`; port 0 picks a free port).\nA restricted network needs `allow_listen` and an IP-literal address inside its CIDRs, otherwise PermissionDenied is returned. An address that is not an IP literal with a port returns InvalidInput." }, { "name": "listen_tls", "kind": "operation", "signature": "fn listen_tls(address: String, options: TlsOptions, handshake_timeout: Optional[Duration] = none) -\u003e Result[Listener, NetworkError]", "doc": "Listens for TCP connections on `address` and completes a TLS handshake for each accepted connection, within `handshake_timeout` when supplied.\n`options` must hold a certificate and key, otherwise InvalidInput is returned." }, { "name": "listen_unix", "kind": "operation", "signature": "fn listen_unix(path: String) -\u003e Result[Listener, NetworkError]", "doc": "Listens on a Unix domain socket at `path`.\nAny restricted network returns PermissionDenied." }, { "name": "lookup", "kind": "operation", "signature": "fn lookup(name: String, max_records: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[List[String], NetworkError]", "doc": "Resolves a host name to its IPv4 and IPv6 address strings through the network's resolver.\nMore than `max_records` addresses returns LimitExceeded, `timeout` bounds the lookup, and a failed lookup returns Failed." }, { "name": "request", "kind": "operation", "signature": "fn request(method: HttpMethod, url: String, headers: HttpHeaders, body: Bytes = \"\".to_bytes(), max_response_bytes: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[ClientResponse, HttpError]", "doc": "Performs one buffered HTTP request and returns the status, headers, and complete body.\nOnly `http` and `https` URLs without user info are accepted. Redirects are returned, not followed, and no cookies or proxy settings apply. A body over `max_response_bytes` returns LimitExceeded; error statuses are ordinary responses." }, { "name": "resolve", "kind": "operation", "signature": "fn resolve(name: String, kind: DnsKind, max_records: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[List[DnsRecord], NetworkError]", "doc": "Resolves the selected supported category, retaining it in each record." }, { "name": "restrict", "kind": "operation", "signature": "fn restrict(hosts: List[String], cidrs: List[String], allow_listen: Bool) -\u003e Result[Network, NetworkError]", "doc": "Returns a derived network limited to the given host names and CIDR ranges.\nNames match case-insensitively without a trailing dot, and IP-literal hosts also match through `cidrs`. With `cidrs`, every resolved address must be inside one of them. `allow_listen` permits listening within the CIDRs. Unix sockets are refused. A derived restriction can only narrow its parent, and closing the parent closes the child. Invalid host or CIDR text returns InvalidInput." }, { "name": "serve", "kind": "operation", "signature": "fn serve(address: String, handler: fn(request: HttpRequest) -\u003e HttpResponse, max_requests: Optional[Int] = none, max_body_bytes: Optional[Int] = none, max_response_bytes: Optional[Int] = none, timeout: Optional[Duration] = none, grace: Optional[Duration] = none) -\u003e Result[HttpServer, IoError]", "doc": "Starts an HTTP server on `address` that calls `handler` with each fully buffered request and sends the returned response.\nA request beyond `limit` concurrent requests is answered with 503, an oversized request body with 413, and a handler fault with 500. An address that cannot be bound returns IoError.Unavailable." }, { "name": "serve_stream", "kind": "operation", "signature": "fn serve_stream(address: String, handler: fn(exchange: HttpExchange) -\u003e Result[Unit, HttpError], options: HttpServerOptions) -\u003e Result[HttpServer, HttpError]", "doc": "Starts an HTTP server on `address` whose handler receives each request as a streaming exchange. Limits, timeouts, and TLS come from `options`.\nReturns PermissionDenied when a restricted network disallows listening, and InvalidInput for invalid options. Close the server to stop it." }, { "name": "web_socket", "kind": "operation", "signature": "fn web_socket(url: String, headers: HttpHeaders, subprotocols: List[String], options: WebSocketOptions) -\u003e Result[WebSocket, WebSocketError]", "doc": "Opens a WebSocket client connection to a `ws` or `wss` URL, sending the given headers and offering `subprotocols` in order.\nHandshake headers such as `Upgrade`, `Connection`, `Host`, and `Sec-WebSocket-*` cannot be set. Failures use WebSocketError." }, { "name": "with_resolver", "kind": "operation", "signature": "fn with_resolver(address: String) -\u003e Result[Network, NetworkError]", "doc": "Returns a derived network that resolves names through the DNS server at `address`, an IP literal with port, instead of the system resolver.\nThe address must be allowed by this network's restrictions, otherwise PermissionDenied is returned. An address that is not an IP literal with a port returns InvalidInput." } ] }, { "name": "NetworkError", "doc": "Errors returned by socket, DNS, and network connection operations.", "kind": "alternative", "type": "NetworkError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "PermissionDenied", "Unsupported", "Closed", "Timeout", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The network, listener, or socket was closed before or during the call." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "Connection, bind, handshake, or DNS failure reported by the host, such as a refused connection or an unresolvable name." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Text is not a valid IP address or CIDR range, or a DNS answer is not valid UTF-8." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "An address, CIDR, name, record kind, or option is malformed, or a limit or timeout is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "A DNS lookup returned more records than `max_records`, or a received datagram is larger than `max_bytes`." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "The restricted network does not allow the host, resolved address, Unix socket, or listening address." }, { "name": "Timeout", "kind": "case", "signature": "case Timeout", "doc": "The supplied timeout elapsed before the operation completed." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The operation is unavailable for this kind of connection, such as `shutdown_write` on a stream that cannot half-close." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name addresses." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `network: \u003creason\u003e`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "contains_ip", "doc": "Reports whether an IP address belongs to a CIDR range.", "kind": "fn", "type": "fn(cidr: Cidr, address: IpAddress)-\u003eResult[Bool, NetworkError]" }, { "name": "network", "doc": "Returns network operations for the current host.", "kind": "fn", "type": "fn()-\u003eNetwork" }, { "name": "parse_cidr", "doc": "Validates and canonicalizes an IPv4 or IPv6 CIDR range.", "kind": "fn", "type": "fn(text: String)-\u003eResult[Cidr, NetworkError]" }, { "name": "parse_ip", "doc": "Validates and canonicalizes an IPv4 or IPv6 address.", "kind": "fn", "type": "fn(text: String)-\u003eResult[IpAddress, NetworkError]" } ] }, { "path": "@std/numbers.ms", "declarations": [ { "name": "NumberError", "doc": "Errors returned for invalid numeric requests, malformed text, or out-of-range values.", "kind": "alternative", "type": "NumberError", "cases": [ "InvalidInput", "InvalidData", "OutOfRange" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "The text does not match the numeric syntax, such as an empty string, stray characters, or digits invalid for the radix." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A radix or digit-count argument is outside its documented range." }, { "name": "OutOfRange", "kind": "case", "signature": "case OutOfRange", "doc": "The text is well formed but the value does not fit, such as an integer beyond signed 64 bits or a float beyond the finite range." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `number: \u003creason\u003e`, such as `number: invalid data`, without echoing the input text.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "parse_float", "doc": "Parses a decimal floating-point number using Manuscript's numeric syntax.", "kind": "fn", "type": "fn(text: String)-\u003eResult[Float, NumberError]" }, { "name": "parse_int", "doc": "Parses an integer in a radix from 2 through 36.", "kind": "fn", "type": "fn(text: String, radix: Int)-\u003eResult[Int, NumberError]" } ] }, { "path": "@std/optional.ms", "declarations": [ { "name": "Optional", "doc": "Represents a value that may be absent: `some(value)` or `none`.", "kind": "alternative", "type": "Optional[T]", "type_parameters": [ "T" ], "cases": [ "some(value: T)", "none" ], "operations": [ "and_then[U]: fn(transform: fn(value: T)-\u003eOptional[U])-\u003eOptional[U]", "is_none: fn()-\u003eBool", "is_some: fn()-\u003eBool", "map[U]: fn(transform: fn(value: T)-\u003eU)-\u003eOptional[U]", "ok_or[E]: fn(cause: Optional[E] = ...)-\u003eResult[T, E]", "ok_or_else[E]: fn(create: fn()-\u003eE)-\u003eResult[T, E]", "or_else: fn(create: fn()-\u003eOptional[T])-\u003eOptional[T]", "unwrap: fn()-\u003eT", "unwrap_or: fn(fallback: T)-\u003eT", "unwrap_or_else: fn(create: fn()-\u003eT)-\u003eT" ], "members": [ { "name": "none", "kind": "case", "signature": "case none", "doc": "An absent value with no payload; no T needs to be constructed." }, { "name": "some", "kind": "case", "signature": "case some(value: T)", "doc": "A present payload, retained by reference when T is mutable." }, { "name": "some.value", "kind": "field", "signature": "value: T", "doc": "The contained value; unwrap and matching return this original payload." }, { "name": "and_then[U]", "kind": "operation", "signature": "fn and_then[U](transform: fn(value: T) -\u003e Optional[U]) -\u003e Optional[U]:", "doc": "Calls transform only when present, returning its Optional unchanged." }, { "name": "is_none", "kind": "operation", "signature": "fn is_none() -\u003e Bool:", "doc": "Reports whether this value is absent." }, { "name": "is_some", "kind": "operation", "signature": "fn is_some() -\u003e Bool:", "doc": "Returns true for some(value), and false for none." }, { "name": "map[U]", "kind": "operation", "signature": "fn map[U](transform: fn(value: T) -\u003e U) -\u003e Optional[U]:", "doc": "Transforms a present payload; none remains absent." }, { "name": "ok_or[E]", "kind": "operation", "signature": "fn ok_or[E = MissingValue](cause: Optional[E] = none) -\u003e Result[T, E]:", "doc": "Returns ok with the original payload, or error with the eager cause.\nWithout a cause, E is MissingValue and the error names the calling source file and line." }, { "name": "ok_or_else[E]", "kind": "operation", "signature": "fn ok_or_else[E](create: fn() -\u003e E) -\u003e Result[T, E]:", "doc": "Constructs an error once only for none; present payloads remain unchanged." }, { "name": "or_else", "kind": "operation", "signature": "fn or_else(create: fn() -\u003e Optional[T]) -\u003e Optional[T]:", "doc": "Calls create once only when absent, returning its Optional unchanged." }, { "name": "unwrap", "kind": "operation", "signature": "fn unwrap() -\u003e T:", "doc": "Returns the payload. Calling this on `none` raises a fault." }, { "name": "unwrap_or", "kind": "operation", "signature": "fn unwrap_or(fallback: T) -\u003e T:", "doc": "Returns the contained value, or `fallback` when this is `none`." }, { "name": "unwrap_or_else", "kind": "operation", "signature": "fn unwrap_or_else(create: fn() -\u003e T) -\u003e T:", "doc": "Computes a fallback only when this is `none`." } ] } ] }, { "path": "@std/path.ms", "declarations": [ { "name": "PathError", "doc": "Errors returned when a path cannot be parsed or resolved.", "kind": "alternative", "type": "PathError", "cases": [ "InvalidInput" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Invalid NUL input, a nonabsolute resolve/relative anchor or malformed glob syntax." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a path-prefixed diagnostic without revealing the supplied paths or pattern.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "PathOperations", "doc": "Path operations using either POSIX or Windows path conventions.", "kind": "interface", "type": "PathOperations", "operations": [ "basename: fn(path: String)-\u003eString", "basename_without: fn(path: String, suffix: String)-\u003eString", "delimiter: fn()-\u003eString", "dirname: fn(path: String)-\u003eString", "extension: fn(path: String)-\u003eString", "format: fn(parts: PathParts)-\u003eString", "is_absolute: fn(path: String)-\u003eBool", "join: fn(parts: List[String])-\u003eString", "matches_glob: fn(path: String, pattern: String)-\u003eResult[Bool, PathError]", "normalize: fn(path: String)-\u003eString", "parse: fn(path: String)-\u003ePathParts", "relative: fn(base: String, target: String)-\u003eResult[String, PathError]", "resolve: fn(base: String, parts: List[String])-\u003eResult[String, PathError]", "separator: fn()-\u003eString", "to_namespaced_path: fn(path: String)-\u003eString" ], "members": [ { "name": "basename", "kind": "operation", "signature": "fn basename(path: String) -\u003e String", "doc": "Returns the last component after ignoring trailing separators under this view's path rules." }, { "name": "basename_without", "kind": "operation", "signature": "fn basename_without(path: String, suffix: String) -\u003e String", "doc": "Removes an exact suffix under basename compatibility rules; it does not strip arbitrary extensions." }, { "name": "delimiter", "kind": "operation", "signature": "fn delimiter() -\u003e String", "doc": "Returns colon for POSIX or semicolon for Windows path-list entries." }, { "name": "dirname", "kind": "operation", "signature": "fn dirname(path: String) -\u003e String", "doc": "Returns the directory component using the selected POSIX or Windows convention." }, { "name": "extension", "kind": "operation", "signature": "fn extension(path: String) -\u003e String", "doc": "Returns the final dot extension, or empty text for extensionless names and simple dotfiles." }, { "name": "format", "kind": "operation", "signature": "fn format(parts: PathParts) -\u003e String", "doc": "Builds a path with directory preferred over root, and base preferred over name plus extension." }, { "name": "is_absolute", "kind": "operation", "signature": "fn is_absolute(path: String) -\u003e Bool", "doc": "Tests absolute-root syntax; a Windows drive-relative spelling is not absolute." }, { "name": "join", "kind": "operation", "signature": "fn join(parts: List[String]) -\u003e String", "doc": "Joins nonempty parts and normalizes separators/dot segments without filesystem access." }, { "name": "matches_glob", "kind": "operation", "signature": "fn matches_glob(path: String, pattern: String) -\u003e Result[Bool, PathError]", "doc": "Tests one lexical path against the supported glob syntax; malformed patterns return InvalidInput." }, { "name": "normalize", "kind": "operation", "signature": "fn normalize(path: String) -\u003e String", "doc": "Cleans repeated separators and dot segments lexically; it does not resolve symlinks." }, { "name": "parse", "kind": "operation", "signature": "fn parse(path: String) -\u003e PathParts", "doc": "Splits the original spelling into root, directory, base, extension and name without filesystem access." }, { "name": "relative", "kind": "operation", "signature": "fn relative(base: String, target: String) -\u003e Result[String, PathError]", "doc": "Computes a lexical relative path from absolute anchors; different roots return the original target.\nNonabsolute anchors or invalid NUL input return InvalidInput." }, { "name": "resolve", "kind": "operation", "signature": "fn resolve(base: String, parts: List[String]) -\u003e Result[String, PathError]", "doc": "Resolves parts against an explicit absolute base; no process working directory is consulted." }, { "name": "separator", "kind": "operation", "signature": "fn separator() -\u003e String", "doc": "Returns slash for POSIX or backslash for Windows path components." }, { "name": "to_namespaced_path", "kind": "operation", "signature": "fn to_namespaced_path(path: String) -\u003e String", "doc": "Returns a Windows namespaced absolute path when applicable; POSIX paths are unchanged." } ] }, { "name": "PathParts", "doc": "Parsed path components using the familiar root, directory, base, extension, and name fields.", "kind": "record", "type": "PathParts", "fields": [ "root: String", "directory: String", "base: String", "extension: String", "name: String" ], "members": [ { "name": "base", "kind": "field", "signature": "base: String", "doc": "Final component with extension; it takes precedence over name/extension during format." }, { "name": "directory", "kind": "field", "signature": "directory: String", "doc": "Directory portion, including the root when present; it takes precedence over root during format." }, { "name": "extension", "kind": "field", "signature": "extension: String", "doc": "Final extension including its dot; simple dotfiles and dot/dot-dot components have no extension." }, { "name": "name", "kind": "field", "signature": "name: String", "doc": "Final component with its extension removed, retaining the original spelling." }, { "name": "root", "kind": "field", "signature": "root: String", "doc": "Root prefix under the chosen path rules, including a POSIX slash or Windows drive/UNC root." } ] }, { "name": "basename", "doc": "Returns the final path component, excluding trailing separators.", "kind": "fn", "type": "fn(path: String)-\u003eString" }, { "name": "basename_without", "doc": "Returns the basename with the supplied suffix removed when it matches.", "kind": "fn", "type": "fn(path: String, suffix: String)-\u003eString" }, { "name": "delimiter", "doc": "Returns the host's path-list delimiter.", "kind": "fn", "type": "fn()-\u003eString" }, { "name": "dirname", "doc": "Returns the directory portion of a path.", "kind": "fn", "type": "fn(path: String)-\u003eString" }, { "name": "extension", "doc": "Returns the final extension, including its leading dot, or an empty string.", "kind": "fn", "type": "fn(path: String)-\u003eString" }, { "name": "format", "doc": "Formats parsed path components as a path string.", "kind": "fn", "type": "fn(parts: PathParts)-\u003eString" }, { "name": "is_absolute", "doc": "Reports whether a path is absolute according to the host path rules.", "kind": "fn", "type": "fn(path: String)-\u003eBool" }, { "name": "join", "doc": "Joins path parts using the host separator and normalizes the result.", "kind": "fn", "type": "fn(parts: List[String])-\u003eString" }, { "name": "matches_glob", "doc": "Tests a path against a glob pattern.", "kind": "fn", "type": "fn(path: String, pattern: String)-\u003eResult[Bool, PathError]" }, { "name": "normalize", "doc": "Normalizes separators and dot segments without accessing the filesystem.", "kind": "fn", "type": "fn(path: String)-\u003eString" }, { "name": "parse", "doc": "Splits a path into its root, directory, base, extension, and name.", "kind": "fn", "type": "fn(path: String)-\u003ePathParts" }, { "name": "posix", "doc": "Returns path operations using POSIX separators and parsing rules.", "kind": "fn", "type": "fn()-\u003ePathOperations" }, { "name": "relative", "doc": "Computes a relative path from `base` to `target` using host path rules.", "kind": "fn", "type": "fn(base: String, target: String)-\u003eResult[String, PathError]" }, { "name": "resolve", "doc": "Resolves path parts against a base using host path conventions.", "kind": "fn", "type": "fn(base: String, parts: List[String])-\u003eResult[String, PathError]" }, { "name": "separator", "doc": "Returns the host's path separator.", "kind": "fn", "type": "fn()-\u003eString" }, { "name": "to_namespaced_path", "doc": "Converts a path to the host's namespaced representation when applicable.", "kind": "fn", "type": "fn(path: String)-\u003eString" }, { "name": "win32", "doc": "Returns path operations using Windows separators and parsing rules.", "kind": "fn", "type": "fn()-\u003ePathOperations" } ] }, { "path": "@std/process.ms", "declarations": [ { "name": "CommandError", "doc": "Errors returned when a process cannot start, times out, or exceeds an output bound.", "kind": "alternative", "type": "CommandError", "cases": [ "InvalidInput", "Unavailable", "Timeout", "OutputLimit", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "The command could not be started or run for another reason reported by the host." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "The program name is empty, or the program, an argument, or a limit holds a NUL byte or is negative." }, { "name": "OutputLimit", "kind": "case", "signature": "case OutputLimit", "doc": "The combined standard output and error exceeded `max_output_bytes`, and the command was killed." }, { "name": "Timeout", "kind": "case", "signature": "case Timeout", "doc": "The command was still running when `timeout` elapsed, and its process group was killed." }, { "name": "Unavailable", "kind": "case", "signature": "case Unavailable", "doc": "The program could not be found or executed, such as a missing executable." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name paths." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `command: \u003creason\u003e`, such as `command: operation timed out`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "CommandOutput", "doc": "Captured exit status and standard output/error from a completed command.", "kind": "record", "type": "CommandOutput", "fields": [ "exit_code: Int", "stdout: Bytes", "stderr: Bytes" ], "members": [ { "name": "exit_code", "kind": "field", "signature": "exit_code: Int", "doc": "The child's exit status; 0 conventionally means success. A nonzero status is still an Ok result, and a child ended by a signal reports -1 on Unix." }, { "name": "stderr", "kind": "field", "signature": "stderr: Bytes", "doc": "Everything the child wrote to standard error, as raw bytes that may not be valid UTF-8." }, { "name": "stdout", "kind": "field", "signature": "stdout: Bytes", "doc": "Everything the child wrote to standard output, as raw bytes that may not be valid UTF-8." } ] }, { "name": "Commands", "doc": "Runs child programs with empty input by default, optional output bounds and timeout.", "kind": "interface", "type": "Commands", "operations": [ "run: fn(program: String, arguments: List[String], input: Bytes = ..., max_output_bytes: Optional[Int] = ..., timeout: Optional[Duration] = ...)-\u003eResult[CommandOutput, CommandError]", "spawn: fn(program: String, arguments: List[String])-\u003eResult[Subprocess, CommandError]" ], "members": [ { "name": "run", "kind": "operation", "signature": "fn run(program: String, arguments: List[String], input: Bytes = \"\".to_bytes(), max_output_bytes: Optional[Int] = none, timeout: Optional[Duration] = none) -\u003e Result[CommandOutput, CommandError]", "doc": "Starts `program` directly, without a shell, searching the PATH, and waits for it to finish. `arguments` are passed after the program name, `input` is written to its standard input, and its output is captured.\nOutput beyond `max_output_bytes` in total across both streams returns OutputLimit, `timeout` returns Timeout, and in both cases the child's process group is killed. Cancelling the calling task also kills it." }, { "name": "spawn", "kind": "operation", "signature": "fn spawn(program: String, arguments: List[String]) -\u003e Result[Subprocess, CommandError]", "doc": "Starts `program` directly, without a shell, searching the PATH, and returns a live Subprocess for use with `with`. `arguments` follow the program name; stdin, stdout, and stderr are OS pipes. Returns InvalidInput, Unavailable, or Failed when it cannot start. Closing the Subprocess, or cancelling the acquiring execution, kills the child's process group." } ] }, { "name": "CpuUsage", "doc": "Cumulative CPU time consumed by the current process, in integer microseconds.", "kind": "record", "type": "CpuUsage", "fields": [ "user_microseconds: Int", "system_microseconds: Int" ], "members": [ { "name": "system_microseconds", "kind": "field", "signature": "system_microseconds: Int", "doc": "Kernel CPU time in microseconds." }, { "name": "user_microseconds", "kind": "field", "signature": "user_microseconds: Int", "doc": "User CPU time in microseconds." } ] }, { "name": "MemoryUsage", "doc": "Memory statistics for the current process; every field is bytes.", "kind": "record", "type": "MemoryUsage", "fields": [ "heap_used: Int", "heap_total: Int", "heap_system: Int", "external: Int", "resident: Int" ], "members": [ { "name": "external", "kind": "field", "signature": "external: Int", "doc": "Bytes the runtime obtained from the operating system outside the heap, such as stacks and internal tables." }, { "name": "heap_system", "kind": "field", "signature": "heap_system: Int", "doc": "Bytes of heap memory obtained from the operating system, including idle spans." }, { "name": "heap_total", "kind": "field", "signature": "heap_total: Int", "doc": "Bytes of heap spans currently in use, which is at least `heap_used`." }, { "name": "heap_used", "kind": "field", "signature": "heap_used: Int", "doc": "Bytes of heap memory occupied by live objects and objects not yet collected." }, { "name": "resident", "kind": "field", "signature": "resident: Int", "doc": "Bytes of physical memory the operating system reports as resident for the process." } ] }, { "name": "ProcessControl", "doc": "Process and operating-system controls for the current process.\n`watch_signals` observes signals without claiming them; SIGINT/SIGTERM still cancel the native application.\n`next()` and code following it have no shutdown guarantee. Register `with`/`Closeable` cleanup\nand finish shutdown work directly in the shielded close call after joining cancelled workers.", "kind": "interface", "type": "ProcessControl", "operations": [ "available_memory: fn()-\u003eResult[Int, ProcessError]", "change_directory: fn(path: String)-\u003eResult[Unit, ProcessError]", "constrained_memory: fn()-\u003eResult[Int, ProcessError]", "cpu_usage: fn()-\u003eResult[CpuUsage, ProcessError]", "environment: fn()-\u003eResult[Map[String, String], ProcessError]", "groups: fn()-\u003eResult[List[Int], ProcessError]", "info: fn()-\u003eResult[ProcessInfo, ProcessError]", "initialize_groups: fn(username: String, gid: Int)-\u003eResult[Unit, ProcessError]", "load_environment: fn(path: String, max_bytes: Optional[Int] = ...)-\u003eResult[Unit, ProcessError]", "memory_usage: fn()-\u003eResult[MemoryUsage, ProcessError]", "monotonic_time: fn()-\u003eInt", "replace: fn(program: String, arguments: List[String], environment: Map[String, String])-\u003eResult[Unit, ProcessError]", "resource_usage: fn()-\u003eResult[ResourceUsage, ProcessError]", "send_signal: fn(pid: Int, signal: Int)-\u003eResult[Unit, ProcessError]", "set_environment: fn(name: String, value: Optional[String])-\u003eResult[Unit, ProcessError]", "set_groups: fn(groups: List[Int])-\u003eResult[Unit, ProcessError]", "set_identity: fn(kind: String, id: Int)-\u003eResult[Unit, ProcessError]", "set_title: fn(title: String)-\u003eResult[Unit, ProcessError]", "title: fn()-\u003eResult[String, ProcessError]", "umask: fn(mask: Int)-\u003eResult[Int, ProcessError]", "uptime: fn()-\u003eResult[Duration, ProcessError]", "watch_signals: fn(signals: List[Int], capacity: Optional[Int] = ...)-\u003eResult[SignalStream, ProcessError]", "working_directory: fn()-\u003eResult[String, ProcessError]" ], "members": [ { "name": "available_memory", "kind": "operation", "signature": "fn available_memory() -\u003e Result[Int, ProcessError]", "doc": "Returns bytes available to new allocations: the host's available memory, reduced to the remaining headroom when a Linux cgroup memory limit applies." }, { "name": "change_directory", "kind": "operation", "signature": "fn change_directory(path: String) -\u003e Result[Unit, ProcessError]", "doc": "Changes the working directory of the whole process, affecting relative paths everywhere.\nA missing path returns NotFound, a path containing NUL returns InvalidInput, and a denied path returns PermissionDenied." }, { "name": "constrained_memory", "kind": "operation", "signature": "fn constrained_memory() -\u003e Result[Int, ProcessError]", "doc": "Returns the memory limit in bytes imposed on this process by its Linux cgroup, or 0 when no limit applies or the platform has no such limit." }, { "name": "cpu_usage", "kind": "operation", "signature": "fn cpu_usage() -\u003e Result[CpuUsage, ProcessError]", "doc": "Returns cumulative user and kernel CPU time consumed by this process in microseconds.\nPlatforms without resource accounting return Unsupported." }, { "name": "environment", "kind": "operation", "signature": "fn environment() -\u003e Result[Map[String, String], ProcessError]", "doc": "Reads a fresh live process environment map; non-UTF-8 entries return Unsupported." }, { "name": "groups", "kind": "operation", "signature": "fn groups() -\u003e Result[List[Int], ProcessError]", "doc": "Returns the numeric ids of the supplementary groups of the process.\nWindows returns Unsupported." }, { "name": "info", "kind": "operation", "signature": "fn info() -\u003e Result[ProcessInfo, ProcessError]", "doc": "Returns the process id, parent id, executable path, arguments, platform, and real and effective user and group ids.\nText that is not valid UTF-8 returns Unsupported." }, { "name": "initialize_groups", "kind": "operation", "signature": "fn initialize_groups(username: String, gid: Int) -\u003e Result[Unit, ProcessError]", "doc": "Replaces the supplementary group list with the groups of `username` from the account database plus `gid` first. Requires privilege.\nA failed user lookup returns Failed, a `gid` outside 0 through 2147483647 returns InvalidInput, and a lack of privilege returns PermissionDenied." }, { "name": "load_environment", "kind": "operation", "signature": "fn load_environment(path: String, max_bytes: Optional[Int] = none) -\u003e Result[Unit, ProcessError]", "doc": "Reads `KEY=value` lines from the file at `path` and sets each variable that is not already present in the environment. Existing variables keep their values.\nBlank lines, `#` comments, an `export ` prefix, and single-, double-, or backtick-quoted values spanning lines are accepted. The whole file is validated first, so a malformed or non-UTF-8 file returns InvalidData and changes nothing. A file larger than `max_bytes` returns LimitExceeded." }, { "name": "memory_usage", "kind": "operation", "signature": "fn memory_usage() -\u003e Result[MemoryUsage, ProcessError]", "doc": "Returns heap and resident memory statistics for this process, in bytes." }, { "name": "monotonic_time", "kind": "operation", "signature": "fn monotonic_time() -\u003e Int", "doc": "Elapsed nanoseconds since native runtime initialization, sharing the uptime() origin.\nThis is not Unix time or a Clock Instant; prefer clock().now().difference(start) for timing." }, { "name": "replace", "kind": "operation", "signature": "fn replace(program: String, arguments: List[String], environment: Map[String, String]) -\u003e Result[Unit, ProcessError]", "doc": "Replaces the running process image with `program` using exactly the given `arguments` as argv, where `arguments[0]` is the program name, and exactly the given `environment`. On success it never returns.\n`program` is a path, not a PATH lookup. An empty program, an empty argument list, or NUL bytes return InvalidInput, and exec failures return NotFound, PermissionDenied, or Failed. Unsupported on Windows." }, { "name": "resource_usage", "kind": "operation", "signature": "fn resource_usage() -\u003e Result[ResourceUsage, ProcessError]", "doc": "Returns kernel resource counters for this process: CPU times, peak resident size, page faults, block I/O, and context switches.\nPlatforms without them return Unsupported." }, { "name": "send_signal", "kind": "operation", "signature": "fn send_signal(pid: Int, signal: Int) -\u003e Result[Unit, ProcessError]", "doc": "Validates a signed 32-bit PID and signal 0..64; the OS decides supported numbers/permissions.\nSignal 0 checks existence; Windows positive PIDs support 0 and forced INT/KILL/TERM termination." }, { "name": "set_environment", "kind": "operation", "signature": "fn set_environment(name: String, value: Optional[String]) -\u003e Result[Unit, ProcessError]", "doc": "Sets environment variable `name` for this process to `value`, or removes it when `value` is none.\nAn empty name, or a name or value with `=` or NUL, returns InvalidInput. The change is visible to child processes started afterwards." }, { "name": "set_groups", "kind": "operation", "signature": "fn set_groups(groups: List[Int]) -\u003e Result[Unit, ProcessError]", "doc": "Replaces the supplementary group list with the given numeric ids, each 0 through 2147483647. Requires privilege.\nInvalid ids return InvalidInput, a lack of privilege returns PermissionDenied, and Windows returns Unsupported." }, { "name": "set_identity", "kind": "operation", "signature": "fn set_identity(kind: String, id: Int) -\u003e Result[Unit, ProcessError]", "doc": "Accepts exactly uid, gid, euid, or egid and id 0..2147483647; other inputs return InvalidInput.\nIdentity changes require OS permission and are Unsupported on Windows." }, { "name": "set_title", "kind": "operation", "signature": "fn set_title(title: String) -\u003e Result[Unit, ProcessError]", "doc": "Sets the process title shown by tools such as `ps`.\nA title with NUL or newline returns InvalidInput, and platforms that cannot rename a process return Unsupported." }, { "name": "title", "kind": "operation", "signature": "fn title() -\u003e Result[String, ProcessError]", "doc": "Returns the current process title.\nPlatforms that cannot read it return Unsupported." }, { "name": "umask", "kind": "operation", "signature": "fn umask(mask: Int) -\u003e Result[Int, ProcessError]", "doc": "Sets mask 0..511 (0777) and returns the previous mask; Unsupported on Windows." }, { "name": "uptime", "kind": "operation", "signature": "fn uptime() -\u003e Result[Duration, ProcessError]", "doc": "Returns elapsed Duration since runtime initialization, rather than host boot." }, { "name": "watch_signals", "kind": "operation", "signature": "fn watch_signals(signals: List[Int], capacity: Optional[Int] = none) -\u003e Result[SignalStream, ProcessError]", "doc": "Observes native signal numbers 1..64, excluding SIGKILL/SIGSTOP; the list must be nonempty.\nCapacity must be 1..1048576; omission/none uses 128 buffered signals.\nNumeric validation does not guarantee OS support. Observing does not suppress host cancellation.\nCode after next() has no shutdown guarantee; use registered with/Closeable cleanup." }, { "name": "working_directory", "kind": "operation", "signature": "fn working_directory() -\u003e Result[String, ProcessError]", "doc": "Reads the live process directory, preserving OS failures as ProcessError." } ] }, { "name": "ProcessError", "doc": "Errors returned by process-control operations.", "kind": "alternative", "type": "ProcessError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "NotFound", "AlreadyExists", "PermissionDenied", "Unsupported", "Closed", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "AlreadyExists", "kind": "case", "signature": "case AlreadyExists", "doc": "The host reported that the target already exists." }, { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "A signal stream was closed while waiting or before the call." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "The host reported another failure while performing the operation." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Host data or file content was malformed, such as an environment file that does not parse or is not valid UTF-8." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "An argument is outside its documented range or contains NUL, such as an invalid signal number, id, mask, capacity, or environment name." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "An environment file is larger than `max_bytes`." }, { "name": "NotFound", "kind": "case", "signature": "case NotFound", "doc": "The host reported that a path or user does not exist." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "The host refused the operation for lack of privilege." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The platform does not provide the operation, or a value is not valid UTF-8." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name paths." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `process: \u003creason\u003e`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "ProcessInfo", "doc": "Identity and invocation details for the current process.", "kind": "record", "type": "ProcessInfo", "fields": [ "pid: Int", "parent_pid: Int", "executable: String", "arguments: List[String]", "os: String", "architecture: String", "uid: Int", "gid: Int", "effective_uid: Int", "effective_gid: Int" ], "members": [ { "name": "architecture", "kind": "field", "signature": "architecture: String", "doc": "Processor architecture in Go's naming, such as `amd64` or `arm64`." }, { "name": "arguments", "kind": "field", "signature": "arguments: List[String]", "doc": "Live native argv including argv[0]; cli.arguments() is the supplied startup tail without it." }, { "name": "effective_gid", "kind": "field", "signature": "effective_gid: Int", "doc": "Effective group id used for permission checks; -1 on Windows." }, { "name": "effective_uid", "kind": "field", "signature": "effective_uid: Int", "doc": "Effective user id used for permission checks; -1 on Windows." }, { "name": "executable", "kind": "field", "signature": "executable: String", "doc": "Absolute path of the running program file." }, { "name": "gid", "kind": "field", "signature": "gid: Int", "doc": "Real group id; -1 on Windows, where ids are not numeric." }, { "name": "os", "kind": "field", "signature": "os: String", "doc": "Operating system name in Go's naming, such as `linux`, `darwin`, or `windows`." }, { "name": "parent_pid", "kind": "field", "signature": "parent_pid: Int", "doc": "Operating system id of the parent process at the time of the call." }, { "name": "pid", "kind": "field", "signature": "pid: Int", "doc": "Operating system id of this process." }, { "name": "uid", "kind": "field", "signature": "uid: Int", "doc": "Real user id; -1 on Windows, where ids are not numeric." } ] }, { "name": "ResourceUsage", "doc": "Kernel resource counters for the current process. CPU times are integer microseconds;\nmax_resident_bytes is bytes; other fields are counts, not durations or byte totals.\nFilesystem reads/writes count native block I/O on Unix and I/O operations on Windows.\nUnavailable Windows fault/context-switch counters are zero.", "kind": "record", "type": "ResourceUsage", "fields": [ "user_microseconds: Int", "system_microseconds: Int", "max_resident_bytes: Int", "minor_faults: Int", "major_faults: Int", "filesystem_reads: Int", "filesystem_writes: Int", "voluntary_switches: Int", "involuntary_switches: Int" ], "members": [ { "name": "filesystem_reads", "kind": "field", "signature": "filesystem_reads: Int", "doc": "Block input operations charged to the process, as a count." }, { "name": "filesystem_writes", "kind": "field", "signature": "filesystem_writes: Int", "doc": "Block output operations charged to the process, as a count." }, { "name": "involuntary_switches", "kind": "field", "signature": "involuntary_switches: Int", "doc": "Context switches where the scheduler preempted the process, as a count." }, { "name": "major_faults", "kind": "field", "signature": "major_faults: Int", "doc": "Page faults that required disk I/O, as a count." }, { "name": "max_resident_bytes", "kind": "field", "signature": "max_resident_bytes: Int", "doc": "Peak physical memory the process has held at once, in bytes." }, { "name": "minor_faults", "kind": "field", "signature": "minor_faults: Int", "doc": "Page faults served without disk I/O, as a count." }, { "name": "system_microseconds", "kind": "field", "signature": "system_microseconds: Int", "doc": "Cumulative CPU time the kernel spent on behalf of this process, in microseconds." }, { "name": "user_microseconds", "kind": "field", "signature": "user_microseconds: Int", "doc": "Cumulative CPU time spent running this process's own code, in microseconds." }, { "name": "voluntary_switches", "kind": "field", "signature": "voluntary_switches: Int", "doc": "Context switches where the process gave up the CPU, such as to wait for I/O, as a count." } ] }, { "name": "SignalStream", "doc": "A cancellable observer of operating-system signals selected by `watch_signals`.\nSIGINT/SIGTERM still cancel the native application; `close()` unregisters this observer.\n`next()` and following code have no shutdown guarantee; use registered `with`/`Closeable` cleanup.", "kind": "interface", "type": "SignalStream", "operations": [ "close: fn()-\u003eUnit", "next: fn()-\u003eResult[Int, ProcessError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Stops observing signals, wakes a pending `next` with Closed, and waits for it.\nSafe to call repeatedly." }, { "name": "next", "kind": "operation", "signature": "fn next() -\u003e Result[Int, ProcessError]", "doc": "Waits for the next observed signal and returns its number. Signals arriving while no call waits are buffered up to the stream's capacity.\nReturns Closed after `close`. Cancelling the waiting task unwinds it." } ] }, { "name": "Subprocess", "doc": "A long-lived child process with live stdin, stdout, and stderr pipes. Closing it\nkills the child's process group, joins it, and closes all three streams.", "kind": "interface", "type": "Subprocess", "operations": [ "close: fn()-\u003eUnit", "kill: fn()-\u003eUnit", "stderr: fn()-\u003eReadStream", "stdin: fn()-\u003eWriteStream", "stdout: fn()-\u003eReadStream", "terminate: fn()-\u003eUnit", "wait: fn(timeout: Optional[Duration] = ...)-\u003eResult[Int, CommandError]" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Kills the process group, joins the child, kills leftover group members, and closes all three streams. Idempotent; `with` calls it on scope exit." }, { "name": "kill", "kind": "operation", "signature": "fn kill() -\u003e Unit", "doc": "Sends SIGKILL to the child's process group. Does not wait." }, { "name": "stderr", "kind": "operation", "signature": "fn stderr() -\u003e ReadStream", "doc": "The child's standard error as a ReadStream over the OS pipe, with the same blocking and backpressure behavior as stdout." }, { "name": "stdin", "kind": "operation", "signature": "fn stdin() -\u003e WriteStream", "doc": "The child's standard input as a WriteStream; writes block when the pipe is full. Closing the stream delivers end-of-input to the child." }, { "name": "stdout", "kind": "operation", "signature": "fn stdout() -\u003e ReadStream", "doc": "The child's standard output as a ReadStream over the OS pipe; reads block until output or end-of-file, and nothing is buffered without bound." }, { "name": "terminate", "kind": "operation", "signature": "fn terminate() -\u003e Unit", "doc": "Sends SIGTERM to the child's process group on Unix; Windows has no SIGTERM, so it kills the direct process. Does not wait." }, { "name": "wait", "kind": "operation", "signature": "fn wait(timeout: Optional[Duration] = none) -\u003e Result[Int, CommandError]", "doc": "Waits for the child to exit and returns its exit status. Returns Timeout if `timeout` elapses first, leaving the child running." } ] }, { "name": "commands", "doc": "Returns child-process operations for the current host.", "kind": "fn", "type": "fn()-\u003eCommands" }, { "name": "control", "doc": "Returns controls and process information for the current process.", "kind": "fn", "type": "fn()-\u003eProcessControl" } ] }, { "path": "@std/queues.ms", "declarations": [ { "name": "BlockingQueue", "doc": "A FIFO queue that waits instead of failing: put blocks while a bounded queue is full,\nand take blocks while the queue is empty. It synchronizes itself, so tasks share it directly.\nWaiting stops at cancellation, so a TaskGroup close unblocks every waiting task.", "kind": "native", "type": "BlockingQueue[T]", "type_parameters": [ "T" ], "fields": [ "capacity: Optional[Int]" ], "operations": [ "close: fn()-\u003eUnit", "is_closed: fn()-\u003eBool", "length: fn()-\u003eInt", "put: fn(value: T)-\u003eBool", "take: fn()-\u003eOptional[T]" ], "members": [ { "name": "capacity", "kind": "field", "signature": "capacity: Optional[Int] = none", "doc": "Constructor capacity in items; omission/none is unbounded, and supplied values must be positive." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit:", "doc": "Closes the queue and wakes every waiting task. Queued values can still be taken; later puts return false." }, { "name": "is_closed", "kind": "operation", "signature": "fn is_closed() -\u003e Bool:", "doc": "Reports whether close has been called." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of values currently waiting in the queue." }, { "name": "put", "kind": "operation", "signature": "fn put(value: T) -\u003e Bool:", "doc": "Waits for free space, then adds the value and returns true. Returns false when the queue is closed." }, { "name": "take", "kind": "operation", "signature": "fn take() -\u003e Optional[T]:", "doc": "Waits for a value and removes the oldest. Returns none once the queue is closed and empty." } ] }, { "name": "PriorityQueue", "doc": "Negative compare results put left before right; equal priorities remain FIFO.", "kind": "native", "type": "PriorityQueue[T]", "type_parameters": [ "T" ], "fields": [ "compare: fn(left: T, right: T)-\u003eInt", "capacity: Optional[Int]" ], "operations": [ "dequeue: fn()-\u003eOptional[T]", "enqueue: fn(value: T)-\u003eBool", "is_empty: fn()-\u003eBool", "length: fn()-\u003eInt", "peek: fn()-\u003eOptional[T]" ], "members": [ { "name": "capacity", "kind": "field", "signature": "capacity: Optional[Int] = none", "doc": "Constructor capacity in items; omission/none is unbounded, and supplied values must be positive." }, { "name": "compare", "kind": "field", "signature": "compare: fn(left: T, right: T) -\u003e Int", "doc": "Constructor comparator: negative puts left first; ties dequeue in enqueue order.\nComparisons must stay consistent and must not mutate this queue." }, { "name": "dequeue", "kind": "operation", "signature": "fn dequeue() -\u003e Optional[T]:", "doc": "Removes and returns the next value by priority, or `none` when empty." }, { "name": "enqueue", "kind": "operation", "signature": "fn enqueue(value: T) -\u003e Bool:", "doc": "Adds a value, returning false when a bounded queue is full." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether the queue has no values to peek or dequeue." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of enqueued values, independent of their priorities." }, { "name": "peek", "kind": "operation", "signature": "fn peek() -\u003e Optional[T]:", "doc": "Returns the next value by priority without removing it, or none when empty." } ] }, { "name": "Queue", "doc": "A local mutable FIFO queue; protect all shared access with Synchronized.\nOmitted or none capacity grows as needed and adds no fixed queue limit.", "kind": "native", "type": "Queue[T]", "type_parameters": [ "T" ], "fields": [ "capacity: Optional[Int]" ], "operations": [ "dequeue: fn()-\u003eOptional[T]", "enqueue: fn(value: T)-\u003eBool", "is_empty: fn()-\u003eBool", "length: fn()-\u003eInt", "peek: fn()-\u003eOptional[T]" ], "members": [ { "name": "capacity", "kind": "field", "signature": "capacity: Optional[Int] = none", "doc": "Constructor capacity in items; omission/none is unbounded, and supplied values must be positive." }, { "name": "dequeue", "kind": "operation", "signature": "fn dequeue() -\u003e Optional[T]:", "doc": "Removes and returns the oldest value, or `none` when empty." }, { "name": "enqueue", "kind": "operation", "signature": "fn enqueue(value: T) -\u003e Bool:", "doc": "Adds a value, returning false when a bounded queue is full." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether dequeue and peek would return none." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of values currently waiting in the queue." }, { "name": "peek", "kind": "operation", "signature": "fn peek() -\u003e Optional[T]:", "doc": "Returns the oldest value without removing it, or none when the queue is empty." } ] } ] }, { "path": "@std/random.ms", "declarations": [ { "name": "Entropy", "doc": "A source of cryptographically secure random bytes.", "kind": "interface", "type": "Entropy", "operations": [ "bytes: fn(count: Int)-\u003eResult[Bytes, RandomError]" ], "members": [ { "name": "bytes", "kind": "operation", "signature": "fn bytes(count: Int) -\u003e Result[Bytes, RandomError]", "doc": "Returns exactly `count` unpredictable bytes, with `count` from 0 through 16 MiB (16777216).\nA negative or larger count returns InvalidInput; a source failure returns Failed. The operating system source observes task cancellation between 64 KiB chunks." } ] }, { "name": "RandomError", "doc": "Errors returned when random input is invalid or entropy generation fails.", "kind": "alternative", "type": "RandomError", "cases": [ "InvalidInput", "LimitExceeded", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "The entropy source could not produce bytes, or returned a different number of bytes than requested." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "The requested byte count is negative or above 16 MiB, or `secure_int` was given `min` not below `max_exclusive`." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Reserved for requests that exceed a configured random-generation budget; the current operations do not return it." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "The source's failure text, which `message()` returns verbatim." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `random: \u003creason\u003e`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "entropy", "doc": "Returns the operating system's cryptographic entropy source.", "kind": "fn", "type": "fn()-\u003eEntropy" }, { "name": "secure_int", "doc": "Returns a secure integer at least `min` and below `max_exclusive` when supplied.", "kind": "fn", "type": "fn(entropy: Entropy, min: Int, max_exclusive: Optional[Int] = ...)-\u003eResult[Int, RandomError]" }, { "name": "uuid_v4", "doc": "Creates a version-4 UUID using the supplied cryptographic entropy source.", "kind": "fn", "type": "fn(entropy: Entropy)-\u003eResult[String, RandomError]" } ] }, { "path": "@std/regex.ms", "declarations": [ { "name": "Regex", "doc": "A compiled regular expression that can be reused across input strings.", "kind": "native", "type": "Regex", "operations": [ "find_all: fn(text: String, max_matches: Optional[Int] = ...)-\u003eResult[List[String], RegexError]", "matches: fn(text: String)-\u003eBool", "replace_all: fn(text: String, replacement: String, max_bytes: Optional[Int] = ...)-\u003eResult[String, RegexError]" ], "members": [ { "name": "find_all", "kind": "operation", "signature": "fn find_all(text: String, max_matches: Optional[Int] = none) -\u003e Result[List[String], RegexError]:", "doc": "Returns nonoverlapping full-match text in occurrence order, excluding capture groups.\nA supplied cap is a strict budget, not truncation; zero-width matches follow native regexp rules." }, { "name": "matches", "kind": "operation", "signature": "fn matches(text: String) -\u003e Bool:", "doc": "Tests whether any match occurs; anchor the pattern explicitly to require a whole-string match." }, { "name": "replace_all", "kind": "operation", "signature": "fn replace_all(text: String, replacement: String, max_bytes: Optional[Int] = none) -\u003e Result[String, RegexError]:", "doc": "Replaces every nonoverlapping match with literal replacement text; $ and capture names are not expanded.\nmax_bytes optionally bounds UTF-8 output; negatives return InvalidInput, exhaustion LimitExceeded." } ] }, { "name": "RegexError", "doc": "Errors returned for invalid patterns or configured result limits.", "kind": "alternative", "type": "RegexError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Pattern syntax is invalid for the native RE2-compatible regular-expression engine." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A supplied match-count or output-byte budget is negative." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "More matches exist than permitted, or replacement output exceeds its byte budget." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a regular-expression-prefixed diagnostic without echoing pattern or input text.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "compile", "doc": "Compiles a regular expression. Invalid pattern syntax is returned as an error.", "kind": "fn", "type": "fn(pattern: String)-\u003eResult[Regex, RegexError]" } ] }, { "path": "@std/result.ms", "declarations": [ { "name": "Result", "doc": "Holds either a successful value (`ok`) or an expected failure (`error`).", "kind": "alternative", "type": "Result[T, E]", "type_parameters": [ "T", "E" ], "cases": [ "ok(value: T)", "error(cause: E)" ], "operations": [ "and_then[U]: fn(transform: fn(value: T)-\u003eResult[U, E])-\u003eResult[U, E]", "is_error: fn()-\u003eBool", "is_ok: fn()-\u003eBool", "map[U]: fn(transform: fn(value: T)-\u003eU)-\u003eResult[U, E]", "to_optional: fn()-\u003eOptional[T]", "unwrap: fn()-\u003eT", "unwrap_error: fn()-\u003eE", "unwrap_or: fn(fallback: T)-\u003eT", "unwrap_or_else: fn(create: fn(cause: E)-\u003eT)-\u003eT" ], "members": [ { "name": "error", "kind": "case", "signature": "case error(cause: E)", "doc": "An expected failure value; it is distinct from faults and cancellation." }, { "name": "ok", "kind": "case", "signature": "case ok(value: T)", "doc": "A successful result, retaining its payload without a deep copy." }, { "name": "error.cause", "kind": "field", "signature": "cause: E", "doc": "The original domain error, retained through compatible Result propagation." }, { "name": "ok.value", "kind": "field", "signature": "value: T", "doc": "The successful value returned by unwrap, matching, or propagation." }, { "name": "and_then[U]", "kind": "operation", "signature": "fn and_then[U](transform: fn(value: T) -\u003e Result[U, E]) -\u003e Result[U, E]:", "doc": "Calls transform only on success. Its result keeps the same error type." }, { "name": "is_error", "kind": "operation", "signature": "fn is_error() -\u003e Bool:", "doc": "Reports whether this result contains an expected error." }, { "name": "is_ok", "kind": "operation", "signature": "fn is_ok() -\u003e Bool:", "doc": "Reports whether this result contains a successful value." }, { "name": "map[U]", "kind": "operation", "signature": "fn map[U](transform: fn(value: T) -\u003e U) -\u003e Result[U, E]:", "doc": "Transforms only a successful payload, preserving an error unchanged." }, { "name": "to_optional", "kind": "operation", "signature": "fn to_optional() -\u003e Optional[T]:", "doc": "Returns some with the original success payload, or none for an error." }, { "name": "unwrap", "kind": "operation", "signature": "fn unwrap() -\u003e T:", "doc": "Returns the successful payload; faults when this is an error." }, { "name": "unwrap_error", "kind": "operation", "signature": "fn unwrap_error() -\u003e E:", "doc": "Returns the error payload; faults when this is successful." }, { "name": "unwrap_or", "kind": "operation", "signature": "fn unwrap_or(fallback: T) -\u003e T:", "doc": "Returns the successful payload, or the eagerly evaluated fallback." }, { "name": "unwrap_or_else", "kind": "operation", "signature": "fn unwrap_or_else(create: fn(cause: E) -\u003e T) -\u003e T:", "doc": "Calls create once with the original error only when this is an error." } ] } ] }, { "path": "@std/sse.ms", "declarations": [ { "name": "SseDecoder", "doc": "Incremental decoder state. Create it with `decoder`, then pass chunks to `feed` and end with `finish`.\nOnly `retry` is meant to be read; the other fields are internal state.", "kind": "record", "type": "SseDecoder", "fields": [ "limits: SseLimits", "retry: Optional[Int]", "last_id: Optional[String]", "line: BytesBuilder", "line_bytes: Int", "event_bytes: Int", "carriage: Bool", "started: Bool", "open_block: Bool", "event_type: String", "data: List[String]", "failure: Optional[SseError]", "closed: Bool" ], "members": [ { "name": "carriage", "kind": "field", "signature": "carriage: Bool", "doc": "Internal: true when the previous byte was CR, so an immediately following LF is part of the same ending." }, { "name": "closed", "kind": "field", "signature": "closed: Bool", "doc": "Internal: true after `finish`." }, { "name": "data", "kind": "field", "signature": "data: List[String]", "doc": "Internal: the pending `data:` lines." }, { "name": "event_bytes", "kind": "field", "signature": "event_bytes: Int", "doc": "Internal: bytes counted against the event budget." }, { "name": "event_type", "kind": "field", "signature": "event_type: String", "doc": "Internal: the pending `event:` value, empty when unset." }, { "name": "failure", "kind": "field", "signature": "failure: Optional[SseError]", "doc": "Internal: the first failure, repeated by later calls." }, { "name": "last_id", "kind": "field", "signature": "last_id: Optional[String]", "doc": "Internal: the last event ID, which persists across events." }, { "name": "limits", "kind": "field", "signature": "limits: SseLimits", "doc": "Limits fixed when the decoder was created." }, { "name": "line", "kind": "field", "signature": "line: BytesBuilder", "doc": "Internal: bytes of the line being assembled." }, { "name": "line_bytes", "kind": "field", "signature": "line_bytes: Int", "doc": "Internal: length of the line being assembled." }, { "name": "open_block", "kind": "field", "signature": "open_block: Bool", "doc": "Internal: true while field lines have arrived since the last blank line." }, { "name": "retry", "kind": "field", "signature": "retry: Optional[Int]", "doc": "The latest valid `retry:` value in milliseconds, or none if the stream sent none." }, { "name": "started", "kind": "field", "signature": "started: Bool", "doc": "Internal: true once the first line has been assembled and the byte order mark has been considered." } ] }, { "name": "SseError", "doc": "Errors returned for invalid input, malformed or oversized event streams, and failed reads.", "kind": "alternative", "type": "SseError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "Truncated", "ReadFailed(cause: IoError)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "A line is not valid UTF-8 text." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A supplied limit or chunk size is not positive, or the decoder was used after `finish`." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "A line or an event exceeds a supplied byte budget." }, { "name": "ReadFailed", "kind": "case", "signature": "case ReadFailed(cause: IoError)", "doc": "The underlying stream failed to read; the cause keeps its original I/O case." }, { "name": "Truncated", "kind": "case", "signature": "case Truncated", "doc": "The stream ended inside a line or before the blank line that completes an event." }, { "name": "ReadFailed.cause", "kind": "field", "signature": "cause: IoError", "doc": "The error returned by the borrowed stream." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a fixed diagnostic that does not echo stream contents.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "SseEvent", "doc": "One dispatched event, with the `message` type used when no `event:` field was sent.", "kind": "record", "type": "SseEvent", "fields": [ "event: String", "data: String", "id: Optional[String]" ], "members": [ { "name": "data", "kind": "field", "signature": "data: String", "doc": "Every `data:` line of the event joined with LF; a bare `data:` line gives an empty line." }, { "name": "event", "kind": "field", "signature": "event: String", "doc": "The event type from the last `event:` field, or `message`." }, { "name": "id", "kind": "field", "signature": "id: Optional[String]", "doc": "The last event ID in effect when the event was dispatched, or none if the stream never set one." } ] }, { "name": "SseLimits", "doc": "Optional byte budgets for one line and for one event.", "kind": "record", "type": "SseLimits", "fields": [ "max_line_bytes: Optional[Int]", "max_event_bytes: Optional[Int]" ], "members": [ { "name": "max_event_bytes", "kind": "field", "signature": "max_event_bytes: Optional[Int] = none", "doc": "Largest total of all field lines in one event, excluding line endings and comments; none adds no budget." }, { "name": "max_line_bytes", "kind": "field", "signature": "max_line_bytes: Optional[Int] = none", "doc": "Largest line in bytes, excluding its line ending; none adds no budget." } ] }, { "name": "SseReader", "doc": "Pulls events from a borrowed ReadStream. The reader never closes the stream:\nits owner closes it, and closing it makes a blocked read fail with ReadFailed.", "kind": "record", "type": "SseReader", "fields": [ "input: ReadStream", "decoder: SseDecoder", "ready: List[SseEvent]", "next: Int", "chunk_bytes: Optional[Int]", "finished: Bool" ], "members": [ { "name": "chunk_bytes", "kind": "field", "signature": "chunk_bytes: Optional[Int]", "doc": "Internal: requested read size, none for the stream default." }, { "name": "decoder", "kind": "field", "signature": "decoder: SseDecoder", "doc": "The decoder, whose `retry` is readable between events." }, { "name": "finished", "kind": "field", "signature": "finished: Bool", "doc": "Internal: true after a clean end of stream." }, { "name": "input", "kind": "field", "signature": "input: ReadStream", "doc": "The borrowed stream, such as an HTTP response body." }, { "name": "next", "kind": "field", "signature": "next: Int", "doc": "Internal: index of the next ready event." }, { "name": "ready", "kind": "field", "signature": "ready: List[SseEvent]", "doc": "Internal: events decoded but not yet returned." } ] }, { "name": "borrow_body", "doc": "Views an HTTP response body as a ReadStream that the response keeps owning.\nClosing the view does nothing, so close the body itself, usually with `with`.", "kind": "fn", "type": "fn(body: ResponseBody)-\u003eReadStream" }, { "name": "decoder", "doc": "Creates a decoder. Supplied limits must be positive.", "kind": "fn", "type": "fn(limits: SseLimits = ...)-\u003eResult[SseDecoder, SseError]" }, { "name": "feed", "doc": "Decodes one chunk and returns the events it completed, in order.\nChunks may split any line, line ending or UTF-8 scalar. An error is final for the decoder.", "kind": "fn", "type": "fn(decoder: SseDecoder, chunk: Bytes)-\u003eResult[List[SseEvent], SseError]" }, { "name": "finish", "doc": "Ends the stream. A stream with no partial line and no unfinished event ends cleanly;\notherwise the result is Truncated and the unfinished event is never dispatched.", "kind": "fn", "type": "fn(decoder: SseDecoder)-\u003eResult[Unit, SseError]" }, { "name": "next_event", "doc": "Returns the next event, or none after a clean end of stream.\nA read failure, malformed line, exceeded limit or truncated event is an error.", "kind": "fn", "type": "fn(reader: SseReader)-\u003eResult[Optional[SseEvent], SseError]" }, { "name": "reader", "doc": "Wraps a stream in an event reader. Supplied limits and chunk size must be positive.", "kind": "fn", "type": "fn(input: ReadStream, limits: SseLimits = ..., chunk_bytes: Optional[Int] = ...)-\u003eResult[SseReader, SseError]" } ] }, { "path": "@std/string.ms", "declarations": [ { "name": "NormalizationForm", "doc": "The four Unicode normalization forms, selected without runtime string spelling errors.", "kind": "alternative", "type": "NormalizationForm", "cases": [ "Nfc", "Nfd", "Nfkc", "Nfkd" ], "operations": [ "normalize: fn(text: String, max_bytes: Optional[Int] = ...)-\u003eResult[String, StringError]" ], "members": [ { "name": "Nfc", "kind": "case", "signature": "case Nfc", "doc": "Canonical decomposition followed by canonical recomposition where Unicode permits it." }, { "name": "Nfd", "kind": "case", "signature": "case Nfd", "doc": "Canonical decomposition with combining marks placed in canonical order." }, { "name": "Nfkc", "kind": "case", "signature": "case Nfkc", "doc": "Compatibility decomposition followed by canonical recomposition where Unicode permits it." }, { "name": "Nfkd", "kind": "case", "signature": "case Nfkd", "doc": "Compatibility decomposition with combining marks placed in canonical order." }, { "name": "normalize", "kind": "operation", "signature": "fn normalize(text: String, max_bytes: Optional[Int] = none) -\u003e Result[String, StringError]:", "doc": "Normalizes text with the existing String.normalize budgets and StringError cases.\nOmission or none adds no output budget; a supplied budget counts UTF-8 bytes." } ] }, { "name": "StringBuilder", "doc": "Mutable builder for constructing a string without repeated intermediate copies.", "kind": "native", "type": "StringBuilder", "operations": [ "append: fn(value: String)-\u003eUnit", "freeze: fn()-\u003eString" ], "members": [ { "name": "append", "kind": "operation", "signature": "fn append(value: String) -\u003e Unit:", "doc": "Appends the supplied text in order; mutation after freeze raises a sealed-builder fault." }, { "name": "freeze", "kind": "operation", "signature": "fn freeze() -\u003e String:", "doc": "Seals the builder and returns immutable text; repeated freeze returns the same text value." } ] }, { "name": "StringError", "doc": "Errors returned by Unicode scalar conversions and bounded string operations.", "kind": "alternative", "type": "StringError", "cases": [ "InvalidInput", "OutOfRange", "LimitExceeded", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "A string-domain failure with an explicit diagnostic supplied by an implementation." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Scalar values, normalization form or a supplied repeat/padding/output budget is invalid." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "UTF-8 output exceeds a supplied byte budget or the native string allocation limit." }, { "name": "OutOfRange", "kind": "case", "signature": "case OutOfRange", "doc": "A strict scalar slice bound lies outside the string or its range is inverted." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Original diagnostic text, returned unchanged by message()." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns original Failed text, or a string-prefixed diagnostic for other cases.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "from_scalars", "doc": "Builds text from Unicode scalar values. Invalid scalars return `InvalidInput`.", "kind": "fn", "type": "fn(values: List[Int])-\u003eResult[String, StringError]" } ] }, { "path": "@std/sync.ms", "declarations": [ { "name": "Synchronized", "doc": "Protects a value shared across tasks. Lock before reading or updating the value.", "kind": "native", "type": "Synchronized[T]", "type_parameters": [ "T" ], "fields": [ "value: T" ], "operations": [ "lock: fn()-\u003eSynchronizedGuard[T]" ], "members": [ { "name": "value", "kind": "field", "signature": "value: T", "doc": "Initial constructor payload; retain its mutable aliases only with the same guarded access policy." }, { "name": "lock", "kind": "operation", "signature": "fn lock() -\u003e SynchronizedGuard[T]:", "doc": "Waits for an exclusive guard; caller cancellation interrupts a pending acquisition.\nKeep the guard in a with scope so every exit releases it." } ] }, { "name": "SynchronizedGuard", "doc": "Holds a synchronization lock. Closing the guard releases the lock.", "kind": "native", "type": "SynchronizedGuard[T]", "type_parameters": [ "T" ], "operations": [ "close: fn()-\u003eUnit", "get: fn()-\u003eT", "notify_all: fn()-\u003eUnit", "set: fn(value: T)-\u003eUnit", "wait: fn()-\u003eUnit" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit:", "doc": "Releases the lock for every alias of this guard; repeated close does nothing." }, { "name": "get", "kind": "operation", "signature": "fn get() -\u003e T:", "doc": "Returns the original guarded payload, without cloning; a closed guard faults." }, { "name": "notify_all", "kind": "operation", "signature": "fn notify_all() -\u003e Unit:", "doc": "Call it after changing the shared value so waiting tasks re-check it. It wakes every task waiting on this Synchronized; the guard must be open and owned by the caller." }, { "name": "set", "kind": "operation", "signature": "fn set(value: T) -\u003e Unit:", "doc": "Replaces the guarded payload without copying it; a closed guard faults." }, { "name": "wait", "kind": "operation", "signature": "fn wait() -\u003e Unit:", "doc": "Releases the lock, waits for notify_all, then reacquires it before returning; re-check state in a loop.\nUse it in a loop, such as: while queue_is_empty: locked.wait(). Only the acquiring task may call it. Cancellation interrupts the wait without reacquiring, leaving the guard released." } ] } ] }, { "path": "@std/system.ms", "declarations": [ { "name": "CpuInfo", "doc": "Model, integer MHz speed (fractional MHz truncated), and cumulative integer millisecond\ncounters for one logical CPU. irq includes hardware and software interrupt time.", "kind": "record", "type": "CpuInfo", "fields": [ "model: String", "speed_mhz: Int", "user: Int", "nice: Int", "system: Int", "idle: Int", "irq: Int" ], "members": [ { "name": "idle", "kind": "field", "signature": "idle: Int", "doc": "Cumulative milliseconds this logical CPU spent idle." }, { "name": "irq", "kind": "field", "signature": "irq: Int", "doc": "Cumulative milliseconds this logical CPU spent servicing hardware and software interrupts." }, { "name": "model", "kind": "field", "signature": "model: String", "doc": "Marketing name of the processor, such as `Intel(R) Core(TM) i7`; it can be empty where the host does not report one." }, { "name": "nice", "kind": "field", "signature": "nice: Int", "doc": "Cumulative milliseconds this logical CPU spent running low-priority (niced) user processes." }, { "name": "speed_mhz", "kind": "field", "signature": "speed_mhz: Int", "doc": "Integer megahertz, not a time interval." }, { "name": "system", "kind": "field", "signature": "system: Int", "doc": "Cumulative milliseconds this logical CPU spent running kernel code." }, { "name": "user", "kind": "field", "signature": "user: Int", "doc": "The user, nice, system, idle, and irq fields are cumulative milliseconds." } ] }, { "name": "NetworkInterface", "doc": "Address and link metadata for one host network interface.", "kind": "record", "type": "NetworkInterface", "fields": [ "name: String", "address: String", "netmask: String", "family: IpFamily", "mac: String", "internal: Bool", "scope_id: Int" ], "members": [ { "name": "address", "kind": "field", "signature": "address: String", "doc": "The interface's IP address in textual form, such as `192.168.1.5` or `fe80::1`." }, { "name": "family", "kind": "field", "signature": "family: IpFamily", "doc": "The IPv4/IPv6 alternative for the native address record." }, { "name": "internal", "kind": "field", "signature": "internal: Bool", "doc": "True for a loopback interface, which only reaches the local host." }, { "name": "mac", "kind": "field", "signature": "mac: String", "doc": "Hardware address as colon-separated lowercase hexadecimal, or an empty string for interfaces without one such as loopback." }, { "name": "name", "kind": "field", "signature": "name: String", "doc": "Host name of the interface, such as `eth0` or `lo0`. Interfaces with several addresses appear once per address." }, { "name": "netmask", "kind": "field", "signature": "netmask: String", "doc": "The address's network mask in the same textual form as `address`, such as `255.255.255.0`." }, { "name": "scope_id", "kind": "field", "signature": "scope_id: Int", "doc": "The operating system's numeric index for the interface, as used to select an interface for link-local IPv6 addresses." } ] }, { "name": "System", "doc": "Read-only host details and selected controls for the current operating system.", "kind": "interface", "type": "System", "operations": [ "cpus: fn()-\u003eResult[List[CpuInfo], SystemError]", "environment: fn(name: String)-\u003eOptional[String]", "get_priority: fn(pid: Int)-\u003eResult[Int, SystemError]", "home_directory: fn()-\u003eResult[String, SystemError]", "hostname: fn()-\u003eResult[String, SystemError]", "info: fn()-\u003eSystemInfo", "machine: fn()-\u003eResult[String, SystemError]", "metrics: fn()-\u003eResult[SystemMetrics, SystemError]", "network_interfaces: fn()-\u003eResult[List[NetworkInterface], SystemError]", "os_release: fn()-\u003eResult[String, SystemError]", "os_version: fn()-\u003eResult[String, SystemError]", "set_priority: fn(pid: Int, priority: Int)-\u003eResult[Unit, SystemError]", "temporary_directory: fn()-\u003eResult[String, SystemError]", "user_info: fn()-\u003eResult[UserInfo, SystemError]", "working_directory: fn()-\u003eString" ], "members": [ { "name": "cpus", "kind": "operation", "signature": "fn cpus() -\u003e Result[List[CpuInfo], SystemError]", "doc": "Returns one CpuInfo per logical CPU with its model, clock speed, and cumulative time counters." }, { "name": "environment", "kind": "operation", "signature": "fn environment(name: String) -\u003e Optional[String]", "doc": "Reads the live variable; absent or non-UTF-8 values return none." }, { "name": "get_priority", "kind": "operation", "signature": "fn get_priority(pid: Int) -\u003e Result[Int, SystemError]", "doc": "Returns the scheduling priority of process `pid` (0 means the calling process) as a nice-style value, from -20 for highest to 19 for lowest. Windows maps its priority classes onto this range.\nA pid outside 0 through 2147483647 returns InvalidInput, and platforms without priorities return Unsupported." }, { "name": "home_directory", "kind": "operation", "signature": "fn home_directory() -\u003e Result[String, SystemError]", "doc": "Returns the current user's home directory path, from the host's environment or account database.\nA path that is not valid UTF-8 returns Unsupported." }, { "name": "hostname", "kind": "operation", "signature": "fn hostname() -\u003e Result[String, SystemError]", "doc": "Returns the host's name as reported by the operating system.\nA name that is not valid UTF-8 returns Unsupported." }, { "name": "info", "kind": "operation", "signature": "fn info() -\u003e SystemInfo", "doc": "Returns the operating system name, processor architecture, and logical CPU count for this host." }, { "name": "machine", "kind": "operation", "signature": "fn machine() -\u003e Result[String, SystemError]", "doc": "Returns the hardware architecture in `uname -m` style, such as `x86_64`, `aarch64`, or `i686`; other architectures use their Go name." }, { "name": "metrics", "kind": "operation", "signature": "fn metrics() -\u003e Result[SystemMetrics, SystemError]", "doc": "Returns memory sizes in bytes, host uptime, load averages, and available parallelism in one snapshot.\nA host query failure returns the matching SystemError." }, { "name": "network_interfaces", "kind": "operation", "signature": "fn network_interfaces() -\u003e Result[List[NetworkInterface], SystemError]", "doc": "Returns one NetworkInterface for every address on every interface, including loopback.\nAn interface name that is not valid UTF-8 returns Unsupported." }, { "name": "os_release", "kind": "operation", "signature": "fn os_release() -\u003e Result[String, SystemError]", "doc": "Returns the kernel release string, such as `6.1.0-18-amd64`, with surrounding whitespace removed.\nReturns Unsupported where the host does not expose it." }, { "name": "os_version", "kind": "operation", "signature": "fn os_version() -\u003e Result[String, SystemError]", "doc": "Returns the kernel build or version string, such as `#1 SMP Debian`, with surrounding whitespace removed.\nReturns Unsupported where the host does not expose it." }, { "name": "set_priority", "kind": "operation", "signature": "fn set_priority(pid: Int, priority: Int) -\u003e Result[Unit, SystemError]", "doc": "Accepts pid 0..2147483647 and priority -20..19 (lower is higher priority).\nUnix uses nice values; Windows maps ranges to native priority classes." }, { "name": "temporary_directory", "kind": "operation", "signature": "fn temporary_directory() -\u003e Result[String, SystemError]", "doc": "Queries the host temp root without creating or checking a directory; non-UTF-8 returns Unsupported." }, { "name": "user_info", "kind": "operation", "signature": "fn user_info() -\u003e Result[UserInfo, SystemError]", "doc": "Returns the current user's name, numeric ids, home directory, and login shell.\nThe shell is empty when the host does not record one, and text that is not valid UTF-8 returns Unsupported." }, { "name": "working_directory", "kind": "operation", "signature": "fn working_directory() -\u003e String", "doc": "Reads the live native directory; an OS query failure faults because this API has no Result.\nA host service constructed with an explicit directory retains that base." } ] }, { "name": "SystemError", "doc": "Errors returned when a requested host operation is unavailable or denied.", "kind": "alternative", "type": "SystemError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "NotFound", "AlreadyExists", "PermissionDenied", "Unsupported", "Closed", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "AlreadyExists", "kind": "case", "signature": "case AlreadyExists", "doc": "The host reported that the target already exists." }, { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "Reserved for operations on a closed system handle; the current operations do not return it." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "The host reported another failure while querying or changing system state." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "Host data could not be interpreted; reserved for malformed host answers." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A pid is outside 0 through 2147483647, a priority is outside -20 through 19, or the host rejected an argument." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Reserved for results beyond a configured bound; the current operations do not return it." }, { "name": "NotFound", "kind": "case", "signature": "case NotFound", "doc": "The host reported that the target does not exist." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "The host refused the operation for lack of privilege, such as raising another process's priority." }, { "name": "Unsupported", "kind": "case", "signature": "case Unsupported", "doc": "The host or platform cannot provide the value, or the value is not valid UTF-8 and cannot become a String." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name paths." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `system: \u003creason\u003e`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "SystemInfo", "doc": "Operating system and processor architecture for the current host.", "kind": "record", "type": "SystemInfo", "fields": [ "os: String", "architecture: String", "cpu_count: Int" ], "members": [ { "name": "architecture", "kind": "field", "signature": "architecture: String", "doc": "The processor architecture in Go's naming, such as `amd64`, `arm64`, or `386`." }, { "name": "cpu_count", "kind": "field", "signature": "cpu_count: Int", "doc": "Number of logical CPUs the operating system reports as present for this process." }, { "name": "os", "kind": "field", "signature": "os: String", "doc": "Native Go OS identifier, such as linux, darwin, or windows; an open host identifier set." } ] }, { "name": "SystemMetrics", "doc": "Host measurements: memory fields are bytes; load_average is 1/5/15-minute load\n(three zeros on Windows); available_parallelism is a usable logical-processor count.", "kind": "record", "type": "SystemMetrics", "fields": [ "total_memory: Int", "free_memory: Int", "available_memory: Int", "uptime: Duration", "load_average: List[Float]", "available_parallelism: Int" ], "members": [ { "name": "available_memory", "kind": "field", "signature": "available_memory: Int", "doc": "Estimated physical memory in bytes that new work can use without swapping, including reclaimable caches." }, { "name": "available_parallelism", "kind": "field", "signature": "available_parallelism: Int", "doc": "Logical processors this process may run on, which can be fewer than `SystemInfo.cpu_count` under CPU affinity limits." }, { "name": "free_memory", "kind": "field", "signature": "free_memory: Int", "doc": "Physical memory in bytes that is completely unused; caches count as used, so it is usually smaller than `available_memory`." }, { "name": "load_average", "kind": "field", "signature": "load_average: List[Float]", "doc": "Three Floats for the 1, 5, and 15 minute system load averages; all 0.0 on Windows." }, { "name": "total_memory", "kind": "field", "signature": "total_memory: Int", "doc": "Installed physical memory in bytes." }, { "name": "uptime", "kind": "field", "signature": "uptime: Duration", "doc": "Host boot uptime as a Duration with whole-second native resolution; not process uptime." } ] }, { "name": "UserInfo", "doc": "User name, numeric identity, home directory, and login shell.", "kind": "record", "type": "UserInfo", "fields": [ "username: String", "uid: Int", "gid: Int", "home: String", "shell: String" ], "members": [ { "name": "gid", "kind": "field", "signature": "gid: Int", "doc": "Numeric primary group id of the current user; -1 on Windows, where ids are not numeric." }, { "name": "home", "kind": "field", "signature": "home: String", "doc": "Absolute path of the user's home directory from the account database." }, { "name": "shell", "kind": "field", "signature": "shell: String", "doc": "Path of the user's login shell, or an empty string when the host records none." }, { "name": "uid", "kind": "field", "signature": "uid: Int", "doc": "Numeric user id of the current user; -1 on Windows, where ids are not numeric." }, { "name": "username", "kind": "field", "signature": "username: String", "doc": "Login name of the current user." } ] }, { "name": "constants", "doc": "Returns native signal/error/loader/priority constants by name.\nNames and values vary by host; missing entries do not imply a portable numeric default.", "kind": "fn", "type": "fn()-\u003eMap[String, Int]" }, { "name": "dev_null", "doc": "Returns the conventional null-device path for the host.", "kind": "fn", "type": "fn()-\u003eString" }, { "name": "end_of_line", "doc": "Returns the host's line-ending sequence.", "kind": "fn", "type": "fn()-\u003eString" }, { "name": "endianness", "doc": "Returns exactly `LE` or `BE` for the host's native byte order.", "kind": "fn", "type": "fn()-\u003eString" }, { "name": "os_type", "doc": "Returns Linux, Darwin, or Windows_NT on the supported hosts; other hosts use their Go OS name.", "kind": "fn", "type": "fn()-\u003eString" }, { "name": "system", "doc": "Returns system information and controls for the current host.", "kind": "fn", "type": "fn()-\u003eSystem" } ] }, { "path": "@std/tasks.ms", "declarations": [ { "name": "ExecutionError", "doc": "Why a task or task group did not complete successfully.", "kind": "alternative", "type": "ExecutionError", "cases": [ "Timeout", "Cancelled", "Crashed(operation: OperationId, message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Cancelled", "kind": "case", "signature": "case Cancelled", "doc": "The group was closed or the surrounding task was cancelled before all tasks completed." }, { "name": "Crashed", "kind": "case", "signature": "case Crashed(operation: OperationId, message: String)", "doc": "A task raised a fault. It takes precedence over Timeout and Cancelled when several failures occur." }, { "name": "Timeout", "kind": "case", "signature": "case Timeout", "doc": "The group's `timeout` elapsed while tasks were still running, and they were cancelled." }, { "name": "Crashed.message", "kind": "field", "signature": "message: String", "doc": "Text of the fault that ended the task." }, { "name": "Crashed.operation", "kind": "field", "signature": "operation: OperationId", "doc": "Id of the task that faulted." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fault text verbatim for Crashed, and otherwise the fixed diagnostic `task execution: \u003creason\u003e`, such as `task execution: operation timed out`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "OperationId", "doc": "Opaque identifier used to inspect, cancel, or restart scheduled work.", "kind": "native", "type": "OperationId" }, { "name": "Scheduler", "doc": "Runs immediate, delayed, and repeating operations with explicit cancellation.", "kind": "native", "type": "Scheduler", "fields": [ "limit: Optional[Int]", "history_limit: Optional[Int]", "drain: Optional[Duration]", "reporter: Optional[fn(failure: SchedulerFailure)-\u003eUnit]" ], "operations": [ "after: fn(duration: Duration, operation: fn()-\u003eResult[Unit, Error])-\u003eResult[OperationId, StartError]", "cancel: fn(id: OperationId)-\u003eUnit", "close: fn()-\u003eUnit", "every: fn(interval: Duration, operation: fn()-\u003eResult[Unit, Error])-\u003eResult[OperationId, StartError]", "restart: fn(id: OperationId)-\u003eResult[OperationId, StartError]", "start: fn(operation: fn()-\u003eResult[Unit, Error])-\u003eResult[OperationId, StartError]", "status: fn(id: OperationId)-\u003eWorkStatus" ], "members": [ { "name": "drain", "kind": "field", "signature": "drain: Optional[Duration] = none", "doc": "How long `close` lets running operations finish on their own before cancelling them. none or a zero duration cancels immediately. A negative duration faults." }, { "name": "history_limit", "kind": "field", "signature": "history_limit: Optional[Int] = none", "doc": "How many finished operations keep a queryable final status. none keeps every one, and 0 keeps none, so `status` reports Unknown and `restart` rejects the id once the operation ends.\nA positive count evicts the oldest finished operation first." }, { "name": "limit", "kind": "field", "signature": "limit: Optional[Int] = none", "doc": "Maximum number of operations running at once; `start`, `after`, and `every` return Full beyond it. Must be at least 1.\nAlso bounds queued failure reports awaiting the reporter. none leaves both unbounded." }, { "name": "reporter", "kind": "field", "signature": "reporter: Optional[fn(failure: SchedulerFailure) -\u003e Unit] = none", "doc": "Called with a SchedulerFailure for each operation that returns an error or faults, one report at a time and in completion order.\nnone writes a one-line diagnostic to standard error instead. A reporter fault is also written to standard error, and the reporter cannot close its own scheduler." }, { "name": "after", "kind": "operation", "signature": "fn after(duration: Duration, operation: fn() -\u003e Result[Unit, Error]) -\u003e Result[OperationId, StartError]:", "doc": "Runs `operation` once after `duration` has elapsed and returns its OperationId. A zero duration runs it as soon as it is scheduled.\nA negative duration returns InvalidInput; a closing scheduler returns Closed and a full one returns Full. Cancelling during the wait prevents the call." }, { "name": "cancel", "kind": "operation", "signature": "fn cancel(id: OperationId) -\u003e Unit:", "doc": "Requests cancellation of a running operation and returns without waiting for it to stop; the final status becomes Cancelled.\nAn unknown or already finished id is ignored." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit:", "doc": "Stops accepting work, waits up to `drain` for running operations, cancels the rest, and waits for them and for pending failure reports to finish.\nCalling it again waits for the first close to complete. An operation or reporter of this scheduler calling close faults." }, { "name": "every", "kind": "operation", "signature": "fn every(interval: Duration, operation: fn() -\u003e Result[Unit, Error]) -\u003e Result[OperationId, StartError]:", "doc": "Runs `operation` repeatedly, sleeping `interval` before the first run and again after each run finishes, so runs never overlap.\nIt stops after the first operation that returns an error, which is reported as Failed. A zero or negative interval returns InvalidInput; Closed and Full apply as for `after`." }, { "name": "restart", "kind": "operation", "signature": "fn restart(id: OperationId) -\u003e Result[OperationId, StartError]:", "doc": "Cancels the operation `id` if it is still running, waits for it to stop, and schedules a new run with the same delay, repeat mode, and callback. Returns the new OperationId; the old id keeps its final status.\nOnly work created by `after` or `every` can restart. An unknown, evicted, or `start`-created id returns InvalidInput, and a closing scheduler returns Closed. An operation of this scheduler calling restart faults." }, { "name": "start", "kind": "operation", "signature": "fn start(operation: fn() -\u003e Result[Unit, Error]) -\u003e Result[OperationId, StartError]:", "doc": "Runs `operation` right away as a background task and returns its OperationId.\nReturns Closed after `close` begins and Full when `limit` operations are already running. An Err result is reported as Failed and a fault as Crashed." }, { "name": "status", "kind": "operation", "signature": "fn status(id: OperationId) -\u003e WorkStatus:", "doc": "Returns the operation's current status, or its final status once it has ended.\nUnknown means the id was never issued by this scheduler, was evicted by `history_limit`, or finished while `history_limit` was 0." } ] }, { "name": "SchedulerFailure", "doc": "A scheduled operation that returned an error or raised a fault.", "kind": "alternative", "type": "SchedulerFailure", "cases": [ "Failed(operation: OperationId, cause: Error)", "Crashed(operation: OperationId, message: String)" ], "members": [ { "name": "Crashed", "kind": "case", "signature": "case Crashed(operation: OperationId, message: String)", "doc": "The operation raised a fault, such as an index error or failed precondition, instead of returning." }, { "name": "Failed", "kind": "case", "signature": "case Failed(operation: OperationId, cause: Error)", "doc": "The operation returned `Err`; delivered to the scheduler's reporter." }, { "name": "Crashed.message", "kind": "field", "signature": "message: String", "doc": "Text of the fault that ended the operation." }, { "name": "Crashed.operation", "kind": "field", "signature": "operation: OperationId", "doc": "Id of the operation that faulted." }, { "name": "Failed.cause", "kind": "field", "signature": "cause: Error", "doc": "The error the operation returned." }, { "name": "Failed.operation", "kind": "field", "signature": "operation: OperationId", "doc": "Id of the failed operation, as returned when it was started." } ] }, { "name": "StartError", "doc": "Why a scheduler could not start an operation.", "kind": "alternative", "type": "StartError", "cases": [ "Closed", "Full", "InvalidInput" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The scheduler is closing or closed and accepts no more work." }, { "name": "Full", "kind": "case", "signature": "case Full", "doc": "The scheduler already has `limit` operations running." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A delay is negative, a repeat interval is not positive, or a restart id is unknown or not restartable." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `scheduler: \u003creason\u003e`, such as `scheduler: capacity exhausted`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "Task", "doc": "A handle to a child task. Join it to collect its result and observe failures.", "kind": "native", "type": "Task[T]", "type_parameters": [ "T" ], "operations": [ "join: fn()-\u003eResult[T, ExecutionError]" ], "members": [ { "name": "join", "kind": "operation", "signature": "fn join() -\u003e Result[T, ExecutionError]:", "doc": "Waits for the task and returns its result. If the task did not complete, returns the group's failure after sibling tasks finish cleanup.\nJoining from inside the same group faults." } ] }, { "name": "TaskGroup", "doc": "Starts child tasks and joins them together with an optional group timeout.", "kind": "native", "type": "TaskGroup", "fields": [ "timeout: Optional[Duration]" ], "operations": [ "close: fn()-\u003eUnit", "join: fn()-\u003eResult[Unit, ExecutionError]", "start[T]: fn(operation: fn()-\u003eT)-\u003eTask[T]" ], "members": [ { "name": "timeout", "kind": "field", "signature": "timeout: Optional[Duration] = none", "doc": "Time budget for all tasks in the group, measured from the first `start`. When it elapses with tasks still running, they are cancelled and `join` returns Timeout.\nA zero duration expires immediately, none sets no limit, and a negative duration faults." }, { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit:", "doc": "Cancels unfinished tasks, waits for them, and releases the group; calling it again waits for the first close.\nA task fault no `join` has observed is raised as a fault here, unless the surrounding task is itself being cancelled. A task of this group calling close faults." }, { "name": "join", "kind": "operation", "signature": "fn join() -\u003e Result[Unit, ExecutionError]:", "doc": "Seals the group against new tasks and waits for every task to finish, including cleanup. Returns Ok when all succeeded, or the group's first failure, with Crashed taking precedence.\nA task or descendant calling join on its own group faults." }, { "name": "start[T]", "kind": "operation", "signature": "fn start[T](operation: fn() -\u003e T) -\u003e Task[T]:", "doc": "Starts `operation` as a concurrent child task and returns its handle without waiting.\nStarting after `join` or `close` faults. After the group has failed or been cancelled, the operation is not run and its handle reports the group failure." } ] }, { "name": "WorkStatus", "doc": "Current or final state of a scheduled operation.", "kind": "alternative", "type": "WorkStatus", "cases": [ "Running", "Succeeded", "Failed", "Cancelled", "Crashed", "Unknown" ], "members": [ { "name": "Cancelled", "kind": "case", "signature": "case Cancelled", "doc": "The operation was cancelled by `cancel`, `restart`, `close`, or the surrounding task before it finished." }, { "name": "Crashed", "kind": "case", "signature": "case Crashed", "doc": "The operation raised a fault; the fault was sent to the reporter." }, { "name": "Failed", "kind": "case", "signature": "case Failed", "doc": "The operation returned `Err`; the error was sent to the reporter." }, { "name": "Running", "kind": "case", "signature": "case Running", "doc": "The operation has started and not yet finished." }, { "name": "Succeeded", "kind": "case", "signature": "case Succeeded", "doc": "The operation returned `Ok`." }, { "name": "Unknown", "kind": "case", "signature": "case Unknown", "doc": "The id was not issued by this scheduler or its final status was not retained under `history_limit`." } ] }, { "name": "check_cancelled", "doc": "Raises the cancellation fault when the current task has been cancelled.", "kind": "fn", "type": "fn()-\u003eUnit" }, { "name": "yield_now", "doc": "Suspends the current task briefly so other ready work can run.", "kind": "fn", "type": "fn()-\u003eUnit" } ] }, { "path": "@std/time.ms", "declarations": [ { "name": "Clock", "doc": "A monotonic clock whose readings are suitable for measuring elapsed time.", "kind": "interface", "type": "Clock", "operations": [ "now: fn()-\u003eInstant" ], "members": [ { "name": "now", "kind": "operation", "signature": "fn now() -\u003e Instant", "doc": "Returns the current reading of this monotonic clock.\nReadings are only comparable with others from the same clock and do not correspond to a calendar date." } ] }, { "name": "Duration", "doc": "A span of elapsed time.", "kind": "native", "type": "Duration", "operations": [ "abs: fn()-\u003eDuration", "add: fn(other: Duration)-\u003eDuration", "compare: fn(other: Duration)-\u003eInt", "divide: fn(divisor: Int)-\u003eDuration", "multiply: fn(factor: Int)-\u003eDuration", "negate: fn()-\u003eDuration", "subtract: fn(other: Duration)-\u003eDuration", "to_hours: fn()-\u003eFloat", "to_microseconds: fn()-\u003eInt", "to_milliseconds: fn()-\u003eInt", "to_minutes: fn()-\u003eFloat", "to_nanoseconds: fn()-\u003eInt", "to_seconds: fn()-\u003eFloat" ], "members": [ { "name": "abs", "kind": "operation", "signature": "fn abs() -\u003e Duration:", "doc": "Returns the absolute value; the minimum Duration faults." }, { "name": "add", "kind": "operation", "signature": "fn add(other: Duration) -\u003e Duration:", "doc": "Adds signed nanoseconds; a result outside Duration's representable range faults." }, { "name": "compare", "kind": "operation", "signature": "fn compare(other: Duration) -\u003e Int:", "doc": "Returns -1, 0, or 1." }, { "name": "divide", "kind": "operation", "signature": "fn divide(divisor: Int) -\u003e Duration:", "doc": "Divides by a nonzero integer, truncating toward zero; zero faults." }, { "name": "multiply", "kind": "operation", "signature": "fn multiply(factor: Int) -\u003e Duration:", "doc": "Multiplies by an integer factor; overflow faults." }, { "name": "negate", "kind": "operation", "signature": "fn negate() -\u003e Duration:", "doc": "Negates this duration; the minimum Duration faults." }, { "name": "subtract", "kind": "operation", "signature": "fn subtract(other: Duration) -\u003e Duration:", "doc": "Subtracts signed nanoseconds; a result outside Duration's representable range faults." }, { "name": "to_hours", "kind": "operation", "signature": "fn to_hours() -\u003e Float:", "doc": "Converts this duration to floating-point hours." }, { "name": "to_microseconds", "kind": "operation", "signature": "fn to_microseconds() -\u003e Int:", "doc": "Converts this duration to an integer number of microseconds." }, { "name": "to_milliseconds", "kind": "operation", "signature": "fn to_milliseconds() -\u003e Int:", "doc": "Converts this duration to an integer number of milliseconds." }, { "name": "to_minutes", "kind": "operation", "signature": "fn to_minutes() -\u003e Float:", "doc": "Converts this duration to floating-point minutes." }, { "name": "to_nanoseconds", "kind": "operation", "signature": "fn to_nanoseconds() -\u003e Int:", "doc": "Converts this duration to an integer number of nanoseconds." }, { "name": "to_seconds", "kind": "operation", "signature": "fn to_seconds() -\u003e Float:", "doc": "Converts this duration to floating-point seconds." } ] }, { "name": "Instant", "doc": "An instant on a monotonic clock; it is not a calendar timestamp.", "kind": "native", "type": "Instant", "operations": [ "compare: fn(other: Instant)-\u003eInt", "difference: fn(other: Instant)-\u003eDuration", "shift: fn(duration: Duration)-\u003eInstant" ], "members": [ { "name": "compare", "kind": "operation", "signature": "fn compare(other: Instant) -\u003e Int:", "doc": "Returns -1, 0, or 1; instants from different clock domains fault." }, { "name": "difference", "kind": "operation", "signature": "fn difference(other: Instant) -\u003e Duration:", "doc": "Returns the elapsed duration from `right` to this instant." }, { "name": "shift", "kind": "operation", "signature": "fn shift(duration: Duration) -\u003e Instant:", "doc": "Shifts this monotonic instant by a duration." } ] }, { "name": "TimeError", "doc": "Errors returned by timestamp parsing, arithmetic, or range conversion.", "kind": "alternative", "type": "TimeError", "cases": [ "InvalidInput", "Closed", "InvalidData", "OutOfRange" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "Reserved for time operations on a closed resource; the current native time operations do not return it." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "The text is not an RFC 3339 timestamp with a four-digit year, full date and time, and an explicit `Z` or `+hh:mm` offset." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Reserved for invalid time arguments; the current native time operations do not return it." }, { "name": "OutOfRange", "kind": "case", "signature": "case OutOfRange", "doc": "A nanosecond component is outside 0 through 999999999, or the result falls outside years 1 through 9999 or cannot be represented as a Duration." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `time: \u003creason\u003e`, such as `time: value out of range`, without echoing the input text.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "Timestamp", "doc": "A wall-clock time with Unix seconds and nanoseconds.", "kind": "native", "type": "Timestamp", "operations": [ "compare: fn(other: Timestamp)-\u003eInt", "difference: fn(other: Timestamp)-\u003eResult[Duration, TimeError]", "nanoseconds: fn()-\u003eInt", "shift: fn(duration: Duration)-\u003eResult[Timestamp, TimeError]", "to_string: fn()-\u003eString", "unix_seconds: fn()-\u003eInt" ], "members": [ { "name": "compare", "kind": "operation", "signature": "fn compare(other: Timestamp) -\u003e Int:", "doc": "Returns -1, 0, or 1 across the full calendar range." }, { "name": "difference", "kind": "operation", "signature": "fn difference(other: Timestamp) -\u003e Result[Duration, TimeError]:", "doc": "Returns `self - right` as a duration." }, { "name": "nanoseconds", "kind": "operation", "signature": "fn nanoseconds() -\u003e Int:", "doc": "Returns this timestamp's nanosecond component." }, { "name": "shift", "kind": "operation", "signature": "fn shift(duration: Duration) -\u003e Result[Timestamp, TimeError]:", "doc": "Adds a duration to this wall-clock timestamp." }, { "name": "to_string", "kind": "operation", "signature": "fn to_string() -\u003e String:", "doc": "Formats this timestamp in RFC 3339 form." }, { "name": "unix_seconds", "kind": "operation", "signature": "fn unix_seconds() -\u003e Int:", "doc": "Returns the whole Unix seconds represented by this timestamp." } ] }, { "name": "WallClock", "doc": "A clock that reports calendar time.", "kind": "interface", "type": "WallClock", "operations": [ "now: fn()-\u003eTimestamp" ], "members": [ { "name": "now", "kind": "operation", "signature": "fn now() -\u003e Timestamp", "doc": "Returns the current calendar time as a UTC Timestamp with nanosecond precision.\nIt can jump when the system clock is adjusted, so use Clock for elapsed time." } ] }, { "name": "clock", "doc": "Returns the monotonic clock used for elapsed-time measurements.", "kind": "fn", "type": "fn()-\u003eClock" }, { "name": "duration", "doc": "Constructs a duration from a number of nanoseconds.", "kind": "fn", "type": "fn(nanoseconds: Int)-\u003eDuration" }, { "name": "parse_timestamp", "doc": "Parses an RFC 3339 timestamp with an explicit time zone.", "kind": "fn", "type": "fn(text: String)-\u003eResult[Timestamp, TimeError]" }, { "name": "sleep", "doc": "Suspends the current task for at least the requested duration.", "kind": "fn", "type": "fn(duration: Duration)-\u003eUnit" }, { "name": "timestamp", "doc": "Constructs a timestamp from Unix seconds and a nanosecond adjustment.", "kind": "fn", "type": "fn(seconds: Int, nanoseconds: Int)-\u003eResult[Timestamp, TimeError]" }, { "name": "wall_clock", "doc": "Returns the wall clock used for calendar timestamps.", "kind": "fn", "type": "fn()-\u003eWallClock" } ] }, { "path": "@std/tls.ms", "declarations": [ { "name": "CertificateInfo", "doc": "Parsed certificate identity, validity range, and original DER bytes.", "kind": "record", "type": "CertificateInfo", "fields": [ "subject: String", "issuer: String", "dns_names: List[String]", "not_before: Timestamp", "not_after: Timestamp", "der: Bytes" ], "members": [ { "name": "der", "kind": "field", "signature": "der: Bytes", "doc": "The certificate's binary DER encoding, as a copy independent of the PEM text." }, { "name": "dns_names", "kind": "field", "signature": "dns_names: List[String]", "doc": "DNS subject alternative names in certificate order; empty when the certificate has none." }, { "name": "issuer", "kind": "field", "signature": "issuer: String", "doc": "The issuing authority as a distinguished-name string, in the same format as `subject`." }, { "name": "not_after", "kind": "field", "signature": "not_after: Timestamp", "doc": "End of the validity period as a UTC Timestamp." }, { "name": "not_before", "kind": "field", "signature": "not_before: Timestamp", "doc": "Start of the validity period as a UTC Timestamp." }, { "name": "subject", "kind": "field", "signature": "subject: String", "doc": "The certificate subject as a distinguished-name string, such as `CN=example.com,O=Example`." } ] }, { "name": "TlsError", "doc": "Errors returned when TLS configuration, certificates, or peer authentication fail.", "kind": "alternative", "type": "TlsError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "AuthenticationFailed" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "AuthenticationFailed", "kind": "case", "signature": "case AuthenticationFailed", "doc": "Chain verification failed: the chain does not lead to a supplied root, a certificate is expired or not yet valid at the supplied time, or the name does not match." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "The PEM text is not a sequence of well-formed CERTIFICATE blocks, or a chain or roots argument holds no certificate." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A certificate limit is negative, a `server_name` is empty, or `tls_info` was requested on a connection that is not TLS." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The PEM text holds more certificates than `max_certificates`." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `TLS: \u003creason\u003e`, such as `TLS: authentication failed`, without echoing certificate text.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "TlsInfo", "doc": "Negotiated TLS version, cipher, protocol, and peer certificate information.", "kind": "record", "type": "TlsInfo", "fields": [ "version: Int", "cipher_suite: Int", "alpn: String", "peer_certificates: List[Bytes]", "verified: Bool" ], "members": [ { "name": "alpn", "kind": "field", "signature": "alpn: String", "doc": "The application protocol both sides agreed on, or an empty string when none was negotiated." }, { "name": "cipher_suite", "kind": "field", "signature": "cipher_suite: Int", "doc": "Negotiated cipher suite as its numeric IANA identifier, such as 4865 (0x1301) for TLS_AES_128_GCM_SHA256." }, { "name": "peer_certificates", "kind": "field", "signature": "peer_certificates: List[Bytes]", "doc": "The peer's presented certificates as DER bytes, leaf first; empty when the peer sent none." }, { "name": "verified", "kind": "field", "signature": "verified: Bool", "doc": "True when the peer's certificate chain was verified against the configured roots; false when no peer chain was verified." }, { "name": "version", "kind": "field", "signature": "version: Int", "doc": "Negotiated protocol version as its numeric wire code, such as 771 (0x0303) for TLS 1.2 or 772 (0x0304) for TLS 1.3." } ] }, { "name": "TlsOptions", "doc": "Client or server TLS settings, including roots, certificates, and ALPN protocols.", "kind": "record", "type": "TlsOptions", "fields": [ "server_name: String", "roots_pem: String", "certificate_pem: String", "private_key_pem: String", "alpn: List[String]", "require_client_certificate: Bool" ], "members": [ { "name": "alpn", "kind": "field", "signature": "alpn: List[String]", "doc": "Application-layer protocols to offer or accept, in preference order, such as `h2` or `http/1.1`. Each must be 1 through 255 bytes; empty disables negotiation." }, { "name": "certificate_pem", "kind": "field", "signature": "certificate_pem: String", "doc": "PEM certificate chain this side presents, paired with `private_key_pem`. Servers must supply it; clients supply it only for mutual TLS." }, { "name": "private_key_pem", "kind": "field", "signature": "private_key_pem: String", "doc": "PEM private key matching `certificate_pem`. Both must be set together and match, or setup fails." }, { "name": "require_client_certificate", "kind": "field", "signature": "require_client_certificate: Bool", "doc": "Servers only: when true, a client must present a certificate that verifies against `roots_pem`. Setting it on a client configuration is rejected." }, { "name": "roots_pem", "kind": "field", "signature": "roots_pem: String", "doc": "PEM certificates to trust. Clients use them instead of the system roots; servers use them to verify client certificates. An empty string selects the system roots; invalid PEM is rejected." }, { "name": "server_name", "kind": "field", "signature": "server_name: String", "doc": "Host name a TLS client sends for server name indication and matches against the server certificate; it must be non-empty for `connect_tls_config`.\nHTTP and WebSocket clients take the name from the URL host and ignore this field, and servers do not use it." } ] }, { "name": "parse_certificates", "doc": "Parses PEM certificates and optionally limits the number returned.", "kind": "fn", "type": "fn(pem: String, max_certificates: Optional[Int] = ...)-\u003eResult[List[CertificateInfo], TlsError]" }, { "name": "verify_certificates", "doc": "Verifies a PEM certificate chain against roots, name constraints, and the supplied time.", "kind": "fn", "type": "fn(chain_pem: String, roots_pem: String, server_name: String, now: Timestamp)-\u003eResult[Unit, TlsError]" } ] }, { "path": "@std/toml.ms", "declarations": [ { "name": "TomlError", "doc": "Errors returned for invalid limits, malformed TOML, or exceeded resource bounds.", "kind": "alternative", "type": "TomlError", "cases": [ "InvalidInput", "InvalidData(line: Int, column: Int, reason: String)", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData(line: Int, column: Int, reason: String)", "doc": "Invalid syntax, duplicate/conflicting keys, unsupported value forms or numeric range failures." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A supplied limit is negative, or stringify received a value that is not a table." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Input, nesting or parsed/returned value counts exceed a supplied budget." }, { "name": "InvalidData.column", "kind": "field", "signature": "column: Int", "doc": "One-based Unicode scalar column after CRLF normalization." }, { "name": "InvalidData.line", "kind": "field", "signature": "line: Int", "doc": "One-based line of the invalid token or conflicting construct." }, { "name": "InvalidData.reason", "kind": "field", "signature": "reason: String", "doc": "Parser diagnostic describing the rejected TOML construct." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Formats the source line, scalar column and parser reason for a malformed document.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "TomlLimits", "doc": "Optional input-byte, nesting-depth, and parsed-value limits for TOML parsing.", "kind": "record", "type": "TomlLimits", "fields": [ "max_bytes: Optional[Int]", "max_depth: Optional[Int]", "max_values: Optional[Int]" ], "members": [ { "name": "max_bytes", "kind": "field", "signature": "max_bytes: Optional[Int] = none", "doc": "Maximum UTF-8 input bytes before CRLF normalization; none adds no budget." }, { "name": "max_depth", "kind": "field", "signature": "max_depth: Optional[Int] = none", "doc": "Maximum value depth, including scalar leaves and implicit tables, with the root at one." }, { "name": "max_values", "kind": "field", "signature": "max_values: Optional[Int] = none", "doc": "Maximum containers and leaves, excluding keys; checked during parsing and materialization." } ] }, { "name": "TomlValue", "doc": "A TOML value. Date and time values retain their original TOML text.", "kind": "alternative", "type": "TomlValue", "cases": [ "StringValue(value: String)", "IntValue(value: Int)", "FloatValue(value: Float)", "BoolValue(value: Bool)", "DateTimeValue(text: String)", "ArrayValue(values: List[TomlValue])", "TableValue(values: Map[String, TomlValue])" ], "members": [ { "name": "ArrayValue", "kind": "case", "signature": "case ArrayValue(values: List[TomlValue])", "doc": "An ordered array; elements can have different TOML value kinds." }, { "name": "BoolValue", "kind": "case", "signature": "case BoolValue(value: Bool)", "doc": "A TOML true or false value; other capitalizations are invalid." }, { "name": "DateTimeValue", "kind": "case", "signature": "case DateTimeValue(text: String)", "doc": "A validated local/offset date or time token, retained as text." }, { "name": "FloatValue", "kind": "case", "signature": "case FloatValue(value: Float)", "doc": "A parsed floating-point number, including TOML infinity and NaN spellings." }, { "name": "IntValue", "kind": "case", "signature": "case IntValue(value: Int)", "doc": "A parsed whole number; out-of-range input is rejected rather than truncated." }, { "name": "StringValue", "kind": "case", "signature": "case StringValue(value: String)", "doc": "Text decoded from TOML basic or literal string syntax." }, { "name": "TableValue", "kind": "case", "signature": "case TableValue(values: Map[String, TomlValue])", "doc": "An insertion-ordered table; parse returns this case even for an empty document." }, { "name": "ArrayValue.values", "kind": "field", "signature": "values: List[TomlValue]", "doc": "Element values in document order, with ordinary mutable list storage." }, { "name": "BoolValue.value", "kind": "field", "signature": "value: Bool", "doc": "The decoded boolean from the lowercase TOML token." }, { "name": "DateTimeValue.text", "kind": "field", "signature": "text: String", "doc": "Original accepted TOML date/time spelling, without a timezone conversion." }, { "name": "FloatValue.value", "kind": "field", "signature": "value: Float", "doc": "Numeric value of the accepted floating token, preserving signed zero." }, { "name": "IntValue.value", "kind": "field", "signature": "value: Int", "doc": "Exact signed integer value of the accepted TOML numeric token." }, { "name": "StringValue.value", "kind": "field", "signature": "value: String", "doc": "Unicode contents after the applicable escapes and multiline rules." }, { "name": "TableValue.values", "kind": "field", "signature": "values: Map[String, TomlValue]", "doc": "String-keyed entries produced by assignments, dotted keys and table headers." } ] }, { "name": "parse", "doc": "Parses a TOML document into a table value and reports source line and column on invalid input.", "kind": "fn", "type": "fn(text: String, limits: Optional[TomlLimits] = ...)-\u003eResult[TomlValue, TomlError]" }, { "name": "stringify", "doc": "Serializes a table value as a TOML document. Tables and arrays of tables use headers; other values are written inline.", "kind": "fn", "type": "fn(value: TomlValue, max_bytes: Optional[Int] = ...)-\u003eResult[String, TomlError]" } ] }, { "path": "@std/url.ms", "declarations": [ { "name": "QueryEntry", "doc": "One decoded key and value in a URL query string.", "kind": "record", "type": "QueryEntry", "fields": [ "key: String", "value: String" ], "members": [ { "name": "key", "kind": "field", "signature": "key: String", "doc": "Decoded query key; duplicate keys retain separate entries in input order." }, { "name": "value", "kind": "field", "signature": "value: String", "doc": "Decoded query value; a bare key has an empty value and plus decodes as a space." } ] }, { "name": "Url", "doc": "Parsed URL components. A missing port is represented by `none`.", "kind": "record", "type": "Url", "fields": [ "scheme: String", "host: String", "port: Optional[Int]", "path: String", "query: String", "fragment: String" ], "members": [ { "name": "fragment", "kind": "field", "signature": "fragment: String", "doc": "Decoded fragment contents without the leading hash mark." }, { "name": "host", "kind": "field", "signature": "host: String", "doc": "Lowercased hostname, excluding the port and IPv6 brackets; user information is rejected." }, { "name": "path", "kind": "field", "signature": "path: String", "doc": "Escaped path text, retaining escaped separators; format validates its percent escapes and UTF-8." }, { "name": "port", "kind": "field", "signature": "port: Optional[Int]", "doc": "Explicit numeric port in 0..65535, or none when the input has no port." }, { "name": "query", "kind": "field", "signature": "query: String", "doc": "Encoded query contents without the leading question mark; parse_query decodes individual entries." }, { "name": "scheme", "kind": "field", "signature": "scheme: String", "doc": "URL scheme, lowercased during parsing; native parse rejects missing schemes and opaque URLs." } ] }, { "name": "UrlError", "doc": "Errors returned for malformed URL text, components, or query limits.", "kind": "alternative", "type": "UrlError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "URL text, escaped bytes, port syntax or a relative reference is invalid or unsupported." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "Constructed URL components or a supplied query-entry budget are invalid." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The decoded query has more entries than its supplied budget permits." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns a URL-prefixed diagnostic without echoing addresses, query values or credentials.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "decode_component", "doc": "Decodes one percent-encoded URL component. `+` is not treated as a space.", "kind": "fn", "type": "fn(text: String)-\u003eResult[String, UrlError]" }, { "name": "encode_component", "doc": "Percent-encodes one URL component using UTF-8 bytes.", "kind": "fn", "type": "fn(text: String)-\u003eString" }, { "name": "format", "doc": "Formats URL components as an absolute or relative URL.", "kind": "fn", "type": "fn(value: Url)-\u003eResult[String, UrlError]" }, { "name": "format_query", "doc": "Encodes query entries as a query string.", "kind": "fn", "type": "fn(entries: List[QueryEntry])-\u003eString" }, { "name": "parse", "doc": "Parses an absolute URL into its components.", "kind": "fn", "type": "fn(text: String)-\u003eResult[Url, UrlError]" }, { "name": "parse_query", "doc": "Parses a query string, preserving duplicate keys and their input order.", "kind": "fn", "type": "fn(text: String, max_entries: Optional[Int] = ...)-\u003eResult[List[QueryEntry], UrlError]" }, { "name": "resolve", "doc": "Resolves a relative reference against a base URL.", "kind": "fn", "type": "fn(base: Url, reference: String)-\u003eResult[Url, UrlError]" } ] }, { "path": "@std/websocket.ms", "declarations": [ { "name": "WebSocket", "doc": "A WebSocket connection. Send and receive byte messages with an explicit text flag.", "kind": "interface", "type": "WebSocket", "operations": [ "close: fn()-\u003eUnit", "ping: fn(data: Bytes)-\u003eResult[Unit, WebSocketError]", "receive: fn()-\u003eResult[Optional[WebSocketMessage], WebSocketError]", "send: fn(data: Bytes, text: Bool)-\u003eResult[Unit, WebSocketError]", "subprotocol: fn()-\u003eString" ], "members": [ { "name": "close", "kind": "operation", "signature": "fn close() -\u003e Unit", "doc": "Sends a normal-closure frame, waiting at most about 100 ms to write it, then closes the connection and waits for in-flight calls to stop.\nSafe to call repeatedly; later calls wait for the first." }, { "name": "ping", "kind": "operation", "signature": "fn ping(data: Bytes) -\u003e Result[Unit, WebSocketError]", "doc": "Sends a ping frame carrying `data`, which must be at most 125 bytes, with a one-second write deadline.\nIt does not wait for the pong. Returns Closed on a closed socket." }, { "name": "receive", "kind": "operation", "signature": "fn receive() -\u003e Result[Optional[WebSocketMessage], WebSocketError]", "doc": "Waits for the next complete message and returns it, or none once the peer closes normally.\nA larger message returns LimitExceeded and a malformed text message InvalidData; after any receive failure the connection is closed. One receive runs at a time, and others wait their turn." }, { "name": "send", "kind": "operation", "signature": "fn send(data: Bytes, text: Bool) -\u003e Result[Unit, WebSocketError]", "doc": "Sends `data` as one message, a text frame when `text` is true and a binary frame otherwise.\nText must be valid UTF-8 or the call returns InvalidData, and a payload over `max_message_bytes` returns LimitExceeded. One send runs at a time." }, { "name": "subprotocol", "kind": "operation", "signature": "fn subprotocol() -\u003e String", "doc": "Returns the subprotocol the server selected during the handshake, or an empty string when none was negotiated." } ] }, { "name": "WebSocketError", "doc": "Errors returned by WebSocket handshakes, message limits, timeouts, or closed sockets.", "kind": "alternative", "type": "WebSocketError", "cases": [ "InvalidInput", "InvalidData", "LimitExceeded", "PermissionDenied", "Closed", "Timeout", "Failed(message: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Closed", "kind": "case", "signature": "case Closed", "doc": "The socket or its network handle was closed, or an earlier read failure already ended the connection." }, { "name": "Failed", "kind": "case", "signature": "case Failed(message: String)", "doc": "Handshake, transport, or protocol failure, such as a refused connection or a rejected upgrade." }, { "name": "InvalidData", "kind": "case", "signature": "case InvalidData", "doc": "A text message is not valid UTF-8, whether being sent or received." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A URL is not a `ws` or `wss` URL with a host and no user info, `max_message_bytes` is not positive, a header, subprotocol, or option is malformed, or a ping payload exceeds 125 bytes." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "A message is larger than `max_message_bytes`." }, { "name": "PermissionDenied", "kind": "case", "signature": "case PermissionDenied", "doc": "The network handle's restriction policy does not allow the host." }, { "name": "Timeout", "kind": "case", "signature": "case Timeout", "doc": "The connection attempt did not finish within `timeout`." }, { "name": "Failed.message", "kind": "field", "signature": "message: String", "doc": "Host-provided failure text; `message()` returns it verbatim, so it can name addresses." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the `Failed` text verbatim, and otherwise the fixed diagnostic `WebSocket: \u003creason\u003e`.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "WebSocketMessage", "doc": "A received message and whether its payload is UTF-8 text.", "kind": "record", "type": "WebSocketMessage", "fields": [ "data: Bytes", "text: Bool" ], "members": [ { "name": "data", "kind": "field", "signature": "data: Bytes", "doc": "The message payload bytes; for a text message they are the UTF-8 encoding of the text." }, { "name": "text", "kind": "field", "signature": "text: Bool", "doc": "True when the peer sent a text frame, which guarantees `data` is valid UTF-8; false for a binary frame." } ] }, { "name": "WebSocketOptions", "doc": "WebSocket message, timeout, TLS, and per-message compression settings.", "kind": "record", "type": "WebSocketOptions", "fields": [ "max_message_bytes: Optional[Int]", "timeout: Optional[Duration]", "tls: TlsOptions", "compression: Bool" ], "members": [ { "name": "compression", "kind": "field", "signature": "compression: Bool", "doc": "When true, offers per-message compression during the handshake; it applies only if the peer agrees." }, { "name": "max_message_bytes", "kind": "field", "signature": "max_message_bytes: Optional[Int] = none", "doc": "Largest message accepted or sent, in bytes. Must be positive; none sets no limit." }, { "name": "timeout", "kind": "field", "signature": "timeout: Optional[Duration] = none", "doc": "Time budget for connecting and completing the opening handshake. none waits indefinitely and a negative duration is rejected." }, { "name": "tls", "kind": "field", "signature": "tls: TlsOptions", "doc": "TLS settings for `wss` URLs: trusted roots, client identity, and protocols." } ] } ] }, { "path": "@std/yaml.ms", "declarations": [ { "name": "YamlError", "doc": "Errors returned for malformed YAML, unsupported features, or exceeded resource limits.", "kind": "alternative", "type": "YamlError", "cases": [ "InvalidInput", "InvalidData(line: Int, column: Int, reason: String)", "UnsupportedFeature(line: Int, reason: String)", "LimitExceeded" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidData", "kind": "case", "signature": "case InvalidData(line: Int, column: Int, reason: String)", "doc": "Malformed YAML or a form outside the supported parser's accepted grammar." }, { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A supplied limit is negative, or stringify received a number whose text is not a YAML number." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "Parsing or validating the returned alias-expanded tree exceeds a supplied budget." }, { "name": "UnsupportedFeature", "kind": "case", "signature": "case UnsupportedFeature(line: Int, reason: String)", "doc": "An explicit tag, complex key or directive unsupported by this configuration parser." }, { "name": "InvalidData.column", "kind": "field", "signature": "column: Int", "doc": "One-based Unicode scalar column within that source line." }, { "name": "InvalidData.line", "kind": "field", "signature": "line: Int", "doc": "One-based source line of the offending token or construct." }, { "name": "InvalidData.reason", "kind": "field", "signature": "reason: String", "doc": "Parser diagnostic describing the malformed construct." }, { "name": "UnsupportedFeature.line", "kind": "field", "signature": "line: Int", "doc": "One-based source line where the unsupported construct appears." }, { "name": "UnsupportedFeature.reason", "kind": "field", "signature": "reason: String", "doc": "Diagnostic identifying the unsupported syntax or feature." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Formats parser positions and reason text; match the typed fields for programmatic handling.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "YamlLimits", "doc": "Optional input-byte, nesting-depth, and parsed-value limits for YAML parsing.", "kind": "record", "type": "YamlLimits", "fields": [ "max_bytes: Optional[Int]", "max_depth: Optional[Int]", "max_values: Optional[Int]" ], "members": [ { "name": "max_bytes", "kind": "field", "signature": "max_bytes: Optional[Int] = none", "doc": "Maximum UTF-8 input bytes before line-ending normalization; none adds no budget." }, { "name": "max_depth", "kind": "field", "signature": "max_depth: Optional[Int] = none", "doc": "Maximum value depth, including scalar leaves, with the root at one." }, { "name": "max_values", "kind": "field", "signature": "max_values: Optional[Int] = none", "doc": "Maximum containers and leaves, excluding keys; aliases count at each checked occurrence." } ] }, { "name": "YamlValue", "doc": "A YAML value represented as null, boolean, number text, string, array, or object.", "kind": "alternative", "type": "YamlValue", "cases": [ "Null", "BoolValue(value: Bool)", "NumberValue(text: String)", "StringValue(value: String)", "ArrayValue(values: List[YamlValue])", "ObjectValue(values: Map[String, YamlValue])" ], "members": [ { "name": "ArrayValue", "kind": "case", "signature": "case ArrayValue(values: List[YamlValue])", "doc": "An ordered YAML sequence with ordinary mutable list storage." }, { "name": "BoolValue", "kind": "case", "signature": "case BoolValue(value: Bool)", "doc": "A core-schema true or false value; yes and no remain strings." }, { "name": "Null", "kind": "case", "signature": "case Null", "doc": "YAML null, including an empty document or a plain null spelling." }, { "name": "NumberValue", "kind": "case", "signature": "case NumberValue(text: String)", "doc": "Numeric token text retained exactly instead of being coerced into Float." }, { "name": "ObjectValue", "kind": "case", "signature": "case ObjectValue(values: Map[String, YamlValue])", "doc": "A textual-key mapping, with insertion order and duplicate-key checks." }, { "name": "StringValue", "kind": "case", "signature": "case StringValue(value: String)", "doc": "Text decoded from a quoted, plain or block scalar." }, { "name": "ArrayValue.values", "kind": "field", "signature": "values: List[YamlValue]", "doc": "Sequence entries in document order, retaining nested references." }, { "name": "BoolValue.value", "kind": "field", "signature": "value: Bool", "doc": "The decoded boolean selected from YAML core-schema spellings." }, { "name": "NumberValue.text", "kind": "field", "signature": "text: String", "doc": "Original numeric spelling, including supported base prefixes and nonfinite spellings." }, { "name": "ObjectValue.values", "kind": "field", "signature": "values: Map[String, YamlValue]", "doc": "Decoded string keys and their values; aliases may share nested payloads." }, { "name": "StringValue.value", "kind": "field", "signature": "value: String", "doc": "Resulting Unicode text after escape decoding, folding and chomping." } ] }, { "name": "parse", "doc": "Parses a YAML document. Unsupported YAML features and invalid input include source locations.", "kind": "fn", "type": "fn(text: String, limits: Optional[YamlLimits] = ...)-\u003eResult[YamlValue, YamlError]" }, { "name": "stringify", "doc": "Serializes a YAML value in block style with double-quoted strings.", "kind": "fn", "type": "fn(value: YamlValue, max_bytes: Optional[Int] = ...)-\u003eResult[String, YamlError]" } ] }, { "path": "prelude", "declarations": [ { "name": "Bool", "doc": "Boolean truth values true and false; conditions require this type.", "kind": "type", "type": "Bool" }, { "name": "CollectionError", "doc": "Errors returned when a collection factory exceeds its supplied item limit.", "kind": "alternative", "type": "CollectionError", "cases": [ "InvalidInput", "LimitExceeded", "OutOfRange" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "InvalidInput", "kind": "case", "signature": "case InvalidInput", "doc": "A count, item budget, or step is invalid: `count` or `max_items` is negative, or `range` has a zero `step`." }, { "name": "LimitExceeded", "kind": "case", "signature": "case LimitExceeded", "doc": "The result would hold more items than `max_items`, or more than the runtime's ceiling of 268435456 (2^28) items when `max_items` is omitted." }, { "name": "OutOfRange", "kind": "case", "signature": "case OutOfRange", "doc": "A slice bound lies outside 0 \u003c= start \u003c= end \u003c= length() after negative bounds are resolved from the end." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns the fixed diagnostic `collection: \u003creason\u003e`, such as `collection: limit exceeded`, without echoing values.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "Equal", "doc": "Equality and hashing are ordinary operation interfaces. Built-in data retains\nits value semantics; an explicit implementation selects domain identity.", "kind": "interface", "type": "Equal", "operations": [ "equals: fn(other: Equal)-\u003eBool" ], "members": [ { "name": "equals", "kind": "operation", "signature": "fn equals(other: Equal) -\u003e Bool", "doc": "Compares this value with another value in the same domain." } ] }, { "name": "Error", "doc": "A contract for expected failures that can provide a human-readable message.", "kind": "interface", "type": "Error", "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String", "doc": "Returns a human-readable description of this expected error." } ] }, { "name": "Float", "doc": "Binary floating-point values, including signed zero, infinities and NaN.", "kind": "type", "type": "Float", "operations": [ "is_finite: fn()-\u003eBool", "is_nan: fn()-\u003eBool", "to_exponential: fn(digits: Int)-\u003eResult[String, NumberError]", "to_fixed: fn(digits: Int)-\u003eResult[String, NumberError]", "to_precision: fn(precision: Int)-\u003eResult[String, NumberError]", "to_string: fn()-\u003eString", "truncate_to_int: fn()-\u003eOptional[Int]" ], "members": [ { "name": "is_finite", "kind": "operation", "signature": "fn is_finite() -\u003e Bool", "doc": "Tests whether the value is neither NaN nor an infinity." }, { "name": "is_nan", "kind": "operation", "signature": "fn is_nan() -\u003e Bool", "doc": "Tests whether the value is NaN." }, { "name": "to_exponential", "kind": "operation", "signature": "fn to_exponential(digits: Int) -\u003e Result[String, NumberError]", "doc": "Formats scientific notation with 0..100 fractional digits; an invalid count returns NumberError.InvalidInput." }, { "name": "to_fixed", "kind": "operation", "signature": "fn to_fixed(digits: Int) -\u003e Result[String, NumberError]", "doc": "Formats 0..100 fractional digits; magnitude \u003e= 1e21 uses ordinary round-trip notation.\nInvalid digits return NumberError.InvalidInput; rounding uses binary64 ties to even." }, { "name": "to_precision", "kind": "operation", "signature": "fn to_precision(precision: Int) -\u003e Result[String, NumberError]", "doc": "Formats 1..100 significant digits, preserving trailing zeros; an invalid precision returns NumberError.InvalidInput." }, { "name": "to_string", "kind": "operation", "signature": "fn to_string() -\u003e String", "doc": "Returns the shortest round-trip representation, including NaN and signed infinities." }, { "name": "truncate_to_int", "kind": "operation", "signature": "fn truncate_to_int() -\u003e Optional[Int]", "doc": "Truncates toward zero, or returns none for nonfinite values or Int overflow." } ] }, { "name": "Hashable", "doc": "A type with a stable hash consistent with its `Equal` implementation.", "kind": "interface", "type": "Hashable", "operations": [ "hash: fn()-\u003eInt" ], "members": [ { "name": "hash", "kind": "operation", "signature": "fn hash() -\u003e Int", "doc": "Returns a stable hash consistent with `equals` for the same value." } ] }, { "name": "Int", "doc": "Signed whole numbers with checked arithmetic; overflow and division by zero fault.", "kind": "type", "type": "Int", "operations": [ "to_decimal: fn()-\u003eDecimal", "to_float: fn()-\u003eFloat", "to_string: fn(radix: Int)-\u003eString" ], "members": [ { "name": "to_decimal", "kind": "operation", "signature": "fn to_decimal() -\u003e Decimal", "doc": "Converts to the exactly equal Decimal; no rounding occurs." }, { "name": "to_float", "kind": "operation", "signature": "fn to_float() -\u003e Float", "doc": "Converts to the nearest Float; integers beyond 2^53 in magnitude can lose low-order digits." }, { "name": "to_string", "kind": "operation", "signature": "fn to_string(radix: Int) -\u003e String", "doc": "Formats the integer in a radix from 2 through 36 using lowercase digits and a leading `-` for negatives.\nA radix outside 2 through 36 is a programming fault." } ] }, { "name": "List", "doc": "An ordered mutable collection with indexing, iteration, and transformations.\nPrimitive backing stores Int and Float values at 64 bits, Bool values as bytes, and String references without an element box.\nGeneric forwarding retains the same List identity; clone and slice copy outer storage.", "kind": "native", "type": "List[T]", "type_parameters": [ "T" ], "operations": [ "append: fn(value: T)-\u003eList[T]", "at: fn(index: Int)-\u003eOptional[T]", "clone: fn()-\u003eList[T]", "concat: fn(other: List[T])-\u003eList[T]", "contains: fn(value: T)-\u003eBool", "copy_within: fn(target: Int, start: Int, end: Int)-\u003eList[T]", "count: fn(predicate: fn(value: T)-\u003eBool)-\u003eInt", "distinct: fn()-\u003eList[T]", "drop: fn(count: Int)-\u003eList[T]", "entries: fn()-\u003eList[ListEntry[T]]", "every: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "fill: fn(value: T, start: Int, end: Int)-\u003eList[T]", "filter: fn(predicate: fn(value: T)-\u003eBool)-\u003eList[T]", "find: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "find_index: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[Int]", "find_last: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "find_last_index: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[Int]", "first: fn()-\u003eOptional[T]", "flat_map[U]: fn(transform: fn(value: T)-\u003eList[U])-\u003eList[U]", "fold[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "fold_right[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "for_each: fn(operation: fn(value: T)-\u003eUnit)-\u003eUnit", "group_by[K: Hashable]: fn(key: fn(value: T)-\u003eK)-\u003eMap[K, List[T]]", "index_of: fn(value: T)-\u003eOptional[Int]", "insert: fn(index: Int, value: T)-\u003eList[T]", "is_empty: fn()-\u003eBool", "join: fn(separator: String)-\u003eString", "keys: fn()-\u003eList[Int]", "last: fn()-\u003eOptional[T]", "last_index_of: fn(value: T)-\u003eOptional[Int]", "length: fn()-\u003eInt", "map[U]: fn(transform: fn(value: T)-\u003eU)-\u003eList[U]", "pop: fn()-\u003eOptional[T]", "prepend: fn(value: T)-\u003eList[T]", "remove: fn(index: Int)-\u003eList[T]", "reverse_in_place: fn()-\u003eList[T]", "reversed: fn()-\u003eList[T]", "set: fn(index: Int, value: T)-\u003eList[T]", "slice: fn(start: Int, end: Int)-\u003eResult[List[T], CollectionError]", "some: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "sorted: fn(compare: fn(left: T, right: T)-\u003eInt)-\u003eList[T]", "splice: fn(start: Int, delete_count: Int, replacement: List[T])-\u003eList[T]", "take: fn(count: Int)-\u003eList[T]", "to_set: fn()-\u003eSet[T]" ], "members": [ { "name": "append", "kind": "operation", "signature": "fn append(value: T) -\u003e List[T]:", "doc": "Adds `value` at the end in place and returns this same list." }, { "name": "at", "kind": "operation", "signature": "fn at(index: Int) -\u003e Optional[T]:", "doc": "Returns an element; negative indexes are relative to the end, and out-of-range indexes return none." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e List[T]:", "doc": "Returns a shallow copy with independent list storage." }, { "name": "concat", "kind": "operation", "signature": "fn concat(other: List[T]) -\u003e List[T]:", "doc": "Returns a new list holding this list's elements followed by `other`; neither operand is changed." }, { "name": "contains", "kind": "operation", "signature": "fn contains(value: T) -\u003e Bool:", "doc": "Reports whether any element equals `value`, using the element type's Equal implementation; an empty list returns false." }, { "name": "copy_within", "kind": "operation", "signature": "fn copy_within(target: Int, start: Int, end: Int) -\u003e List[T]:", "doc": "Copies the elements in [start, end) to begin at index `target`, in place, and returns this list.\nThe list never grows: copying stops at the end of the list. Source bounds must satisfy 0 \u003c= start \u003c= end \u003c= length() and a target must be within 0 through length(); otherwise the call faults." }, { "name": "count", "kind": "operation", "signature": "fn count(predicate: fn(value: T) -\u003e Bool) -\u003e Int:", "doc": "Counts values satisfying the predicate, calling it once per element in order." }, { "name": "distinct", "kind": "operation", "signature": "fn distinct() -\u003e List[T]:", "doc": "Returns a new shallow List keeping each first equal element in order; elements require Equal." }, { "name": "drop", "kind": "operation", "signature": "fn drop(count: Int) -\u003e List[T]:", "doc": "Copies the remainder after min(count, length) into fresh shallow List storage.\nLeaves the receiver unchanged; negative count is a programming fault." }, { "name": "entries", "kind": "operation", "signature": "fn entries() -\u003e List[ListEntry[T]]:", "doc": "Returns a new list of `ListEntry` records pairing each zero-based index with its element, in order." }, { "name": "every", "kind": "operation", "signature": "fn every(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Returns true when every value satisfies the predicate; empty lists return true." }, { "name": "fill", "kind": "operation", "signature": "fn fill(value: T, start: Int, end: Int) -\u003e List[T]:", "doc": "Sets elements in [start, end) to `value` in place and returns this list.\nBounds must satisfy 0 \u003c= start \u003c= end \u003c= length(); negative or larger bounds fault rather than counting from the end, and an empty range changes nothing." }, { "name": "filter", "kind": "operation", "signature": "fn filter(predicate: fn(value: T) -\u003e Bool) -\u003e List[T]:", "doc": "Keeps matching values in their original order." }, { "name": "find", "kind": "operation", "signature": "fn find(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Returns the first element for which `predicate` is true, or none; later elements are not tested after a match." }, { "name": "find_index", "kind": "operation", "signature": "fn find_index(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[Int]:", "doc": "Returns the zero-based index of the first element for which `predicate` is true, or none." }, { "name": "find_last", "kind": "operation", "signature": "fn find_last(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Searches from the end and returns the last element for which `predicate` is true, or none." }, { "name": "find_last_index", "kind": "operation", "signature": "fn find_last_index(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[Int]:", "doc": "Searches from the end and returns the last matching zero-based index, or none." }, { "name": "first", "kind": "operation", "signature": "fn first() -\u003e Optional[T]:", "doc": "Returns the first element, or none when the list is empty." }, { "name": "flat_map[U]", "kind": "operation", "signature": "fn flat_map[U](transform: fn(value: T) -\u003e List[U]) -\u003e List[U]:", "doc": "Calls `transform` on each element in order and concatenates the returned lists into one new list; the receiver is unchanged." }, { "name": "fold[A]", "kind": "operation", "signature": "fn fold[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces values from left to right, starting with `initial`." }, { "name": "fold_right[A]", "kind": "operation", "signature": "fn fold_right[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces values from right to left, starting with `initial`." }, { "name": "for_each", "kind": "operation", "signature": "fn for_each(operation: fn(value: T) -\u003e Unit) -\u003e Unit:", "doc": "Calls operation(value:) over the initial backing slice and length; element writes can affect later calls, and append does not extend traversal." }, { "name": "group_by[K: Hashable]", "kind": "operation", "signature": "fn group_by[K: Hashable](key: fn(value: T) -\u003e K) -\u003e Map[K, List[T]]:", "doc": "Calls `key` once per element in order and returns a map from each distinct key to the elements that produced it.\nKeys appear in first-seen order and each group keeps the original element order." }, { "name": "index_of", "kind": "operation", "signature": "fn index_of(value: T) -\u003e Optional[Int]:", "doc": "Returns the first equal element's zero-based index, or none; elements require Equal." }, { "name": "insert", "kind": "operation", "signature": "fn insert(index: Int, value: T) -\u003e List[T]:", "doc": "Inserts value before index in place and returns this list; negative indexes count from the end.\nRequires -length() \u003c= index \u003c= length(); index length() appends, and invalid indexes fault." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether the list has no elements." }, { "name": "join", "kind": "operation", "signature": "fn join(separator: String) -\u003e String:", "doc": "Concatenates the strings with `separator` between neighbors; an empty list returns an empty string.\nAvailable only on List[String]." }, { "name": "keys", "kind": "operation", "signature": "fn keys() -\u003e List[Int]:", "doc": "Returns a new list of the zero-based indexes 0 through length() - 1." }, { "name": "last", "kind": "operation", "signature": "fn last() -\u003e Optional[T]:", "doc": "Returns the last element, or none when the list is empty." }, { "name": "last_index_of", "kind": "operation", "signature": "fn last_index_of(value: T) -\u003e Optional[Int]:", "doc": "Returns the last equal element's zero-based index, or none; elements require Equal." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of elements." }, { "name": "map[U]", "kind": "operation", "signature": "fn map[U](transform: fn(value: T) -\u003e U) -\u003e List[U]:", "doc": "Returns a new list holding `transform` applied to each element in order; the receiver is unchanged." }, { "name": "pop", "kind": "operation", "signature": "fn pop() -\u003e Optional[T]:", "doc": "Removes and returns the last element in place, or none for an empty list." }, { "name": "prepend", "kind": "operation", "signature": "fn prepend(value: T) -\u003e List[T]:", "doc": "Inserts `value` at index 0 in place, shifting existing elements one position later, and returns this same list." }, { "name": "remove", "kind": "operation", "signature": "fn remove(index: Int) -\u003e List[T]:", "doc": "Removes an element in place and returns this list; negative indexes count from the end.\nInvalid indexes fault.\nShifts the suffix without clearing prior values retained in spare backing capacity." }, { "name": "reverse_in_place", "kind": "operation", "signature": "fn reverse_in_place() -\u003e List[T]:", "doc": "Reverses this list in place and returns the same instance." }, { "name": "reversed", "kind": "operation", "signature": "fn reversed() -\u003e List[T]:", "doc": "Returns a reversed shallow copy with independent outer storage; nested references remain shared." }, { "name": "set", "kind": "operation", "signature": "fn set(index: Int, value: T) -\u003e List[T]:", "doc": "Replaces an element in place and returns this list; negative indexes count from the end.\nInvalid indexes fault." }, { "name": "slice", "kind": "operation", "signature": "fn slice(start: Int, end: Int) -\u003e Result[List[T], CollectionError]:", "doc": "Returns a new shallow List containing [start, end); outer storage is independent.\nNegative bounds are relative to the end; bounds outside 0 \u003c= start \u003c= end \u003c= length() return CollectionError.OutOfRange." }, { "name": "some", "kind": "operation", "signature": "fn some(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Returns true when at least one value satisfies the predicate." }, { "name": "sorted", "kind": "operation", "signature": "fn sorted(compare: fn(left: T, right: T) -\u003e Int) -\u003e List[T]:", "doc": "Returns a new list sorted by negative/zero/positive comparator results." }, { "name": "splice", "kind": "operation", "signature": "fn splice(start: Int, delete_count: Int, replacement: List[T]) -\u003e List[T]:", "doc": "Replaces delete_count elements starting at start, mutating and returning this List.\nRequires 0 \u003c= start \u003c= length and 0 \u003c= delete_count \u003c= length - start; invalid bounds fault without clamping.\nReplacement references stay shallow; using this same List as replacement stages its prior values.\nShrinking retains prior values in spare backing capacity, following captured Go slice traversal." }, { "name": "take", "kind": "operation", "signature": "fn take(count: Int) -\u003e List[T]:", "doc": "Copies the first min(count, length) elements into fresh shallow List storage.\nLeaves the receiver unchanged; negative count is a programming fault." }, { "name": "to_set", "kind": "operation", "signature": "fn to_set() -\u003e Set[T]:", "doc": "Returns a new set of the distinct elements, using Hashable equality; the first of equal elements is kept in insertion order." } ] }, { "name": "ListEntry", "doc": "One list index and its corresponding value.", "kind": "record", "type": "ListEntry[T]", "type_parameters": [ "T" ], "fields": [ "index: Int", "value: T" ], "members": [ { "name": "index", "kind": "field", "signature": "index: Int", "doc": "Zero-based position of the element in the list that produced this entry." }, { "name": "value", "kind": "field", "signature": "value: T", "doc": "The element found at `index`." } ] }, { "name": "Map", "doc": "A mutable key-value collection. Keys use explicit `Hashable` value semantics.", "kind": "native", "type": "Map[T, U]", "type_parameters": [ "T: Hashable", "U" ], "operations": [ "add: fn(key: T, value: U)-\u003eMap[T, U]", "add_default: fn(key: T, value: U)-\u003eMap[T, U]", "add_default_from: fn(key: T, create: fn(key: T)-\u003eU)-\u003eMap[T, U]", "clear: fn()-\u003eMap[T, U]", "clone: fn()-\u003eMap[T, U]", "contains: fn(key: T)-\u003eBool", "entries: fn()-\u003eList[MapEntry[T, U]]", "every: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eBool", "filter: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eMap[T, U]", "find: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eOptional[MapEntry[T, U]]", "find_last: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eOptional[MapEntry[T, U]]", "fold[A]: fn(initial: A, step: fn(accumulator: A, key: T, value: U)-\u003eA)-\u003eA", "fold_right[A]: fn(initial: A, step: fn(accumulator: A, key: T, value: U)-\u003eA)-\u003eA", "for_each: fn(operation: fn(key: T, value: U)-\u003eUnit)-\u003eUnit", "get: fn(key: T)-\u003eOptional[U]", "get_or: fn(key: T, fallback: U)-\u003eU", "is_empty: fn()-\u003eBool", "keys: fn()-\u003eList[T]", "length: fn()-\u003eInt", "map[W]: fn(transform: fn(key: T, value: U)-\u003eW)-\u003eMap[T, W]", "map_keys[W: Hashable]: fn(transform: fn(key: T, value: U)-\u003eW)-\u003eMap[W, U]", "merge: fn(other: Map[T, U])-\u003eMap[T, U]", "remove: fn(key: T)-\u003eMap[T, U]", "some: fn(predicate: fn(key: T, value: U)-\u003eBool)-\u003eBool", "values: fn()-\u003eList[U]" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(key: T, value: U) -\u003e Map[T, U]:", "doc": "Inserts or replaces a value and returns this map; replacement keeps the original key and insertion position." }, { "name": "add_default", "kind": "operation", "signature": "fn add_default(key: T, value: U) -\u003e Map[T, U]:", "doc": "Inserts a default only when the key is absent and returns this map.\nThe supplied value evaluates normally even when the key already exists." }, { "name": "add_default_from", "kind": "operation", "signature": "fn add_default_from(key: T, create: fn(key: T) -\u003e U) -\u003e Map[T, U]:", "doc": "Creates and inserts a default only when the key is absent, then returns this map.\nCalls create(key:) once for absence; an existing key leaves its value and position unchanged." }, { "name": "clear", "kind": "operation", "signature": "fn clear() -\u003e Map[T, U]:", "doc": "Removes every entry in place and returns this same map; aliases observe the empty map." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e Map[T, U]:", "doc": "Returns a shallow copy with independent map storage." }, { "name": "contains", "kind": "operation", "signature": "fn contains(key: T) -\u003e Bool:", "doc": "Reports whether an equal key is present, using the key type's Hashable implementation." }, { "name": "entries", "kind": "operation", "signature": "fn entries() -\u003e List[MapEntry[T, U]]:", "doc": "Returns a new list of fresh `MapEntry` records in insertion order; keys and values keep their original references." }, { "name": "every", "kind": "operation", "signature": "fn every(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first nonmatching entry; empty maps return true." }, { "name": "filter", "kind": "operation", "signature": "fn filter(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Map[T, U]:", "doc": "Copies matching entries in insertion order, retaining payload references.\nCallbacks traverse a snapshot even when they mutate the receiver." }, { "name": "find", "kind": "operation", "signature": "fn find(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Optional[MapEntry[T, U]]:", "doc": "Returns the first matching entry as a fresh record with shallow references." }, { "name": "find_last", "kind": "operation", "signature": "fn find_last(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Optional[MapEntry[T, U]]:", "doc": "Searches a snapshot from the end, stopping at the last matching entry.\nReturns a fresh entry record retaining its original key/value references." }, { "name": "fold[A]", "kind": "operation", "signature": "fn fold[A](initial: A, step: fn(accumulator: A, key: T, value: U) -\u003e A) -\u003e A:", "doc": "Reduces an entry snapshot in insertion order, starting with initial." }, { "name": "fold_right[A]", "kind": "operation", "signature": "fn fold_right[A](initial: A, step: fn(accumulator: A, key: T, value: U) -\u003e A) -\u003e A:", "doc": "Reduces an entry snapshot in reverse insertion order, starting with initial." }, { "name": "for_each", "kind": "operation", "signature": "fn for_each(operation: fn(key: T, value: U) -\u003e Unit) -\u003e Unit:", "doc": "Calls operation(key:, value:) sequentially over an insertion-order membership snapshot." }, { "name": "get", "kind": "operation", "signature": "fn get(key: T) -\u003e Optional[U]:", "doc": "Returns the value stored for an equal key, or none when the key is absent." }, { "name": "get_or", "kind": "operation", "signature": "fn get_or(key: T, fallback: U) -\u003e U:", "doc": "Returns the stored value or an eagerly evaluated fallback without inserting." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether this map has no entries." }, { "name": "keys", "kind": "operation", "signature": "fn keys() -\u003e List[T]:", "doc": "Returns a new list of the keys in insertion order." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of entries." }, { "name": "map[W]", "kind": "operation", "signature": "fn map[W](transform: fn(key: T, value: U) -\u003e W) -\u003e Map[T, W]:", "doc": "Transforms values in snapshot insertion order, retaining original keys.\nReturns independent outer storage with shallow key and result references." }, { "name": "map_keys[W: Hashable]", "kind": "operation", "signature": "fn map_keys[W: Hashable](transform: fn(key: T, value: U) -\u003e W) -\u003e Map[W, U]:", "doc": "Transforms keys in snapshot insertion order, retaining value references.\nEqual outputs keep the first key/position and the last input value." }, { "name": "merge", "kind": "operation", "signature": "fn merge(other: Map[T, U]) -\u003e Map[T, U]:", "doc": "Copies every entry of `other` into this map in place and returns this map.\nExisting keys keep their position and key but take the value from `other`; new keys append in `other` order. `other` is unchanged." }, { "name": "remove", "kind": "operation", "signature": "fn remove(key: T) -\u003e Map[T, U]:", "doc": "Removes an equal key and returns this same Map; remaining entries retain insertion order.\nAn absent key leaves values and ordering unchanged; lookup uses the selected Equal/Hashable scope." }, { "name": "some", "kind": "operation", "signature": "fn some(predicate: fn(key: T, value: U) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first matching entry; empty maps return false." }, { "name": "values", "kind": "operation", "signature": "fn values() -\u003e List[U]:", "doc": "Returns a new list of the values in insertion order." } ] }, { "name": "MapEntry", "doc": "One key-value pair returned by `Map.entries`.", "kind": "record", "type": "MapEntry[T, U]", "type_parameters": [ "T: Hashable", "U" ], "fields": [ "key: T", "value: U" ], "members": [ { "name": "key", "kind": "field", "signature": "key: T", "doc": "The lookup identity of the pair; unique within its map under Hashable equality." }, { "name": "value", "kind": "field", "signature": "value: U", "doc": "The payload stored for `key`; the reference is shared with the map, not copied." } ] }, { "name": "MissingValue", "doc": "The error `Optional.ok_or()` returns when no cause is given. Its message names the source file and line of the call.", "kind": "alternative", "type": "MissingValue", "cases": [ "Missing(location: String)" ], "operations": [ "message: fn()-\u003eString" ], "members": [ { "name": "Missing", "kind": "case", "signature": "case Missing(location: String)", "doc": "Records where the absent value was converted to an error." }, { "name": "Missing.location", "kind": "field", "signature": "location: String", "doc": "The calling source position, as `file:line`." }, { "name": "message", "kind": "operation", "signature": "fn message() -\u003e String:", "doc": "Returns \"missing value at\" followed by the recorded source position.", "contract": "Error" } ], "implements": [ "Error" ] }, { "name": "Never", "doc": "The return type of computations that cannot return a value, such as panic.", "kind": "type", "type": "Never" }, { "name": "Optional", "doc": "Represents a value that may be absent: `some(value)` or `none`.", "kind": "alternative", "type": "Optional[T]", "type_parameters": [ "T" ], "cases": [ "some(value: T)", "none" ], "operations": [ "and_then[U]: fn(transform: fn(value: T)-\u003eOptional[U])-\u003eOptional[U]", "is_none: fn()-\u003eBool", "is_some: fn()-\u003eBool", "map[U]: fn(transform: fn(value: T)-\u003eU)-\u003eOptional[U]", "ok_or[E]: fn(cause: Optional[E] = ...)-\u003eResult[T, E]", "ok_or_else[E]: fn(create: fn()-\u003eE)-\u003eResult[T, E]", "or_else: fn(create: fn()-\u003eOptional[T])-\u003eOptional[T]", "unwrap: fn()-\u003eT", "unwrap_or: fn(fallback: T)-\u003eT", "unwrap_or_else: fn(create: fn()-\u003eT)-\u003eT" ], "members": [ { "name": "none", "kind": "case", "signature": "case none", "doc": "An absent value with no payload; no T needs to be constructed." }, { "name": "some", "kind": "case", "signature": "case some(value: T)", "doc": "A present payload, retained by reference when T is mutable." }, { "name": "some.value", "kind": "field", "signature": "value: T", "doc": "The contained value; unwrap and matching return this original payload." }, { "name": "and_then[U]", "kind": "operation", "signature": "fn and_then[U](transform: fn(value: T) -\u003e Optional[U]) -\u003e Optional[U]:", "doc": "Calls transform only when present, returning its Optional unchanged." }, { "name": "is_none", "kind": "operation", "signature": "fn is_none() -\u003e Bool:", "doc": "Reports whether this value is absent." }, { "name": "is_some", "kind": "operation", "signature": "fn is_some() -\u003e Bool:", "doc": "Returns true for some(value), and false for none." }, { "name": "map[U]", "kind": "operation", "signature": "fn map[U](transform: fn(value: T) -\u003e U) -\u003e Optional[U]:", "doc": "Transforms a present payload; none remains absent." }, { "name": "ok_or[E]", "kind": "operation", "signature": "fn ok_or[E = MissingValue](cause: Optional[E] = none) -\u003e Result[T, E]:", "doc": "Returns ok with the original payload, or error with the eager cause.\nWithout a cause, E is MissingValue and the error names the calling source file and line." }, { "name": "ok_or_else[E]", "kind": "operation", "signature": "fn ok_or_else[E](create: fn() -\u003e E) -\u003e Result[T, E]:", "doc": "Constructs an error once only for none; present payloads remain unchanged." }, { "name": "or_else", "kind": "operation", "signature": "fn or_else(create: fn() -\u003e Optional[T]) -\u003e Optional[T]:", "doc": "Calls create once only when absent, returning its Optional unchanged." }, { "name": "unwrap", "kind": "operation", "signature": "fn unwrap() -\u003e T:", "doc": "Returns the payload. Calling this on `none` raises a fault." }, { "name": "unwrap_or", "kind": "operation", "signature": "fn unwrap_or(fallback: T) -\u003e T:", "doc": "Returns the contained value, or `fallback` when this is `none`." }, { "name": "unwrap_or_else", "kind": "operation", "signature": "fn unwrap_or_else(create: fn() -\u003e T) -\u003e T:", "doc": "Computes a fallback only when this is `none`." } ] }, { "name": "Result", "doc": "Holds either a successful value (`ok`) or an expected failure (`error`).", "kind": "alternative", "type": "Result[T, E]", "type_parameters": [ "T", "E" ], "cases": [ "ok(value: T)", "error(cause: E)" ], "operations": [ "and_then[U]: fn(transform: fn(value: T)-\u003eResult[U, E])-\u003eResult[U, E]", "is_error: fn()-\u003eBool", "is_ok: fn()-\u003eBool", "map[U]: fn(transform: fn(value: T)-\u003eU)-\u003eResult[U, E]", "to_optional: fn()-\u003eOptional[T]", "unwrap: fn()-\u003eT", "unwrap_error: fn()-\u003eE", "unwrap_or: fn(fallback: T)-\u003eT", "unwrap_or_else: fn(create: fn(cause: E)-\u003eT)-\u003eT" ], "members": [ { "name": "error", "kind": "case", "signature": "case error(cause: E)", "doc": "An expected failure value; it is distinct from faults and cancellation." }, { "name": "ok", "kind": "case", "signature": "case ok(value: T)", "doc": "A successful result, retaining its payload without a deep copy." }, { "name": "error.cause", "kind": "field", "signature": "cause: E", "doc": "The original domain error, retained through compatible Result propagation." }, { "name": "ok.value", "kind": "field", "signature": "value: T", "doc": "The successful value returned by unwrap, matching, or propagation." }, { "name": "and_then[U]", "kind": "operation", "signature": "fn and_then[U](transform: fn(value: T) -\u003e Result[U, E]) -\u003e Result[U, E]:", "doc": "Calls transform only on success. Its result keeps the same error type." }, { "name": "is_error", "kind": "operation", "signature": "fn is_error() -\u003e Bool:", "doc": "Reports whether this result contains an expected error." }, { "name": "is_ok", "kind": "operation", "signature": "fn is_ok() -\u003e Bool:", "doc": "Reports whether this result contains a successful value." }, { "name": "map[U]", "kind": "operation", "signature": "fn map[U](transform: fn(value: T) -\u003e U) -\u003e Result[U, E]:", "doc": "Transforms only a successful payload, preserving an error unchanged." }, { "name": "to_optional", "kind": "operation", "signature": "fn to_optional() -\u003e Optional[T]:", "doc": "Returns some with the original success payload, or none for an error." }, { "name": "unwrap", "kind": "operation", "signature": "fn unwrap() -\u003e T:", "doc": "Returns the successful payload; faults when this is an error." }, { "name": "unwrap_error", "kind": "operation", "signature": "fn unwrap_error() -\u003e E:", "doc": "Returns the error payload; faults when this is successful." }, { "name": "unwrap_or", "kind": "operation", "signature": "fn unwrap_or(fallback: T) -\u003e T:", "doc": "Returns the successful payload, or the eagerly evaluated fallback." }, { "name": "unwrap_or_else", "kind": "operation", "signature": "fn unwrap_or_else(create: fn(cause: E) -\u003e T) -\u003e T:", "doc": "Calls create once with the original error only when this is an error." } ] }, { "name": "Set", "doc": "A mutable collection of unique values using explicit `Hashable` value semantics.", "kind": "native", "type": "Set[T]", "type_parameters": [ "T: Hashable" ], "operations": [ "add: fn(value: T)-\u003eSet[T]", "clear: fn()-\u003eSet[T]", "clone: fn()-\u003eSet[T]", "contains: fn(value: T)-\u003eBool", "difference: fn(other: Set[T])-\u003eSet[T]", "entries: fn()-\u003eList[List[T]]", "every: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "filter: fn(predicate: fn(value: T)-\u003eBool)-\u003eSet[T]", "find: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "find_last: fn(predicate: fn(value: T)-\u003eBool)-\u003eOptional[T]", "fold[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "fold_right[A]: fn(initial: A, step: fn(accumulator: A, value: T)-\u003eA)-\u003eA", "for_each: fn(operation: fn(value: T)-\u003eUnit)-\u003eUnit", "intersection: fn(other: Set[T])-\u003eSet[T]", "is_disjoint_from: fn(other: Set[T])-\u003eBool", "is_empty: fn()-\u003eBool", "is_subset_of: fn(other: Set[T])-\u003eBool", "is_superset_of: fn(other: Set[T])-\u003eBool", "length: fn()-\u003eInt", "map[U: Hashable]: fn(transform: fn(value: T)-\u003eU)-\u003eSet[U]", "remove: fn(value: T)-\u003eSet[T]", "some: fn(predicate: fn(value: T)-\u003eBool)-\u003eBool", "symmetric_difference: fn(other: Set[T])-\u003eSet[T]", "union: fn(other: Set[T])-\u003eSet[T]", "values: fn()-\u003eList[T]" ], "members": [ { "name": "add", "kind": "operation", "signature": "fn add(value: T) -\u003e Set[T]:", "doc": "Adds a value in place and returns this set; an equal value retains its original payload and position." }, { "name": "clear", "kind": "operation", "signature": "fn clear() -\u003e Set[T]:", "doc": "Removes all values in place and returns this set; aliases observe the empty set." }, { "name": "clone", "kind": "operation", "signature": "fn clone() -\u003e Set[T]:", "doc": "Copies outer storage, retaining element references and insertion order." }, { "name": "contains", "kind": "operation", "signature": "fn contains(value: T) -\u003e Bool:", "doc": "Reports whether an equal value is present, using the element's Hashable implementation." }, { "name": "difference", "kind": "operation", "signature": "fn difference(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set of receiver values absent from right, preserving receiver insertion order." }, { "name": "entries", "kind": "operation", "signature": "fn entries() -\u003e List[List[T]]:", "doc": "Returns a new list of [value, value] lists in insertion order." }, { "name": "every", "kind": "operation", "signature": "fn every(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first nonmatching element; empty sets return true." }, { "name": "filter", "kind": "operation", "signature": "fn filter(predicate: fn(value: T) -\u003e Bool) -\u003e Set[T]:", "doc": "Copies matching elements in insertion order, retaining payload references.\nCallbacks traverse a snapshot even when they mutate the receiver." }, { "name": "find", "kind": "operation", "signature": "fn find(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Returns the original first matching element, or none." }, { "name": "find_last", "kind": "operation", "signature": "fn find_last(predicate: fn(value: T) -\u003e Bool) -\u003e Optional[T]:", "doc": "Searches a snapshot from the end, returning the original last matching element." }, { "name": "fold[A]", "kind": "operation", "signature": "fn fold[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces an element snapshot in insertion order, starting with initial." }, { "name": "fold_right[A]", "kind": "operation", "signature": "fn fold_right[A](initial: A, step: fn(accumulator: A, value: T) -\u003e A) -\u003e A:", "doc": "Reduces an element snapshot in reverse insertion order, starting with initial." }, { "name": "for_each", "kind": "operation", "signature": "fn for_each(operation: fn(value: T) -\u003e Unit) -\u003e Unit:", "doc": "Calls operation(value:) sequentially over an insertion-order membership snapshot." }, { "name": "intersection", "kind": "operation", "signature": "fn intersection(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set of receiver values also in right, preserving receiver insertion order." }, { "name": "is_disjoint_from", "kind": "operation", "signature": "fn is_disjoint_from(other: Set[T]) -\u003e Bool:", "doc": "Tests whether the operands have no common values." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool:", "doc": "Reports whether this set has no elements." }, { "name": "is_subset_of", "kind": "operation", "signature": "fn is_subset_of(other: Set[T]) -\u003e Bool:", "doc": "Tests whether every receiver value also occurs in right." }, { "name": "is_superset_of", "kind": "operation", "signature": "fn is_superset_of(other: Set[T]) -\u003e Bool:", "doc": "Tests whether every right value also occurs in the receiver." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int:", "doc": "Returns the number of distinct values currently stored." }, { "name": "map[U: Hashable]", "kind": "operation", "signature": "fn map[U: Hashable](transform: fn(value: T) -\u003e U) -\u003e Set[U]:", "doc": "Transforms a snapshot into a fresh set, retaining the first equal result." }, { "name": "remove", "kind": "operation", "signature": "fn remove(value: T) -\u003e Set[T]:", "doc": "Removes an equal value in place and returns this set; an absent value leaves it unchanged." }, { "name": "some", "kind": "operation", "signature": "fn some(predicate: fn(value: T) -\u003e Bool) -\u003e Bool:", "doc": "Stops at the first matching element; empty sets return false." }, { "name": "symmetric_difference", "kind": "operation", "signature": "fn symmetric_difference(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set of values in exactly one operand; leaves both operands unchanged." }, { "name": "union", "kind": "operation", "signature": "fn union(other: Set[T]) -\u003e Set[T]:", "doc": "Returns a new set with receiver values followed by right-only values in insertion order." }, { "name": "values", "kind": "operation", "signature": "fn values() -\u003e List[T]:", "doc": "Returns a shallow list of values in insertion order." } ] }, { "name": "String", "doc": "UTF-8 text indexed by Unicode scalar values; byte_length counts encoded bytes instead.", "kind": "type", "type": "String", "operations": [ "at: fn(index: Int)-\u003eOptional[String]", "byte_length: fn()-\u003eInt", "chars: fn()-\u003eList[String]", "compare: fn(other: String)-\u003eInt", "concat: fn(other: String)-\u003eString", "contains: fn(value: String)-\u003eBool", "ends_with: fn(suffix: String)-\u003eBool", "index_of: fn(value: String)-\u003eOptional[Int]", "is_empty: fn()-\u003eBool", "last_index_of: fn(value: String)-\u003eOptional[Int]", "length: fn()-\u003eInt", "lines: fn()-\u003eList[String]", "lower: fn()-\u003eString", "normalize: fn(form: String, max_bytes: Optional[Int] = ...)-\u003eResult[String, StringError]", "pad_end: fn(target_length: Int, padding: String, max_bytes: Optional[Int] = ...)-\u003eResult[String, StringError]", "pad_start: fn(target_length: Int, padding: String, max_bytes: Optional[Int] = ...)-\u003eResult[String, StringError]", "parse_int: fn()-\u003eOptional[Int]", "repeat: fn(count: Int, max_bytes: Optional[Int] = ...)-\u003eResult[String, StringError]", "replace: fn(old: String, new: String, max_replacements: Optional[Int] = ...)-\u003eString", "replace_all: fn(old: String, new: String, max_bytes: Optional[Int] = ...)-\u003eResult[String, StringError]", "replace_first: fn(old: String, new: String, max_replacements: Optional[Int] = ...)-\u003eString", "replace_n: fn(old: String, new: String, max_replacements: Int)-\u003eString", "reverse: fn()-\u003eString", "scalar_at: fn(index: Int)-\u003eOptional[Int]", "scalar_length: fn()-\u003eInt", "scalar_values: fn()-\u003eList[Int]", "slice: fn(start: Int, end: Int)-\u003eResult[String, StringError]", "slice_scalars: fn(start: Int, end: Int)-\u003eResult[String, StringError]", "split: fn(separator: String, max_parts: Optional[Int] = ...)-\u003eList[String]", "starts_with: fn(prefix: String)-\u003eBool", "to_bytes: fn()-\u003eBytes", "trim: fn()-\u003eString", "trim_end: fn()-\u003eString", "trim_start: fn()-\u003eString", "upper: fn()-\u003eString" ], "members": [ { "name": "at", "kind": "operation", "signature": "fn at(index: Int) -\u003e Optional[String]", "doc": "Returns a one-scalar String; negative indexes are relative to the end, and invalid indexes return none." }, { "name": "byte_length", "kind": "operation", "signature": "fn byte_length() -\u003e Int", "doc": "Returns the UTF-8 encoded byte length." }, { "name": "chars", "kind": "operation", "signature": "fn chars() -\u003e List[String]", "doc": "Returns a fresh list with one String for each Unicode scalar, in order." }, { "name": "compare", "kind": "operation", "signature": "fn compare(other: String) -\u003e Int", "doc": "Returns -1, 0 or 1 in lexical scalar order, without locale or normalization." }, { "name": "concat", "kind": "operation", "signature": "fn concat(other: String) -\u003e String", "doc": "Concatenates text without changing either operand." }, { "name": "contains", "kind": "operation", "signature": "fn contains(value: String) -\u003e Bool", "doc": "Tests whether the exact text occurs, without normalization." }, { "name": "ends_with", "kind": "operation", "signature": "fn ends_with(suffix: String) -\u003e Bool", "doc": "Tests whether the receiver ends with this exact suffix." }, { "name": "index_of", "kind": "operation", "signature": "fn index_of(value: String) -\u003e Optional[Int]", "doc": "Returns the first matching Unicode scalar index or none; empty value matches at zero." }, { "name": "is_empty", "kind": "operation", "signature": "fn is_empty() -\u003e Bool", "doc": "Reports whether the text contains no scalars." }, { "name": "last_index_of", "kind": "operation", "signature": "fn last_index_of(value: String) -\u003e Optional[Int]", "doc": "Returns the last matching Unicode scalar index or none; empty value matches at scalar_length()." }, { "name": "length", "kind": "operation", "signature": "fn length() -\u003e Int", "doc": "Counts Unicode scalars, with the same unit as scalar_length." }, { "name": "lines", "kind": "operation", "signature": "fn lines() -\u003e List[String]", "doc": "Splits LF and CRLF lines, preserving interior empty lines and standalone CR.\nOmits a final extra empty item; empty text returns a fresh empty list." }, { "name": "lower", "kind": "operation", "signature": "fn lower() -\u003e String", "doc": "Returns locale-independent full Unicode lowercase mapping; the scalar length can change." }, { "name": "normalize", "kind": "operation", "signature": "fn normalize(form: String, max_bytes: Optional[Int] = none) -\u003e Result[String, StringError]", "doc": "Normalizes using exactly NFC, NFD, NFKC, or NFKD (case-sensitive); max_bytes optionally bounds UTF-8 output.\nInvalid forms or negative budgets return InvalidInput; exceeded budgets return LimitExceeded." }, { "name": "pad_end", "kind": "operation", "signature": "fn pad_end(target_length: Int, padding: String, max_bytes: Optional[Int] = none) -\u003e Result[String, StringError]", "doc": "Pads on the right until the scalar length reaches `target_length`.\nEmpty padding or a shorter target leaves text unchanged; negative targets/budgets return InvalidInput." }, { "name": "pad_start", "kind": "operation", "signature": "fn pad_start(target_length: Int, padding: String, max_bytes: Optional[Int] = none) -\u003e Result[String, StringError]", "doc": "Pads on the left until the scalar length reaches `target_length`.\nEmpty padding or a shorter target leaves text unchanged; max_bytes still bounds UTF-8 output." }, { "name": "parse_int", "kind": "operation", "signature": "fn parse_int() -\u003e Optional[Int]", "doc": "Parses signed ASCII decimal digits; invalid text or Int overflow returns none." }, { "name": "repeat", "kind": "operation", "signature": "fn repeat(count: Int, max_bytes: Optional[Int] = none) -\u003e Result[String, StringError]", "doc": "Repeats text count times; negative counts/budgets return InvalidInput, exceeded UTF-8 budgets return LimitExceeded." }, { "name": "replace", "kind": "operation", "signature": "fn replace(old: String, new: String, max_replacements: Optional[Int] = none) -\u003e String", "doc": "Compatibility spelling for replace_first, including its explicit replacement cap." }, { "name": "replace_all", "kind": "operation", "signature": "fn replace_all(old: String, new: String, max_bytes: Optional[Int] = none) -\u003e Result[String, StringError]", "doc": "Replaces every nonoverlapping occurrence; empty old matches at each scalar boundary.\nmax_bytes bounds UTF-8 output; negatives return InvalidInput and exhaustion returns LimitExceeded." }, { "name": "replace_first", "kind": "operation", "signature": "fn replace_first(old: String, new: String, max_replacements: Optional[Int] = none) -\u003e String", "doc": "Transitional compatibility name: omitted or none replaces the first occurrence; an explicit cap can replace more.\nUse replace_n for a required finite cap; this retained signature has not become a strict first-only operation.\nAn empty old matches at scalar boundaries, and inserted text is not searched again.\nZero changes nothing; negative caps retain replace's programming fault." }, { "name": "replace_n", "kind": "operation", "signature": "fn replace_n(old: String, new: String, max_replacements: Int) -\u003e String", "doc": "Replaces at most the required number of nonoverlapping literal occurrences; zero leaves text unchanged.\nEmpty old matches at scalar boundaries, inserted text is not rescanned, and negative caps retain replace's programming fault.\nThe count limits replacements, not UTF-8 output bytes; there is no additional allocation budget." }, { "name": "reverse", "kind": "operation", "signature": "fn reverse() -\u003e String", "doc": "Reverses Unicode scalar order; combining sequences/graphemes may change." }, { "name": "scalar_at", "kind": "operation", "signature": "fn scalar_at(index: Int) -\u003e Optional[Int]", "doc": "Returns an integer scalar code point; negative indexes are relative to the end, and invalid indexes return none." }, { "name": "scalar_length", "kind": "operation", "signature": "fn scalar_length() -\u003e Int", "doc": "Returns the number of Unicode scalar values in the string." }, { "name": "scalar_values", "kind": "operation", "signature": "fn scalar_values() -\u003e List[Int]", "doc": "Returns each Unicode scalar value as an integer." }, { "name": "slice", "kind": "operation", "signature": "fn slice(start: Int, end: Int) -\u003e Result[String, StringError]", "doc": "Selects [start, end) in Unicode scalars; negative bounds are relative to the end.\nBounds outside 0 \u003c= start \u003c= end \u003c= scalar_length() return StringError.OutOfRange; the receiver is unchanged." }, { "name": "slice_scalars", "kind": "operation", "signature": "fn slice_scalars(start: Int, end: Int) -\u003e Result[String, StringError]", "doc": "Selects [start, end) in Unicode scalars; requires 0 \u003c= start \u003c= end \u003c= scalar_length().\nNegative, inverted, or out-of-range bounds return StringError.OutOfRange." }, { "name": "split", "kind": "operation", "signature": "fn split(separator: String, max_parts: Optional[Int] = none) -\u003e List[String]", "doc": "Splits exact separators, truncating parts to a supplied nonnegative cap; zero returns [], negatives fault.\nEmpty text with a nonempty separator yields [\"\"]; an empty separator splits into scalars." }, { "name": "starts_with", "kind": "operation", "signature": "fn starts_with(prefix: String) -\u003e Bool", "doc": "Tests whether the receiver begins with this exact prefix." }, { "name": "to_bytes", "kind": "operation", "signature": "fn to_bytes() -\u003e Bytes", "doc": "Encodes the string as UTF-8 bytes." }, { "name": "trim", "kind": "operation", "signature": "fn trim() -\u003e String", "doc": "Removes Unicode whitespace at both ends; see the exact whitespace set in the text guide." }, { "name": "trim_end", "kind": "operation", "signature": "fn trim_end() -\u003e String", "doc": "Removes Unicode whitespace at the end." }, { "name": "trim_start", "kind": "operation", "signature": "fn trim_start() -\u003e String", "doc": "Removes Unicode whitespace at the start." }, { "name": "upper", "kind": "operation", "signature": "fn upper() -\u003e String", "doc": "Returns locale-independent full Unicode uppercase mapping; the scalar length can change." } ] }, { "name": "Unit", "doc": "The single value unit, used when an operation returns no useful payload.", "kind": "type", "type": "Unit" } ] } ] }