Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions FEATURES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Generator features

<!-- Generated by `comline-conformance` (`support_is_proven`) - don't edit by hand. Regenerate with `CONFORMANCE_BLESS=1 cargo test`. -->

What the typescript generator implements, and the conformance fixtures that prove it. A claim is checked, not trusted: a supported feature has a fixture that generates and matches its golden, an ignored one generates exactly what it would without the feature, and an unsupported one is refused with an error naming every use.

| Feature | typescript ≥ 5.0 |
|---|---|
| structs <br><sub>`structs`</sub> | ✅ supported <br><sub>proven by `primitives`, `optional_and_arrays`, `type_refs` +18 more</sub> |
| enums <br><sub>`enums`</sub> | ✅ supported <br><sub>proven by `enum_basic`</sub> |
| optional fields <br><sub>`optional-fields`</sub> | ✅ supported <br><sub>proven by `optional_and_arrays`, `type_refs`, `shapes` +5 more</sub> |
| arrays <br><sub>`arrays`</sub> | ✅ supported <br><sub>proven by `optional_and_arrays`, `type_refs`, `shapes` +6 more</sub> |
| fixed-length arrays <br><sub>`fixed-arrays`</sub> | 🟡 partial: rendered as `T[]`: the length isn't part of the type <br><sub>proven by `shapes`, `large_fixed_arrays_nested`</sub> |
| fixed arrays over 32 elements, nested <br><sub>`large-fixed-arrays-nested`</sub> | 🟡 partial: rendered as `T[]`: the length isn't part of the type <br><sub>proven by `large_fixed_arrays_nested`</sub> |
| unions <br><sub>`unions`</sub> | ✅ supported <br><sub>proven by `unions`</sub> |
| type aliases <br><sub>`type-aliases`</sub> | ✅ supported <br><sub>proven by `validators`, `validators_on_decode`, `unions` +1 more</sub> |
| constants <br><sub>`constants`</sub> | ✅ supported <br><sub>proven by `constant`, `shapes`, `validators` +1 more</sub> |
| protocols <br><sub>`protocols`</sub> | ✅ supported <br><sub>proven by `protocol`, `error_shapes`, `validators` +14 more</sub> |
| errors <br><sub>`errors`</sub> | ✅ supported <br><sub>proven by `protocol`, `error_shapes`, `lockstep` +1 more</sub> |
| functions that throw <br><sub>`throws`</sub> | ✅ supported <br><sub>proven by `protocol`, `error_shapes`, `lockstep` +1 more</sub> |
| validators <br><sub>`validators`</sub> | ⚪ ignored: the types are generated; the checks aren't run yet (core#96) <br><sub>proven by `validators`, `validators_on_decode`</sub> |
| imports between schemas <br><sub>`imports`</sub> | ✅ supported <br><sub>proven by `cross_schema`, `import_alias`, `import_glob` +6 more</sub> |
| nested namespaces <br><sub>`nested-namespaces`</sub> | ✅ supported <br><sub>proven by `nested_namespace`, `external_std`, `validators` +4 more</sub> |
| `lib` mode <br><sub>`lib-mode`</sub> | ✅ supported <br><sub>proven by `nested_namespace`, `external_std`</sub> |
| `external_std` <br><sub>`external-std`</sub> | ✅ supported <br><sub>proven by `external_std`</sub> |
| `validate_on_decode` <br><sub>`validate-on-decode`</sub> | ⚪ ignored: no checks are generated to run on decode yet (core#96) <br><sub>proven by `validators_on_decode`</sub> |
| JSON-RPC framing <br><sub>`framing-jsonrpc`</sub> | ✅ supported <br><sub>proven by `framing_jsonrpc`, `connections_jsonrpc`</sub> |
| no handshake <br><sub>`handshake-none`</sub> | ✅ supported <br><sub>proven by `handshake_none`</sub> |
| `datagram@3` framing <br><sub>`framing-datagram3`</sub> | ✅ supported <br><sub>proven by `framing_datagram3`, `handshake_comline2`, `connections_default` +3 more</sub> |
| `comline@2` handshake <br><sub>`handshake-comline2`</sub> | ✅ supported <br><sub>proven by `handshake_comline2`, `connections_default`, `dependency_protocol` +2 more</sub> |
| connections <br><sub>`connections`</sub> | ✅ supported <br><sub>proven by `protocol`, `error_shapes`, `validators` +12 more</sub> |
| `async` <br><sub>`async`</sub> | ⚪ ignored: handlers and senders always return Promises: the output is async either way <br><sub>proven by `connections_async`</sub> |
| the `packed@1` format <br><sub>`format-packed`</sub> | ✅ supported <br><sub>proven by `protocol`, `error_shapes`, `validators` +11 more</sub> |
| the `json@1` format <br><sub>`format-json`</sub> | ✅ supported <br><sub>proven by `format_json`</sub> |
| the `msgpack@1` format <br><sub>`format-msgpack`</sub> | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet <br><sub>proven by `format_msgpack`</sub> |
| bounds <br><sub>`bounds`</sub> | ✅ supported <br><sub>proven by `bounds`</sub> |
| single characters <br><sub>`chars`</sub> | ✅ supported <br><sub>proven by `chars`</sub> |
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,14 @@ cd runtime && npm ci && npm test
## Features

What this generator implements, feature by feature. Each claim is checked by
the conformance suite in [`ComlineProject/generation`](https://github.com/ComlineProject/generation):
`codegen/tests/conformance.rs`, which runs the conformance corpus of
[`ComlineProject/generation`](https://github.com/ComlineProject/generation)
over this generator, against the goldens in `codegen/tests/golden/`:
a supported feature has a fixture that generates and matches its golden output,
an ignored one generates exactly what it would without the feature, and an
unsupported one is refused with an error naming every use. The full matrix,
with the fixtures that prove each claim, is in
[`FEATURES.md`](https://github.com/ComlineProject/generation/blob/master/FEATURES.md).
with the fixtures that prove each claim, is in [`FEATURES.md`](FEATURES.md)
(also as [`features.json`](features.json)), which that run writes.

<!-- features:start -->
<!-- Generated from `SUPPORT` in `codegen/src/lib.rs` - don't edit by hand. -->
Expand Down
11 changes: 6 additions & 5 deletions codegen/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ license = "GPL-3.0-only"
# Consumed by git rev (see ComlineProject/docs → Design → Runtime & generation
# repository structure — no crates.io publishing at this stage). Local
# iteration: add a `[patch]` onto a sibling checkout.
comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "e900919375429591d73c906380f1d354d636ab22" }
comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "31e808ff05632acbfa4f48d208b8d5a2fbca3b0e" }
comline-core = { git = "https://github.com/ComlineProject/core", rev = "69039e7ab05953760bb7a6818f61e98c14b43922", default-features = false }

eyre = "0.6.8"
Expand All @@ -18,9 +18,10 @@ name = "comline-gen-typescript"
path = "src/bin/comline-gen-typescript.rs"

[dev-dependencies]
# The conformance corpus: every fixture is a whole package. Same generation
# rev as `comline-codegen` above, so the corpus and the generator share one
# `comline-codegen`.
comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "e900919375429591d73c906380f1d354d636ab22" }
# The conformance corpus and the harness that runs this generator over it
# (`tests/conformance.rs`, against `tests/golden/`): every fixture is a whole
# package. Same generation rev as `comline-codegen` above, so the corpus and
# the generator share one `comline-codegen`.
comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "31e808ff05632acbfa4f48d208b8d5a2fbca3b0e" }
# The tests compile schemas, so they need core's compiler.
comline-core = { git = "https://github.com/ComlineProject/core", rev = "69039e7ab05953760bb7a6818f61e98c14b43922" }
46 changes: 46 additions & 0 deletions codegen/tests/conformance.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
//! The conformance corpus (`comline-conformance`, in ComlineProject/generation)
//! run over this generator: its output for every fixture, at each of its
//! version boundaries, against the goldens under `tests/golden/`; the
//! generator protocol round trip; and the proof of every claim in `SUPPORT`,
//! with the report `FEATURES.md` and `features.json` at the repository root.
//! Regenerate the goldens and the report with:
//!
//! ```text
//! CONFORMANCE_BLESS=1 cargo test -p comline-codegen-typescript --test conformance
//! ```
//!
//! A blessed golden is a snapshot of what the generator does now: a diff in
//! one is a change to what it emits, to be read as one.

