@bytecodealliance/preview2-shim 0.0.8 → 0.0.10

package/types/imports/streams.d.ts

@@ -1,23 +1,180 @@
-export namespace Streams {
+export namespace ImportsStreams {
+  /**
+   * Read bytes from a stream.
+   * 
+   * This function returns a list of bytes containing the data that was
+   * read, along with a bool which, when true, indicates that the end of the
+   * stream was reached. The returned list will contain up to `len` bytes; it
+   * may return fewer than requested, but not more.
+   * 
+   * Once a stream has reached the end, subsequent calls to read or
+   * `skip` will always report end-of-stream rather than producing more
+   * data.
+   * 
+   * If `len` is 0, it represents a request to read 0 bytes, which should
+   * always succeed, assuming the stream hasn't reached its end yet, and
+   * return an empty list.
+   * 
+   * The len here is a `u64`, but some callees may not be able to allocate
+   * a buffer as large as that would imply.
+   * FIXME: describe what happens if allocation fails.
+   */
   export function read(this: InputStream, len: bigint): [Uint8Array | ArrayBuffer, boolean];
+  /**
+   * Read bytes from a stream, with blocking.
+   * 
+   * This is similar to `read`, except that it blocks until at least one
+   * byte can be read.
+   */
   export function blockingRead(this: InputStream, len: bigint): [Uint8Array | ArrayBuffer, boolean];
+  /**
+   * Skip bytes from a stream.
+   * 
+   * This is similar to the `read` function, but avoids copying the
+   * bytes into the instance.
+   * 
+   * Once a stream has reached the end, subsequent calls to read or
+   * `skip` will always report end-of-stream rather than producing more
+   * data.
+   * 
+   * This function returns the number of bytes skipped, along with a bool
+   * indicating whether the end of the stream was reached. The returned
+   * value will be at most `len`; it may be less.
+   */
   export function skip(this: InputStream, len: bigint): [bigint, boolean];
+  /**
+   * Skip bytes from a stream, with blocking.
+   * 
+   * This is similar to `skip`, except that it blocks until at least one
+   * byte can be consumed.
+   */
   export function blockingSkip(this: InputStream, len: bigint): [bigint, boolean];
+  /**
+   * Create a `pollable` which will resolve once either the specified stream
+   * has bytes available to read or the other end of the stream has been
+   * closed.
+   */
   export function subscribeToInputStream(this: InputStream): Pollable;
+  /**
+   * Dispose of the specified `input-stream`, after which it may no longer
+   * be used.
+   */
   export function dropInputStream(this: InputStream): void;
+  /**
+   * Write bytes to a stream.
+   * 
+   * This function returns a `u64` indicating the number of bytes from
+   * `buf` that were written; it may be less than the full list.
+   */
   export function write(this: OutputStream, buf: Uint8Array): bigint;
+  /**
+   * Write bytes to a stream, with blocking.
+   * 
+   * This is similar to `write`, except that it blocks until at least one
+   * byte can be written.
+   */
   export function blockingWrite(this: OutputStream, buf: Uint8Array): bigint;
+  /**
+   * Write multiple zero bytes to a stream.
+   * 
+   * This function returns a `u64` indicating the number of zero bytes
+   * that were written; it may be less than `len`.
+   */
   export function writeZeroes(this: OutputStream, len: bigint): bigint;
+  /**
+   * Write multiple zero bytes to a stream, with blocking.
+   * 
+   * This is similar to `write-zeroes`, except that it blocks until at least
+   * one byte can be written.
+   */
   export function blockingWriteZeroes(this: OutputStream, len: bigint): bigint;
+  /**
+   * Read from one stream and write to another.
+   * 
+   * This function returns the number of bytes transferred; it may be less
+   * than `len`.
+   * 
+   * Unlike other I/O functions, this function blocks until all the data
+   * read from the input stream has been written to the output stream.
+   */
   export function splice(this: OutputStream, src: InputStream, len: bigint): [bigint, boolean];
+  /**
+   * Read from one stream and write to another, with blocking.
+   * 
+   * This is similar to `splice`, except that it blocks until at least
+   * one byte can be read.
+   */
   export function blockingSplice(this: OutputStream, src: InputStream, len: bigint): [bigint, boolean];
+  /**
+   * Forward the entire contents of an input stream to an output stream.
+   * 
+   * This function repeatedly reads from the input stream and writes
+   * the data to the output stream, until the end of the input stream
+   * is reached, or an error is encountered.
+   * 
+   * Unlike other I/O functions, this function blocks until the end
+   * of the input stream is seen and all the data has been written to
+   * the output stream.
+   * 
+   * This function returns the number of bytes transferred.
+   */
   export function forward(this: OutputStream, src: InputStream): bigint;
+  /**
+   * Create a `pollable` which will resolve once either the specified stream
+   * is ready to accept bytes or the other end of the stream has been closed.
+   */
   export function subscribeToOutputStream(this: OutputStream): Pollable;
+  /**
+   * Dispose of the specified `output-stream`, after which it may no longer
+   * be used.
+   */
   export function dropOutputStream(this: OutputStream): void;
 }
-export type InputStream = number;
-export interface StreamError {
-}
 import type { Pollable } from '../imports/poll';
 export { Pollable };
+/**
+ * An error type returned from a stream operation. Currently this
+ * doesn't provide any additional information.
+ */
+export interface StreamError {
+}
+/**
+ * An output bytestream. In the future, this will be replaced by handle
+ * types.
+ * 
+ * This conceptually represents a `stream<u8, _>`. It's temporary
+ * scaffolding until component-model's async features are ready.
+ * 
+ * `output-stream`s are *non-blocking* to the extent practical on
+ * underlying platforms. Except where specified otherwise, I/O operations also
+ * always return promptly, after the number of bytes that can be written
+ * promptly, which could even be zero. To wait for the stream to be ready to
+ * accept data, the `subscribe-to-output-stream` function to obtain a
+ * `pollable` which can be polled for using `wasi_poll`.
+ * 
+ * And at present, it is a `u32` instead of being an actual handle, until
+ * the wit-bindgen implementation of handles and resources is ready.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
 export type OutputStream = number;
+/**
+ * An input bytestream. In the future, this will be replaced by handle
+ * types.
+ * 
+ * This conceptually represents a `stream<u8, _>`. It's temporary
+ * scaffolding until component-model's async features are ready.
+ * 
+ * `input-stream`s are *non-blocking* to the extent practical on underlying
+ * platforms. I/O operations always return promptly; if fewer bytes are
+ * promptly available than requested, they return the number of bytes promptly
+ * available, which could even be zero. To wait for data to be available,
+ * use the `subscribe-to-input-stream` function to obtain a `pollable` which
+ * can be polled for using `wasi_poll`.
+ * 
+ * And at present, it is a `u32` instead of being an actual handle, until
+ * the wit-bindgen implementation of handles and resources is ready.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type InputStream = number;

package/types/imports/tcp-create-socket.d.ts

@@ -1,9 +1,33 @@
-export namespace TcpCreateSocket {
+export namespace ImportsTcpCreateSocket {
+  /**
+   * Create a new TCP socket.
+   * 
+   * Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX.
+   * 
+   * This function does not require a network capability handle. This is considered to be safe because
+   * at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`listen`/`connect`
+   * is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
+   * 
+   * All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
+   * 
+   * # Typical errors
+   * - `not-supported`:                The host does not support TCP sockets. (EOPNOTSUPP)
+   * - `address-family-not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
+   * - `new-socket-limit`:             The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
+   * - <https://man7.org/linux/man-pages/man2/socket.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
+   */
   export function createTcpSocket(addressFamily: IpAddressFamily): TcpSocket;
 }
