@williamthorsen/readout 0.0.0-stage → 0.1.0

package/.meta/changelog.json

@@ -0,0 +1,40 @@
+[
+  {
+    "version": "0.1.0",
+    "date": "2026-11-06",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds the `@williamthorsen/readout` package, whose `Readout` type pairs a result's data with a list of its sensitive top-level fields, and whose `serializeReadout` and `redactReadout` leave those fields out and name them under `redacted` unless the caller passes `includeSensitive: true`. (#8)",
+            "hash": "0495317f861e1f9f71b18aa0379a62dbfc77ce4c",
+            "entry": 1
+          },
+          {
+            "description": "Adds `embedJson`, which escapes every `<` in JSON text so that the text can be the content of a `<script type=\"application/json\">` element without closing the element or opening a comment. (#8)",
+            "hash": "0495317f861e1f9f71b18aa0379a62dbfc77ce4c",
+            "entry": 2
+          },
+          {
+            "description": "Adds the `Renderers` type, which maps each type of value to its renderer and fails the typecheck when a type lacks one, and the `render` function, which dispatches a value to the renderer for its `type`. (#8)",
+            "hash": "0495317f861e1f9f71b18aa0379a62dbfc77ce4c",
+            "entry": 3
+          }
+        ]
+      },
+      {
+        "title": "⚙️ Tooling",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Adds a `typecheck:post` script that typechecks the published source of `packages/readout` through `tsconfig.src.json`, which excludes the tests, so that the DOM lib loaded by a test's `/// <reference lib=\"dom\" />` cannot hide a DOM API used in `src/`. (#8)",
+            "hash": "0495317f861e1f9f71b18aa0379a62dbfc77ce4c",
+            "entry": 4
+          }
+        ]
+      }
+    ]
+  }
+]

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 — 2026-11-06
+
+### 🎉 Features
+
+- Adds the `@williamthorsen/readout` package, whose `Readout` type pairs a result's data with a list of its sensitive top-level fields, and whose `serializeReadout` and `redactReadout` leave those fields out and name them under `redacted` unless the caller passes `includeSensitive: true`. (#8)
+- Adds `embedJson`, which escapes every `<` in JSON text so that the text can be the content of a `<script type="application/json">` element without closing the element or opening a comment. (#8)
+- Adds the `Renderers` type, which maps each type of value to its renderer and fails the typecheck when a type lacks one, and the `render` function, which dispatches a value to the renderer for its `type`. (#8)
+
+### ⚙️ Tooling
+
+- Adds a `typecheck:post` script that typechecks the published source of `packages/readout` through `tsconfig.src.json`, which excludes the tests, so that the DOM lib loaded by a test's `/// <reference lib="dom" />` cannot hide a DOM API used in `src/`. (#8)
+
+<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 William Thorsen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+<!-- readme-type: library -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @williamthorsen/readout
+
+One result object that a person and a machine both read: a redacting JSON serializer, a DOM-embedding helper, and typed renderers over the same object.
+
+<!-- section:release-notes -->
+## Release notes — v0.1.0 (2026-11-06)
+
+### 🎉 Features
+
+- Adds the `@williamthorsen/readout` package, whose `Readout` type pairs a result's data with a list of its sensitive top-level fields, and whose `serializeReadout` and `redactReadout` leave those fields out and name them under `redacted` unless the caller passes `includeSensitive: true`. (#8)
+- Adds `embedJson`, which escapes every `<` in JSON text so that the text can be the content of a `<script type="application/json">` element without closing the element or opening a comment. (#8)
+- Adds the `Renderers` type, which maps each type of value to its renderer and fails the typecheck when a type lacks one, and the `render` function, which dispatches a value to the renderer for its `type`. (#8)
+<!-- /section:release-notes -->
+
+```ts
+import { type Readout, serializeReadout } from '@williamthorsen/readout';
+
+const readout: Readout<{ id: string; secret: string }> = { data: { id: 'tok-1', secret: 'ATATT-…' }, sensitive: ['secret'] };
+serializeReadout(readout); // {"id": "tok-1", "redacted": ["secret"]}, indented by two spaces
+```
+
+## Why
+
+A result that an app shows to a person, such as a created token or a check's outcome, also has a reader that drives the app: an agent, a script, or an end-to-end test. When the result exists only as formatted text, that reader parses prose that changes whenever the wording does. `readout` keeps the result as one object in canonical values and renders every form from it, so that the forms cannot disagree. The convention that it implements is the `machine-readable-output-conventions` rulebook in [codeassembly-guidance](https://github.com/williamthorsen/codeassembly-guidance).
+
+Hand-rolled `JSON.stringify` covers the machine form, but each call site then decides on its own what to leave out, and a secret reaches a page snapshot through the call site that forgot. A readout declares its sensitive fields once, in its type.
+
+The package has no runtime dependency and uses neither DOM nor Node APIs, so it runs in a browser and in Node alike.
+
+## One readout, two forms
+
+```ts
+import { embedJson, type Readout, render, type Renderers, serializeReadout } from '@williamthorsen/readout';
+
+interface TokenCreated {
+  type: 'created';
+  id: string;
+  expiresAt: string;
+  secret: string;
+}
+
+const readout: Readout<TokenCreated> = {
+  data: { type: 'created', id: 'tok-1', expiresAt: '2026-11-12T00:00:00Z', secret: 'ATATT-…' },
+  sensitive: ['secret'],
+};
+
+// For a person: one renderer per type, which the typecheck holds to every type in the map.
+const sentences: Renderers<{ created: TokenCreated }> = {
+  created: (value) => `Created token ${value.id}, which expires on ${value.expiresAt.slice(0, 10)}`,
+};
+render(readout.data, sentences); // 'Created token tok-1, which expires on 2026-11-12'
+
+// For a machine: the copy, and the same text embedded in the page for a driven browser.
+const json = serializeReadout(readout);
+const script = `<script type="application/json" id="token-data">${embedJson(json)}</script>`;
+```
+
+## Contract
+
+- **Sensitive fields.** `serializeReadout` and `redactReadout` leave out each field named in `sensitive` and list it under `redacted`, so that a reader can tell a redacted field from an absent one. `{ includeSensitive: true }` keeps every field and omits `redacted`. Because `redacted` is reserved, the type rejects data with a field of that name. Only top-level fields can be marked sensitive.
+- **Serialization.** `serializeReadout` returns JSON indented by two spaces. `redactReadout` returns the object that it serializes.
+- **Embedding.** `embedJson` escapes every `<` in JSON text as `\u003c`, so that the content of a `<script type="application/json">` element cannot close the element or open a comment, and `JSON.parse` of the element's text returns the serialized value. It takes JSON text, not a readout, so that any serialization embeds through it.
+- **Renderers.** `Renderers<M, R>` maps each type in `M`, a map from a type to the shape of its values, to a renderer that returns `R` (a string by default). `render` dispatches a value to the renderer for its `type`. JSON is not a renderer, because `serializeReadout` is the machine form.

package/dist/esm/embed-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns JSON text that is safe as the content of a `<script type="application/json">` element and parses to the same
+ * value. In valid JSON, `<` occurs only inside a string, where its escape is equivalent, so escaping it means that the
+ * content can neither close the element nor open a comment.
+ */
+export declare function embedJson(json: string): string;

package/dist/esm/embed-json.js

@@ -0,0 +1,3 @@
+export function embedJson(json) {
+    return json.replaceAll('<', String.raw `\u003c`);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { embedJson } from './embed-json.js';
+export { type Readout, type ReadoutData, redactReadout, type SerializeOptions, serializeReadout } from './readout.js';
+export { render, type Renderers, type TypedValues } from './renderers.js';

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { embedJson } from "./embed-json.js";
+export { redactReadout, serializeReadout } from "./readout.js";
+export { render } from "./renderers.js";

package/dist/esm/readout.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A result that a program shows to a person and also exposes as data, with the fields that the data leaves out unless
+ * the caller asks for them. `redacted` is reserved, because the redacted form names the fields that it leaves out under
+ * that key.
+ */
+export interface Readout<T extends ReadoutData> {
+    data: T;
+    /** The fields that a serialization leaves out by default and names under `redacted`, such as a credential. */
+    sensitive: readonly (keyof T & string)[];
+}
+/** The data of a readout: an object without a field named `redacted`. */
+export type ReadoutData = object & {
+    redacted?: never;
+};
+/** How a readout is serialized. */
+export interface SerializeOptions {
+    /** Keeps every sensitive field and omits `redacted`. Off by default. */
+    includeSensitive?: boolean;
+}
+/**
+ * Returns the readout's data without its sensitive fields and with `redacted` naming each one that it leaves out, so
+ * that a reader can tell a redacted field from an absent one. With `includeSensitive`, returns every field.
+ */
+export declare function redactReadout<T extends ReadoutData>(readout: Readout<T>, options?: SerializeOptions): Record<string, unknown>;
+/** Serializes the readout as indented JSON, without its sensitive fields unless `includeSensitive` is set. */
+export declare function serializeReadout<T extends ReadoutData>(readout: Readout<T>, options?: SerializeOptions): string;

package/dist/esm/readout.js

@@ -0,0 +1,15 @@
+export function redactReadout(readout, options = {}) {
+    const sensitive = new Set(options.includeSensitive === true ? [] : readout.sensitive);
+    const kept = {};
+    const redacted = [];
+    for (const [key, value] of Object.entries(readout.data)) {
+        if (sensitive.has(key))
+            redacted.push(key);
+        else
+            kept[key] = value;
+    }
+    return redacted.length > 0 ? { ...kept, redacted } : kept;
+}
+export function serializeReadout(readout, options = {}) {
+    return JSON.stringify(redactReadout(readout, options), null, 2);
+}

package/dist/esm/renderers.d.ts

@@ -0,0 +1,14 @@
+/** A map from each type of value to the value's shape, in which each value names its own type. */
+export type TypedValues<M> = {
+    [K in keyof M]: {
+        type: K;
+    };
+};
+/** One renderer per type in the map, so that the typecheck reports a type without one; each returns the form `R`. */
+export type Renderers<M extends TypedValues<M>, R = string> = {
+    [K in keyof M & string]: (value: M[K]) => R;
+};
+/** Renders a value through the renderer for its type. */
+export declare function render<M extends TypedValues<M>, K extends keyof M & string, R>(value: M[K] & {
+    type: K;
+}, renderers: Renderers<M, R>): R;

package/dist/esm/renderers.js

@@ -0,0 +1,3 @@
+export function render(value, renderers) {
+    return renderers[value.type](value);
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@williamthorsen/readout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "description": "One result object for people and machines: redacting JSON serializer, DOM embedding, and typed renderers",
+  "keywords": [
+    "json",
+    "machine-readable",
+    "readout",
+    "redaction",
+    "renderer"
+  ],
+  "homepage": "https://github.com/williamthorsen/showroom/tree/main/packages/readout#readme",
+  "bugs": {
+    "url": "https://github.com/williamthorsen/showroom/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/williamthorsen/showroom.git",
+    "directory": "packages/readout"
+  },
+  "license": "ISC",
+  "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/esm/index.d.ts"
+    }
+  },
+  "files": [
+    ".meta/changelog.json",
+    "CHANGELOG.md",
+    "dist"
+  ],
+  "devDependencies": {
+    "@williamthorsen/nmr": "0.54.0",
+    "vitest": "5.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck:post": "tsgo --noEmit --project tsconfig.src.json"
+  }
 }