use std::path::Path;

use comline_conformance::harness::{self, Generator};

const GENERATOR: Generator = Generator {
language: "typescript",
generate: comline_codegen_typescript::generate_typescript,
register: comline_codegen_typescript::register,
support: comline_codegen_typescript::SUPPORT,
versions: comline_codegen_typescript::VERSIONS,
};

#[test]
fn the_protocol_generates_what_the_generator_does() {
harness::the_protocol_generates_what_the_generator_does(&GENERATOR);
}

#[test]
fn corpus_matches_golden() {
harness::corpus_matches_golden(
&GENERATOR,
&Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/golden"),
);
}

#[test]
fn support_is_proven() {
harness::support_is_proven(
&GENERATOR,
&Path::new(env!("CARGO_MANIFEST_DIR")).join(".."),
);
}
35 changes: 35 additions & 0 deletions codegen/tests/golden/bounds/typescript/conformance.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
// Generated by Comline
// For TypeScript 5.0 or later; verified up to 5.9.

import { checkChars, type Layout } from "@comline/runtime";

/** A string of at most 32 characters: make one with `Name.from`. */
export type Name = string & { readonly __brand: "Name" };

export const NameLayout: Layout = { chars: { max: 32 } };

export const Name = {
/** `value` as a `Name`; throws a `RuntimeError` unless it holds at most 32 characters. */
from(value: string): Name {
checkChars(value, 32);
return value as Name;
},
};

export interface Customer {
name: Name;
country: string;
email?: string;
tags: string[];
scores: number[];
}