+import type { Network } from '../imports/network';
+export { Network };
+import type { ErrorCode } from '../imports/network';
+export { ErrorCode };
 import type { IpAddressFamily } from '../imports/network';
 export { IpAddressFamily };
 import type { TcpSocket } from '../imports/tcp';
 export { TcpSocket };
-import type { Error } from '../imports/network';
-export { Error };

package/types/imports/tcp.d.ts

@@ -1,52 +1,285 @@
-export namespace Tcp {
-  export function bind(this: TcpSocket, network: Network, localAddress: IpSocketAddress): void;
-  export function connect(this: TcpSocket, network: Network, remoteAddress: IpSocketAddress): [InputStream, OutputStream];
-  export function listen(this: TcpSocket, network: Network): void;
+export namespace ImportsTcp {
+  /**
+   * Bind the socket to a specific network on the provided IP address and port.
+   * 
+   * If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
+   * network interface(s) to bind to.
+   * If the TCP/UDP port is zero, the socket will be bound to a random free port.
+   * 
+   * When a socket is not explicitly bound, the first invocation to a listen or connect operation will
+   * implicitly bind the socket.
+   * 
+   * Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+   * 
+   * # Typical `start` errors
+   * - `address-family-mismatch`:   The `local-address` has the wrong address family. (EINVAL)
+   * - `already-bound`:             The socket is already bound. (EINVAL)
+   * - `concurrency-conflict`:      Another `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   * 
+   * # Typical `finish` errors
+   * - `ephemeral-ports-exhausted`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
+   * - `address-in-use`:            Address is already in use. (EADDRINUSE)
+   * - `address-not-bindable`:      `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
+   * - `not-in-progress`:           A `bind` operation is not in progress.
+   * - `would-block`:               Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
+   * - <https://man7.org/linux/man-pages/man2/bind.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
+   */
+  export function startBind(this: TcpSocket, network: Network, localAddress: IpSocketAddress): void;
+  export function finishBind(this: TcpSocket): void;
+  /**
+   * Connect to a remote endpoint.
+   * 
+   * On success:
+   * - the socket is transitioned into the Connection state
+   * - a pair of streams is returned that can be used to read & write to the connection
+   * 
+   * # Typical `start` errors
+   * - `address-family-mismatch`:   The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+   * - `invalid-remote-address`:    The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
+   * - `invalid-remote-address`:    The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
+   * - `already-attached`:          The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
+   * - `already-connected`:         The socket is already in the Connection state. (EISCONN)
+   * - `already-listening`:         The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
+   * - `concurrency-conflict`:      Another `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   * 
+   * # Typical `finish` errors
+   * - `timeout`:                   Connection timed out. (ETIMEDOUT)
+   * - `connection-refused`:        The connection was forcefully rejected. (ECONNREFUSED)
+   * - `connection-reset`:          The connection was reset. (ECONNRESET)
+   * - `remote-unreachable`:        The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)
+   * - `ephemeral-ports-exhausted`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
+   * - `not-in-progress`:           A `connect` operation is not in progress.
+   * - `would-block`:               Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
+   * - <https://man7.org/linux/man-pages/man2/connect.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
+   * - <https://man.freebsd.org/cgi/man.cgi?connect>
+   */
+  export function startConnect(this: TcpSocket, network: Network, remoteAddress: IpSocketAddress): void;
+  export function finishConnect(this: TcpSocket): [InputStream, OutputStream];
+  /**
+   * Start listening for new connections.
+   * 
+   * Transitions the socket into the Listener state.
+   * 
+   * Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+   * 
+   * # Typical `start` errors
+   * - `already-attached`:          The socket is already attached to a different network. The `network` passed to `listen` must be identical to the one passed to `bind`.
+   * - `already-connected`:         The socket is already in the Connection state. (EISCONN, EINVAL on BSD)
+   * - `already-listening`:         The socket is already in the Listener state.
+   * - `concurrency-conflict`:      Another `bind`, `connect` or `listen` operation is already in progress. (EINVAL on BSD)
+   * 
+   * # Typical `finish` errors
+   * - `ephemeral-ports-exhausted`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
+   * - `not-in-progress`:           A `listen` operation is not in progress.
+   * - `would-block`:               Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
+   * - <https://man7.org/linux/man-pages/man2/listen.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
+   */
+  export function startListen(this: TcpSocket, network: Network): void;
+  export function finishListen(this: TcpSocket): void;
+  /**
+   * Accept a new client socket.
+   * 
+   * The returned socket is bound and in the Connection state.
+   * 
+   * On success, this function returns the newly accepted client socket along with
+   * a pair of streams that can be used to read & write to the connection.
+   * 
+   * # Typical errors
+   * - `not-listening`: Socket is not in the Listener state. (EINVAL)
+   * - `would-block`:   No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
+   * 
+   * Host implementations must skip over transient errors returned by the native accept syscall.
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
+   * - <https://man7.org/linux/man-pages/man2/accept.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
+   */
   export function accept(this: TcpSocket): [TcpSocket, InputStream, OutputStream];
+  /**
+   * Get the bound local address.
+   * 
+   * # Typical errors
+   * - `not-bound`: The socket is not bound to any local address.
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
+   * - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
+   * - <https://man.freebsd.org/cgi/man.cgi?getsockname>
+   */
   export function localAddress(this: TcpSocket): IpSocketAddress;
+  /**
+   * Get the bound remote address.
+   * 
+   * # Typical errors
+   * - `not-connected`: The socket is not connected to a remote address. (ENOTCONN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
+   * - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
+   */
   export function remoteAddress(this: TcpSocket): IpSocketAddress;
+  /**
+   * Whether this is a IPv4 or IPv6 socket.
+   * 
+   * Equivalent to the SO_DOMAIN socket option.
+   */
   export function addressFamily(this: TcpSocket): IpAddressFamily;
+  /**
+   * Whether IPv4 compatibility (dual-stack) mode is disabled or not.
+   * 
+   * Equivalent to the IPV6_V6ONLY socket option.
+   * 
+   * # Typical errors
+   * - `ipv6-only-operation`:  (get/set) `this` socket is an IPv4 socket.
+   * - `already-bound`:        (set) The socket is already bound.
+   * - `not-supported`:        (set) Host does not support dual-stack sockets. (Implementations are not required to.)
+   * - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   */
   export function ipv6Only(this: TcpSocket): boolean;
   export function setIpv6Only(this: TcpSocket, value: boolean): void;
+  /**
+   * Hints the desired listen queue size. Implementations are free to ignore this.
+   * 
+   * # Typical errors
+   * - `already-connected`:    (set) The socket is already in the Connection state.
+   * - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   */
   export function setListenBacklogSize(this: TcpSocket, value: bigint): void;
+  /**
+   * Equivalent to the SO_KEEPALIVE socket option.
+   * 
+   * # Typical errors
+   * - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   */
   export function keepAlive(this: TcpSocket): boolean;
   export function setKeepAlive(this: TcpSocket, value: boolean): void;
+  /**
+   * Equivalent to the TCP_NODELAY socket option.
+   * 
+   * # Typical errors
+   * - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   */
   export function noDelay(this: TcpSocket): boolean;
   export function setNoDelay(this: TcpSocket, value: boolean): void;
+  /**
+   * Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+   * 
+   * # Typical errors
+   * - `already-connected`:    (set) The socket is already in the Connection state.
+   * - `already-listening`:    (set) The socket is already in the Listener state.
+   * - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   */
   export function unicastHopLimit(this: TcpSocket): number;
   export function setUnicastHopLimit(this: TcpSocket, value: number): void;
+  /**
+   * The kernel buffer space reserved for sends/receives on this socket.
+   * 
+   * Note #1: an implementation may choose to cap or round the buffer size when setting the value.
+   * In other words, after setting a value, reading the same setting back may return a different value.
+   * 
+   * Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
+   * actual data to be sent/received by the application, because the kernel might also use the buffer space
+   * for internal metadata structures.
+   * 
+   * Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
+   * 
+   * # Typical errors
+   * - `already-connected`:    (set) The socket is already in the Connection state.
+   * - `already-listening`:    (set) The socket is already in the Listener state.
+   * - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+   */
   export function receiveBufferSize(this: TcpSocket): bigint;
   export function setReceiveBufferSize(this: TcpSocket, value: bigint): void;
   export function sendBufferSize(this: TcpSocket): bigint;
   export function setSendBufferSize(this: TcpSocket, value: bigint): void;
-  export function nonBlocking(this: TcpSocket): boolean;
-  export function setNonBlocking(this: TcpSocket, value: boolean): void;
+  /**
+   * Create a `pollable` which will resolve once the socket is ready for I/O.
+   * 
+   * Note: this function is here for WASI Preview2 only.
+   * It's planned to be removed when `future` is natively supported in Preview3.
+   */
   export function subscribe(this: TcpSocket): Pollable;
+  /**
+   * Initiate a graceful shutdown.
+   * 
+   * - receive: the socket is not expecting to receive any more data from the peer. All subsequent read
+   * operations on the `input-stream` associated with this socket will return an End Of Stream indication.
+   * Any data still in the receive queue at time of calling `shutdown` will be discarded.
+   * - send: the socket is not expecting to send any more data to the peer. All subsequent write
+   * operations on the `output-stream` associated with this socket will return an error.
+   * - both: same effect as receive & send combined.
+   * 
+   * The shutdown function does not close (drop) the socket.
+   * 
+   * # Typical errors
+   * - `not-connected`: The socket is not in the Connection state. (ENOTCONN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
+   * - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
+   */
   export function shutdown(this: TcpSocket, shutdownType: ShutdownType): void;
+  /**
+   * Dispose of the specified `tcp-socket`, after which it may no longer be used.
+   * 
+   * Similar to the POSIX `close` function.
+   * 
+   * Note: this function is scheduled to be removed when Resources are natively supported in Wit.
+   */
   export function dropTcpSocket(this: TcpSocket): void;
 }
-export type TcpSocket = number;
-import type { Network } from '../imports/network';
-export { Network };
-import type { IpSocketAddress } from '../imports/network';
-export { IpSocketAddress };
-import type { Error } from '../imports/network';
-export { Error };
 import type { InputStream } from '../imports/streams';
 export { InputStream };
 import type { OutputStream } from '../imports/streams';
 export { OutputStream };
-import type { IpAddressFamily } from '../imports/network';
-export { IpAddressFamily };
 import type { Pollable } from '../imports/poll';
 export { Pollable };
+import type { Network } from '../imports/network';
+export { Network };
+import type { ErrorCode } from '../imports/network';
+export { ErrorCode };
+import type { IpSocketAddress } from '../imports/network';
+export { IpSocketAddress };
+import type { IpAddressFamily } from '../imports/network';
+export { IpAddressFamily };
+/**
+ * A TCP socket handle.
+ */
+export type TcpSocket = number;
 /**
  * # Variants
  * 
  * ## `"receive"`
  * 
+ * Similar to `SHUT_RD` in POSIX.
+ * 
  * ## `"send"`
  * 
+ * Similar to `SHUT_WR` in POSIX.
+ * 
  * ## `"both"`
+ * 
+ * Similar to `SHUT_RDWR` in POSIX.
  */
 export type ShutdownType = 'receive' | 'send' | 'both';

package/types/imports/timezone.d.ts

@@ -1,13 +1,71 @@
-export namespace Timezone {
+export namespace ImportsTimezone {
+  /**
+   * Return information needed to display the given `datetime`. This includes
+   * the UTC offset, the time zone name, and a flag indicating whether
+   * daylight saving time is active.
+   * 
+   * If the timezone cannot be determined for the given `datetime`, return a
+   * `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
+   * saving time.
+   */
   export function display(this: Timezone, when: Datetime): TimezoneDisplay;
+  /**
+   * The same as `display`, but only return the UTC offset.
+   */
   export function utcOffset(this: Timezone, when: Datetime): number;
+  /**
+   * Dispose of the specified input-stream, after which it may no longer
+   * be used.
+   */
   export function dropTimezone(this: Timezone): void;
 }
-export type Timezone = number;
 import type { Datetime } from '../imports/wall-clock';
 export { Datetime };
+/**
+ * Information useful for displaying the timezone of a specific `datetime`.
+ * 
+ * This information may vary within a single `timezone` to reflect daylight
+ * saving time adjustments.
+ */
 export interface TimezoneDisplay {
+  /**
+   * The number of seconds difference between UTC time and the local
+   * time of the timezone.
+   * 
+   * The returned value will always be less than 86400 which is the
+   * number of seconds in a day (24*60*60).
+   * 
+   * In implementations that do not expose an actual time zone, this
+   * should return 0.
+   */
   utcOffset: number,
+  /**
+   * The abbreviated name of the timezone to display to a user. The name
+   * `UTC` indicates Coordinated Universal Time. Otherwise, this should
+   * reference local standards for the name of the time zone.
+   * 
+   * In implementations that do not expose an actual time zone, this
+   * should be the string `UTC`.
+   * 
+   * In time zones that do not have an applicable name, a formatted
+   * representation of the UTC offset may be returned, such as `-04:00`.
+   */
   name: string,
+  /**
+   * Whether daylight saving time is active.
+   * 
+   * In implementations that do not expose an actual time zone, this
+   * should return false.
+   */
   inDaylightSavingTime: boolean,
 }
+/**
+ * A timezone.
+ * 
+ * In timezones that recognize daylight saving time, also known as daylight
+ * time and summer time, the information returned from the functions varies
+ * over time to reflect these adjustments.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type Timezone = number;

package/types/imports/types.d.ts

@@ -1,4 +1,4 @@
-export namespace Types {
+export namespace ImportsTypes {
   export function dropFields(fields: Fields): void;
   export function newFields(entries: [string, string][]): Fields;
   export function fieldsGet(fields: Fields, name: string): string[];
@@ -33,15 +33,32 @@ export namespace Types {
   export function futureIncomingResponseGet(f: FutureIncomingResponse): Result<IncomingResponse, Error> | null;
   export function listenToFutureIncomingResponse(f: FutureIncomingResponse): Pollable;
 }
-export type Fields = number;
 import type { InputStream } from '../imports/streams';
 export { InputStream };
-export type IncomingStream = InputStream;
-export type Trailers = Fields;
 import type { OutputStream } from '../imports/streams';
 export { OutputStream };
+import type { Pollable } from '../imports/poll';
+export { Pollable };
+export type StatusCode = number;
+export type Scheme = SchemeHttp | SchemeHttps | SchemeOther;
+export interface SchemeHttp {
+  tag: 'HTTP',
+}
+export interface SchemeHttps {
+  tag: 'HTTPS',
+}
+export interface SchemeOther {
+  tag: 'other',
+  val: string,
+}
+export type ResponseOutparam = number;
+export interface RequestOptions {
+  connectTimeoutMs?: number,
+  firstByteTimeoutMs?: number,
+  betweenBytesTimeoutMs?: number,
+}
 export type OutgoingStream = OutputStream;
-export type IncomingRequest = number;
+export type OutgoingResponse = number;
 export type OutgoingRequest = number;
 export type Method = MethodGet | MethodHead | MethodPost | MethodPut | MethodDelete | MethodConnect | MethodOptions | MethodTrace | MethodPatch | MethodOther;
 export interface MethodGet {
@@ -75,20 +92,13 @@ export interface MethodOther {
   tag: 'other',
   val: string,
 }
-export type Scheme = SchemeHttp | SchemeHttps | SchemeOther;
-export interface SchemeHttp {
-  tag: 'HTTP',
-}
-export interface SchemeHttps {
-  tag: 'HTTPS',
-}
-export interface SchemeOther {
-  tag: 'other',
-  val: string,
-}
+export type IncomingStream = InputStream;
+export type IncomingResponse = number;
+export type IncomingRequest = number;
+export type FutureIncomingResponse = number;
+export type Fields = number;
+export type Trailers = Fields;
 export type Headers = Fields;
-export type ResponseOutparam = number;
-export type OutgoingResponse = number;
 export type Error = ErrorInvalidUrl | ErrorTimeoutError | ErrorProtocolError | ErrorUnexpectedError;
 export interface ErrorInvalidUrl {
   tag: 'invalid-url',
@@ -106,14 +116,4 @@ export interface ErrorUnexpectedError {
   tag: 'unexpected-error',
   val: string,
 }
-export type IncomingResponse = number;
-export type StatusCode = number;
-export type FutureIncomingResponse = number;
-import type { Pollable } from '../imports/poll';
-export { Pollable };
-export interface RequestOptions {
-  connectTimeoutMs?: number,
-  firstByteTimeoutMs?: number,
-  betweenBytesTimeoutMs?: number,
-}
 export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };