TypeScript
What Comline supports in TypeScript, as its conformance suites prove it. For how to use it, see the TypeScript guide. The states are explained in the overview.
Code generation
What the comline-typescript generator emits
for each language feature, and the conformance fixtures that prove it.
Generator typescript#5.0.
| Feature | What it covers | State | Proven by |
|---|---|---|---|
structs structs |
struct declarations |
✅ supported | primitives, optional_and_arrays, type_refs, protocol, shapes, cross_schema, import_alias, import_glob, nested_namespace, external_std, validators, validators_on_decode, unions, large_fixed_arrays_nested, format_json |
enums enums |
enum declarations |
✅ supported | enum_basic |
optional fields optional-fields |
fields marked optional |
✅ supported | optional_and_arrays, type_refs, shapes, cross_schema, validators, validators_on_decode, large_fixed_arrays_nested |
arrays arrays |
variable-length arrays, T[] |
✅ supported | optional_and_arrays, type_refs, shapes, cross_schema, validators, validators_on_decode, large_fixed_arrays_nested |
fixed-length arrays fixed-arrays |
fixed-length arrays, T[N] |
🟡 partial: rendered as T[]: the length isn't part of the type |
shapes, large_fixed_arrays_nested |
fixed arrays over 32 elements, nested large-fixed-arrays-nested |
a T[N] with N over 32 anywhere but a field's own, non-optional type: inside another array, optional, an alias, an argument or a return |
🟡 partial: rendered as T[]: the length isn't part of the type |
large_fixed_arrays_nested |
unions unions |
union(A B ...) types |
✅ supported | unions |
type aliases type-aliases |
type Name = ... declarations |
✅ supported | validators, validators_on_decode, unions |
constants constants |
const declarations |
✅ supported | constant, shapes, validators, validators_on_decode |
protocols protocols |
protocol declarations and their functions |
✅ supported | protocol, error_shapes, validators, validators_on_decode, framing_jsonrpc, handshake_none, connections, connections_async, connections_jsonrpc, format_json |
errors errors |
error declarations |
✅ supported | protocol, error_shapes, format_json |
functions that throw throws |
functions declared with ! Error |
✅ supported | protocol, error_shapes, format_json |
validators validators |
@validators on fields and type aliases, checked in generated code |
⚪ ignored: the types are generated; the checks aren't run yet (core#96) | validators, validators_on_decode |
imports between schemas imports |
use of another schema's declarations |
✅ supported | cross_schema, import_alias, import_glob, nested_namespace, external_std, validators, validators_on_decode |
nested namespaces nested-namespaces |
schemas in subdirectories (chat::admin) |
✅ supported | nested_namespace, external_std, validators, validators_on_decode |
lib mode lib-mode |
--mode lib: a buildable package, not bare source files |
✅ supported | nested_namespace, external_std |
external_std external-std |
[generate] external_std: std referenced as its own package |
✅ supported | external_std |
validate_on_decode validate-on-decode |
[generate] validate_on_decode: decoding runs the checks |
⚪ ignored: no checks are generated to run on decode yet (core#96) | validators_on_decode |
JSON-RPC framing framing-jsonrpc |
@framing = "jsonrpc" (or as the package default) |
✅ supported | framing_jsonrpc, connections_jsonrpc |
no handshake handshake-none |
@handshake = "none" (or as the package default) |
✅ supported | handshake_none |
connections connections |
protocols on a connection, with calls in both directions: datagram@2 (the default), or @provider = Client / Multiple |
✅ supported | protocol, error_shapes, validators, validators_on_decode, handshake_none, connections, connections_async, connections_jsonrpc, format_json |
async async |
[generate] async: connection protocols get async handlers and senders |
⚪ ignored: handlers and senders always return Promises: the output is async either way | connections_async |
the packed@1 format format-packed |
wire.format = "packed@1", the default: fixed-width fields, no tags |
✅ supported | protocol, error_shapes, validators, validators_on_decode, handshake_none, connections, connections_async |
the json@1 format format-json |
wire.format = "json@1" |
✅ supported | format_json |
the msgpack@1 format format-msgpack |
wire.format = "msgpack@1" |
❌ unsupported: @comline/runtime has no MessagePack codec yet |
format_msgpack |
Runtime
What the @comline/runtime runtime speaks on the wire, proven against the
shared wire corpus:
byte-exact examples of the handshake, the envelopes, each framing and each
wire format. The claims are in conformance-support.json.
Runtime typescript.
| Feature | What it covers | State | Proven by |
|---|---|---|---|
name hash name-hash |
FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | 8 cases |
handshake handshake |
the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | 9 cases |
envelope envelope |
a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | 8 cases |
datagram framing framing-datagram |
Comline's own binary framing of requests and responses | ✅ supported | 9 cases |
datagram@2 framing framing-datagram2 |
the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | 12 cases |
stream framing stream |
frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ❌ unsupported: no length-prefixed framing or frame limit yet: the transports are message-oriented (comline-typescript#80) | — |
JSON-RPC framing framing-jsonrpc |
JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | 19 cases |
JSON wire format format-json |
values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges (comline-typescript#57) fails: format-json/decode-unknown-variant, format-json/decode-wider-integer-overflow |
44 cases |
MessagePack wire format format-msgpack |
values as MessagePack: a struct as an array | ❌ unsupported: JSON and packed@1 ship | — |
packed wire format format-packed |
values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | 59 cases |
Verification
The TypeScript runtime is also checked against the Rust reference on random inputs, in addition to the vectors above. Its divergences from the reference are tracked, each with the issue that will fix it.
Differential properties
- Property tests
(
fast-check) run the same random types and values through this runtime and thecomline-referenceprocess, and compare what each encodes, accepts and refuses: the formats, the framings, the envelope and the handshake. - Pull requests run a short suite; a nightly run takes 20,000 cases per property and opens an issue on a divergence outside the known classes.
The property suite doesn't write a results file, so there are no run counts to show here. Coverage-guided fuzzing (Jazzer.js) isn't set up yet.
Divergences
Where typescript and the reference are known to answer differently, from known-divergences.json. The differential tests report a difference in one of these classes and fail on any other.
| Class | What differs | Issue |
|---|---|---|
json-decode-unchecked-variants-and-ranges |
json@1 decoding accepts a string that isn't one of the enum's variants, and an integer outside its type's range; the reference refuses both | comline-typescript#57 |
json-decode-unchecked-shape |
json@1 decoding accepts the wrong JSON kind, a missing or repeated struct field, an integer spelled 1.0, 1e0 or -0, and a float past its range; the reference refuses them | comline-typescript#73 |
json-encode-f32-digits |
json@1 writes an f32 with the shortest digits of a double (1.401298464324817e-45), the reference with those of the f32 (1e-45): the same f32, not the same JSON number | comline-typescript#74 |
jsonrpc-decode-lenient |
jsonrpc@1 decoding accepts a declared member twice, and an id or error code spelled 1.0, 1e0 or -0; the reference refuses both | comline-typescript#75 |
connection-replies-in-any-order |
Connection hands a reply to the call it answers in any order; an ordered (nested, blocking) Rust State refuses a reply that skips the innermost waiting call as a framing error. TypeScript has only the async model | comline-typescript#77 |
Benchmarks
No benchmark results are published yet: they will appear here once the runtime checks in runtime/conformance-bench.json.