export const CustomerLayout: Layout = { struct: [["name", () => NameLayout], ["country", { chars: { length: 2 } }], ["email", { option: { chars: { max: 254 } } }], ["tags", { array: { chars: { max: 16 } }, max: 8 }], ["scores", { array: "u32", max: 10 }]] };

export interface Node {
label: string;
children: Node[];
}

export const NodeLayout: Layout = { depth: 16, of: { struct: [["label", { chars: { max: 64 } }], ["children", { array: () => NodeLayout, max: 4 }]] } };

11 changes: 11 additions & 0 deletions codegen/tests/golden/chars/typescript/conformance.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
// Generated by Comline
// For TypeScript 5.0 or later; verified up to 5.9.

import type { Layout } from "@comline/runtime";

export interface Grade {
letter: string;
}

export const GradeLayout: Layout = { struct: [["letter", "char"]] };

184 changes: 184 additions & 0 deletions codegen/tests/golden/connections/typescript/conformance.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
// Generated by Comline
// For TypeScript 5.0 or later; verified up to 5.9.

import {
RuntimeError,
resolveKind,
type Codec,
type Connection,
type Dispatch,
type Kind,
type Layout,
type Peer,
type Reply,
} from "@comline/runtime";

/** Canonical digest of the frozen IR this file was generated from — the
* two ends of a connection must agree on it. */
export const IR_HASH = 0xb97e34b203ec1425n;

export interface ChatSendParams {
n: number;
}

/** @internal */
export const ChatSendParamsLayout: Layout = { struct: [["n", "u32"]] };

export interface Chat {
send(peer: Peer, params: ChatSendParams): Promise<number>;
}

/** @internal */
export const CHAT_CALLS = ["send"] as const;

/** @internal */
export class ChatDispatcher implements Dispatch {
/** This protocol's number on a connection. */
static readonly PROTOCOL = 0;

private readonly impl: Chat;

constructor(impl: Chat) {
this.impl = impl;
}

calls(): readonly string[] {
return CHAT_CALLS;
}

/** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */
async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise<void> {
reply.fault();
}

async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise<void> {
const codec = peer.codec;
switch (resolveKind(call, CHAT_CALLS)) {
case 0: {
try {
const p = codec.decode<ChatSendParams>(params, ChatSendParamsLayout);
reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u32"));
} catch {
reply.fault();
}
return;
}
default:
throw RuntimeError.unknownCall();
}
}

/** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */
provideOn(conn: Connection): void {
conn.provide(ChatDispatcher.PROTOCOL, this);
}
}

/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */
export class ChatSender {
/** This protocol's number on a connection. */
static readonly PROTOCOL = 0;

private readonly peer: Peer;

constructor(peer: Peer) {
this.peer = peer;
}

async send(params: ChatSendParams): Promise<number> {
const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: ChatSendParamsLayout });
if ("ok" in env) return this.peer.codec.decode<number>(env.ok, "u32");
if ("fault" in env) throw RuntimeError.provider();
throw RuntimeError.remote(env.err.id);
}
}

export interface EventsShownParams {
n: number;
}

/** @internal */
export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] };

export interface Events {
shown(peer: Peer, params: EventsShownParams): Promise<boolean>;
ping(peer: Peer): Promise<void>;
}

/** @internal */
export const EVENTS_CALLS = ["shown", "ping"] as const;

/** @internal */
export class EventsDispatcher implements Dispatch {
/** This protocol's number on a connection. */
static readonly PROTOCOL = 1;

private readonly impl: Events;

constructor(impl: Events) {
this.impl = impl;
}

calls(): readonly string[] {
return EVENTS_CALLS;
}

/** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */
async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise<void> {
reply.fault();
}

async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise<void> {
const codec = peer.codec;
switch (resolveKind(call, EVENTS_CALLS)) {
case 0: {
try {
const p = codec.decode<EventsShownParams>(params, EventsShownParamsLayout);
reply.ok(codec.encode((await this.impl.shown(peer, p)) ?? null, "bool"));
} catch {
reply.fault();
}
return;
}
case 1: {
try {
await this.impl.ping(peer);
} catch {
/* one-way: nowhere to report this */
}
return;
}
default:
throw RuntimeError.unknownCall();
}
}

/** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */
provideOn(conn: Connection): void {
conn.provide(EventsDispatcher.PROTOCOL, this);
}
}

/** Calls protocol `Events` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */
export class EventsSender {
/** This protocol's number on a connection. */
static readonly PROTOCOL = 1;

private readonly peer: Peer;

constructor(peer: Peer) {
this.peer = peer;
}

async shown(params: EventsShownParams): Promise<boolean> {
const env = await this.peer.call(EventsSender.PROTOCOL, { id: 0, name: "shown" }, params, { layout: EventsShownParamsLayout });
if ("ok" in env) return this.peer.codec.decode<boolean>(env.ok, "bool");
if ("fault" in env) throw RuntimeError.provider();
throw RuntimeError.remote(env.err.id);
}

async ping(): Promise<void> {
await this.peer.notify(EventsSender.PROTOCOL, { id: 1, name: "ping" }, null, { layout: "unit" });
}
}

Loading
Loading