diff --git a/docs/content/1.getting-started/2.installation.md b/docs/content/1.getting-started/2.installation.md index 8257570f9..ca7313d2d 100644 --- a/docs/content/1.getting-started/2.installation.md +++ b/docs/content/1.getting-started/2.installation.md @@ -48,6 +48,7 @@ Besides the providers, the package has a few more subpaths for specific jobs: | `forges/fake` | An in-memory forge for [tests](/guides/testing) | | `forges/testing` | Fixture replay and webhook signing for [tests](/guides/testing) | | `forges/schema` | [JSON Schemas](/reference/json-schemas) for the models, and every verb signature | +| `forges/wire` | Encode and decode dates and bytes when models cross JSON | | `forges/kit` | Building blocks for [writing a provider](/contributing/write-a-provider) | ## Browsers diff --git a/docs/content/5.reference/14.json-schemas.md b/docs/content/5.reference/14.json-schemas.md index 781e84145..9e8b982a9 100644 --- a/docs/content/5.reference/14.json-schemas.md +++ b/docs/content/5.reference/14.json-schemas.md @@ -38,8 +38,8 @@ If you need a file, `forges/schema/.json` contains one type as a standalon ```ts import Ajv from 'ajv' -import { reviveDates } from 'forges' import thread from 'forges/schema/Thread.json' with { type: 'json' } +import { decode } from 'forges/wire' const validate = new Ajv({ strict: false, validateFormats: false }).compile(thread) @@ -48,15 +48,15 @@ if (!validate(stored)) { throw new Error('Not a Thread') } -// JSON has no dates, so turn the ISO strings back into `Date`s. -const value = reviveDates(stored) +// Turn the tagged dates and bytes back into `Date`s and `Uint8Array`s. +const value = decode(stored) ``` ## What the models say A few conventions apply to every model: -- `Date` fields are `{ type: 'string', format: 'date-time' }`, because JSON has no dates. To turn them back into dates, use [`reviveDates()`](/reference/data-model#revivedates). +- `Date` fields are `{ "$date": "" }`; the inner string uses `format: date-time`. Use [`decode()`](/reference/wire) to turn the object back into a `Date`. - JSON can't carry bytes, so `Uint8Array` fields, such as the content of a binary file, are `{ "$bytes": "" }`. - A listing result is `PageOf`, the schema of `Page` with its `items` of that type. - The `raw` and `payload` fields accept anything, because they hold the response of the forge as it was. diff --git a/docs/content/5.reference/15.wire.md b/docs/content/5.reference/15.wire.md new file mode 100644 index 000000000..cdb2d5100 --- /dev/null +++ b/docs/content/5.reference/15.wire.md @@ -0,0 +1,29 @@ +--- +title: Wire codec +description: Encode and decode the dates and bytes in forges models when they cross JSON. +icon: i-lucide-arrow-left-right +--- + +JSON has no `Date` or `Uint8Array`. `forges` returns both in its model values, so anything that stores them or sends them over HTTP must encode them first. + +Most code does not need this. Providers already return real `Date` and `Uint8Array` values. Use `forges/wire` only when model values cross a JSON boundary, such as storage, a worker, or a proxy. + +`forges/wire` exports `encode()` and `decode()` for that boundary. + +```ts +import { decode, encode } from 'forges/wire' + +const wire = encode(result) +const value = decode(JSON.parse(JSON.stringify(wire))) +``` + +## Tags + +`encode()` replaces values that JSON cannot represent: + +- `Date` becomes `{ "$date": "" }`. +- `Uint8Array` becomes `{ "$bytes": "" }`. + +Everything else is copied unchanged. + +`decode()` is strict: a malformed `$date` or `$bytes` tag throws a `TypeError`. diff --git a/package.json b/package.json index c6e729f7e..5144af45b 100644 --- a/package.json +++ b/package.json @@ -62,6 +62,7 @@ "./tangled": "./src/tangled/index.ts", "./testing": "./src/testing/index.ts", "./web": "./src/web/index.ts", + "./wire": "./src/wire.ts", "./package.json": "./package.json", "./schema/*.json": "./dist/schema/*.json" }, @@ -90,6 +91,7 @@ "./tangled": "./dist/tangled/index.mjs", "./testing": "./dist/testing/index.mjs", "./web": "./dist/web/index.mjs", + "./wire": "./dist/wire.mjs", "./package.json": "./package.json", "./schema/*.json": "./dist/schema/*.json" } diff --git a/scripts/api-docs/config.ts b/scripts/api-docs/config.ts index 269fd1720..662abc264 100644 --- a/scripts/api-docs/config.ts +++ b/scripts/api-docs/config.ts @@ -146,10 +146,6 @@ const DATA_MODEL_SECTIONS: SectionConfig[] = [ title: 'Notifications and events', names: [/^(?:Notification|BulkNotification|ForgeEvent|Event|PushCommit|SourceKind|StreamOptions|StreamItem)/], }, - { - title: 'Dates', - names: ['reviveDates', 'DATE_FIELDS'], - }, ] export const OVERVIEW_INTRO = '`forges` is one client for every forge. You create a provider for each forge that you use, call the same operations on all of them, such as `provider.threads.merge()`, and get the same objects back.' diff --git a/scripts/bundle-size.ts b/scripts/bundle-size.ts index 182188210..a8b455a81 100644 --- a/scripts/bundle-size.ts +++ b/scripts/bundle-size.ts @@ -65,6 +65,11 @@ const BUNDLES: Array<{ name: string, source: string, imports: string, absent?: s absent: 'x-github-api-version', budget: 10_000, }, + { + name: 'forges/wire', + source: 'wire.mjs', + imports: 'decode, encode', + }, ] interface Size { diff --git a/scripts/generate-schemas.ts b/scripts/generate-schemas.ts index fd1559a99..3ebd42251 100644 --- a/scripts/generate-schemas.ts +++ b/scripts/generate-schemas.ts @@ -10,7 +10,7 @@ import { readFileSync, writeFileSync } from 'node:fs' import process from 'node:process' import { fileURLToPath, pathToFileURL } from 'node:url' import { createGenerator } from 'ts-json-schema-generator' -import { BYTES_SCHEMA, isRecord, refs, sortByKey, tidyDescriptions } from './schema/json.ts' +import { isRecord, refs, sortByKey, tidyDescriptions, wireSchema } from './schema/json.ts' import { generateVerbSignatures } from './schema/verbs.ts' /** Model types a schema is generated for; their dependencies are included. */ @@ -80,23 +80,6 @@ function rewriteRefs(value: Json, prefix: string): Json { ])) } -function replaceByteArrays(value: Json): Json { - if (Array.isArray(value)) { - return value.map(replaceByteArrays) - } - if (!isRecord(value)) { - return value - } - const { properties } = value - if (isRecord(properties) && 'BYTES_PER_ELEMENT' in properties) { - return BYTES_SCHEMA - } - return Object.fromEntries(Object.entries(value).map(([key, item]) => [ - key, - replaceByteArrays(item), - ])) -} - /** `name` and its transitive dependencies. */ function dependenciesOf(name: string, models: Record): string[] { const found = new Set() @@ -132,7 +115,7 @@ function generateModels(): Record { return sortByKey(Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [ name, { - ...rewriteRefs(tidyDescriptions(replaceByteArrays(definition)), '#/components/schemas/') as Schema, + ...rewriteRefs(tidyDescriptions(wireSchema(definition)), '#/components/schemas/') as Schema, 'x-forges-type': name, }, ]))) diff --git a/scripts/schema/generator.ts b/scripts/schema/generator.ts index bb9fc900d..3afda52b3 100644 --- a/scripts/schema/generator.ts +++ b/scripts/schema/generator.ts @@ -2,7 +2,7 @@ import type { BaseType, ChainNodeParser, Definition, SubNodeParser, SubTypeForma import type { Schema } from './json.ts' import { BaseType as Base, Context, createFormatter, createParser, DEFAULT_CONFIG, NeverType, SchemaGenerator } from 'ts-json-schema-generator' import ts from 'typescript' -import { BYTES_SCHEMA, STREAM_SCHEMA } from './json.ts' +import { STREAM_SCHEMA } from './json.ts' /** Symbols the wire maps: listings, their page, and the live provider. */ export interface ForgesTypes { @@ -13,7 +13,6 @@ export interface ForgesTypes { } const WIRE_SCHEMAS = { - bytes: BYTES_SCHEMA, opaque: { type: 'object' } as Schema, stream: STREAM_SCHEMA, } @@ -60,11 +59,9 @@ class WireTypes implements SubNodeParser, SubTypeFormatter { return this.chain.createType(this.forges.page as never, page) } const name = this.lib(node) - return name === 'Uint8Array' - ? new WireType('bytes') - : name === 'ReadableStream' - ? new WireType('stream') - : new NeverType() + return name === 'ReadableStream' + ? new WireType('stream') + : new NeverType() } supportsType(type: BaseType): boolean { @@ -94,7 +91,10 @@ class WireTypes implements SubNodeParser, SubTypeFormatter { private lib(node: ts.Node): string | undefined { return ts.isTypeReferenceNode(node) - ? ['Uint8Array', 'ReadableStream', 'AbortSignal'].find(name => isLib(this.program, node, name)) + ? [ + 'ReadableStream', + 'AbortSignal', + ].find(name => isLib(this.program, node, name)) : undefined } } diff --git a/scripts/schema/json.ts b/scripts/schema/json.ts index f5b66cd5d..7ce05a8c4 100644 --- a/scripts/schema/json.ts +++ b/scripts/schema/json.ts @@ -22,10 +22,46 @@ export const STREAM_SCHEMA: Schema = { description: 'The bytes, as `application/octet-stream`.', } +export const DATE_SCHEMA: Schema = { + type: 'object', + properties: { + $date: { type: 'string', format: 'date-time' }, + }, + required: ['$date'], + additionalProperties: false, + description: 'Date, as `{ "$date": "" }`.', +} + export function isRecord(value: Json | undefined): value is Schema { return !!value && typeof value === 'object' && !Array.isArray(value) } +/** Replaces the generator's `Date` and `Uint8Array` schemas with their wire tags. */ +export function wireSchema(value: Json): Json { + if (Array.isArray(value)) { + return value.map(wireSchema) + } + if (!isRecord(value)) { + return value + } + if (value.type === 'string' && value.format === 'date-time') { + return { + ...DATE_SCHEMA, + ...(typeof value.description === 'string' + ? { description: value.description } + : {}), + } + } + const { properties } = value + if (isRecord(properties) && 'BYTES_PER_ELEMENT' in properties) { + return BYTES_SCHEMA + } + return Object.fromEntries(Object.entries(value).map(([key, item]) => [ + key, + wireSchema(item), + ])) +} + /** Every OpenAPI component a schema references. */ export function* refs(value: Json): Generator { if (Array.isArray(value)) { diff --git a/scripts/schema/verbs.ts b/scripts/schema/verbs.ts index 08f955614..f0e74c33a 100644 --- a/scripts/schema/verbs.ts +++ b/scripts/schema/verbs.ts @@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url' import ts from 'typescript' import { CAPABILITY_TABLE } from '../../src/capability-table.ts' import { awaited, isStreamType, schemaGenerator } from './generator.ts' -import { clean, componentName, isRecord, refs, sortByKey, tidyDescriptions } from './json.ts' +import { clean, componentName, isRecord, refs, sortByKey, tidyDescriptions, wireSchema } from './json.ts' const root = fileURLToPath(new URL('../..', import.meta.url)) @@ -111,7 +111,7 @@ export function generateVerbSignatures(): { components: Record, inline(item, stack), ])) } - const cleanInline = (value: Json): Schema => clean(tidyDescriptions(inline(value))) as Schema + const cleanInline = (value: Json): Schema => clean(tidyDescriptions(wireSchema(inline(value)))) as Schema const classes = new Map & { listing: boolean }>() for (const capability of CAPABILITY_TABLE) { diff --git a/src/index.ts b/src/index.ts index ff7852694..86192971b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -46,7 +46,7 @@ export { github } from './github/index.ts' export type { GitHubAuth, GitHubGraphQL, GitHubOptions, GitHubProvider, GitHubTokenAuth, GitHubTokenKind, TypedGraphQLDocument } from './github/index.ts' export { gitlab } from './gitlab/index.ts' export type { GitLabAuth, GitLabOptions } from './gitlab/index.ts' -export { affectedKeys, commentKey, commitCommentKey, commitKey, DATE_FIELDS, isNamespaceRef, isResolvedThread, isUnsupported, namesAreCaseInsensitive, namespaceRef, normaliseRepoName, notificationKey, notificationThread, parseCommentKey, parseCommitCommentKey, parseCommitKey, parseNotificationKey, parseReleaseKey, parseRepoKey, parseThreadKey, REACTION_CONTENTS, releaseKey, repoKey, repoRef, repoSlug, reviveDates, threadKey, threadSlug } from './model.ts' +export { affectedKeys, commentKey, commitCommentKey, commitKey, isNamespaceRef, isResolvedThread, isUnsupported, namesAreCaseInsensitive, namespaceRef, normaliseRepoName, notificationKey, notificationThread, parseCommentKey, parseCommitCommentKey, parseCommitKey, parseNotificationKey, parseReleaseKey, parseRepoKey, parseThreadKey, REACTION_CONTENTS, releaseKey, repoKey, repoRef, repoSlug, threadKey, threadSlug } from './model.ts' export type { Actor, AddCollaboratorResult, diff --git a/src/model.ts b/src/model.ts index bccf78d51..fb13da107 100644 --- a/src/model.ts +++ b/src/model.ts @@ -2511,58 +2511,3 @@ export interface Installation extends ForgeOrigin { repositorySelectionRaw?: string raw: unknown } - -/** Every `Date` field in the model, by name. */ -export const DATE_FIELDS: ReadonlySet = new Set([ - 'closedAt', - 'completedAt', - 'createdAt', - 'date', - 'deliveredAt', - 'dismissedAt', - 'dueOn', - 'expiresAt', - 'lastActivityAt', - 'lastReadAt', - 'mergedAt', - 'nextPollAt', - 'occurredAt', - 'publishedAt', - 'pushedAt', - 'requestedAt', - 'resetAt', - 'startedAt', - 'submittedAt', - 'updatedAt', - 'week', -]) - -const UNNORMALISED_FIELDS: ReadonlySet = new Set(['payload', 'raw']) - -/** - * Turns the ISO strings `JSON.stringify` left in a model value back into - * `Date`s, at any depth, for every field in {@link DATE_FIELDS}, skipping - * `raw` and `payload`. Returns a copy. - */ -export function reviveDates(value: T): T { - if (Array.isArray(value)) { - return value.map(item => reviveDates(item)) as T - } - if (!value || typeof value !== 'object' || value instanceof Date) { - return value - } - return Object.fromEntries(Object.entries(value).map(([key, item]) => [ - key, - reviveField(key, item), - ])) as T -} - -function reviveField(key: string, item: unknown): unknown { - if (UNNORMALISED_FIELDS.has(key)) { - return item - } - if (DATE_FIELDS.has(key) && typeof item === 'string' && !Number.isNaN(Date.parse(item))) { - return new Date(item) - } - return reviveDates(item) -} diff --git a/src/schema/schema.json b/src/schema/schema.json index 4af255d04..b1c57d6b1 100644 --- a/src/schema/schema.json +++ b/src/schema/schema.json @@ -4196,8 +4196,17 @@ "description": "Limit to one repository." }, "before": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Only notifications updated before this time." } }, @@ -4270,12 +4279,32 @@ "type": "string" }, "startedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "completedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "run": { "$ref": "#/components/schemas/CiRunRef", @@ -4438,12 +4467,32 @@ "type": "string" }, "startedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "completedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "raw": {} }, @@ -4523,16 +4572,46 @@ "$ref": "#/components/schemas/Actor" }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "startedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "completedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "raw": {} }, @@ -4750,12 +4829,32 @@ "description": "Forge-native association the normalised `authorAssociation` was derived from." }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "url": { "type": "string" @@ -4901,12 +5000,32 @@ "description": "Forge-native association the normalised `authorAssociation` was derived from." }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "url": { "type": "string" @@ -5021,13 +5140,31 @@ "description": "Branch, tag or sha to walk back from." }, "since": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Only commits at or after this time." }, "until": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Only commits at or before this time." }, "path": { @@ -5101,13 +5238,31 @@ "description": "Commits whose committer is this login." }, "since": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Authored or committed at or after." }, "until": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Authored or committed at or before." }, "sort": { @@ -5144,8 +5299,17 @@ "type": "string" }, "date": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "When the commit was authored or committed." } }, @@ -5296,8 +5460,17 @@ "type": "object", "properties": { "week": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Start of the week." }, "additions": { @@ -6880,8 +7053,17 @@ "description": "Single line describing the event, suitable for a list row." }, "occurredAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "When the event happened, from the forge's own timestamp unless `undated` is set." }, "undated": { @@ -7090,8 +7272,18 @@ "type": "string" }, "expiresAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "permissions": { "type": "object", @@ -7216,8 +7408,17 @@ "description": "Resume after the page that returned this cursor." }, "since": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Only items updated at or after this time." } }, @@ -7364,8 +7565,18 @@ "type": "string" }, "dueOn": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "url": { "type": "string" @@ -7440,12 +7651,32 @@ "type": "string" }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "lastReadAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "url": { "type": "string" @@ -7490,8 +7721,17 @@ "description": "Resume after the page that returned this cursor." }, "since": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Only items updated at or after this time." }, "all": { @@ -7779,8 +8019,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -7831,8 +8080,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -7883,8 +8141,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -7935,8 +8202,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -7987,8 +8263,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8039,8 +8324,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8091,8 +8385,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8143,8 +8446,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8195,8 +8507,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8247,8 +8568,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8299,8 +8629,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8351,8 +8690,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8403,8 +8751,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8455,8 +8812,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8507,8 +8873,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8559,8 +8934,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8611,8 +8995,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8663,8 +9056,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8715,8 +9117,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8767,8 +9178,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8819,8 +9239,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8871,8 +9300,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8923,8 +9361,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -8975,8 +9422,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -9027,8 +9483,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -9079,8 +9544,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -9131,8 +9605,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -9183,8 +9666,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -9235,8 +9727,17 @@ "description": "True when the provider sent no request, because the forge asked to wait longer between reads of this feed. The page has no items and a `feed_throttled` warning; read it again later, or pass `force: true`." }, "nextPollAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "The earliest time the forge allows the first page to be read again, as GitHub sets with `X-Poll-Interval`. Until then, a read of the first page returns a `throttled` page unless it passes `force: true`." }, "warnings": { @@ -9394,8 +9895,17 @@ "description": "The number of requests left in the budget." }, "resetAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "When `remaining` resets." }, "resource": { @@ -9429,8 +9939,18 @@ "$ref": "#/components/schemas/Actor" }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "raw": {} }, @@ -9540,12 +10060,32 @@ "$ref": "#/components/schemas/Actor" }, "publishedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "url": { "type": "string" @@ -9780,16 +10320,45 @@ "description": "Git remotes. Tangled maps the hosting knot to its SSH host." }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "pushedAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Last push, where the listing endpoint reports it." }, "openIssueCount": { @@ -10373,8 +10942,18 @@ "type": "string" }, "submittedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "comments": { "anyOf": [ @@ -10453,8 +11032,18 @@ "description": "The resolvable conversation the comment belongs to, where the forge has one." }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "url": { "type": "string" @@ -10663,8 +11252,17 @@ "description": "True when the reviewer is a team rather than an account." }, "requestedAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "When the pending review was last requested. Absent where the forge doesn't report it; on GitHub, `threads.getMany()` reports it." } }, @@ -10734,16 +11332,46 @@ "type": "string" }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "dismissedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "raw": {} }, @@ -11118,20 +11746,59 @@ "type": "string" }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "closedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "mergedAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "When the pull request was merged, where the forge reports it." }, "mergedBy": { @@ -11139,8 +11806,17 @@ "description": "The account that merged the pull request, where the forge reports it." }, "lastActivityAt": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Latest activity the forge reports for the thread." }, "locked": { @@ -11342,13 +12018,31 @@ "description": "Milestone title, or `'none'` for threads with no milestone." }, "since": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Updated at or after." }, "createdAfter": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Created at or after." }, "sort": { @@ -11476,8 +12170,17 @@ "description": "Threads carrying every one of these labels." }, "since": { - "type": "string", - "format": "date-time", + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, "description": "Updated at or after." }, "sort": { @@ -11803,8 +12506,18 @@ "type": "string" }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "followers": { "type": "number" @@ -11863,12 +12576,32 @@ "description": "`'json'` or `'form'` where the forge offers a choice." }, "createdAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "updatedAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "secret": { "not": {}, @@ -11957,8 +12690,18 @@ "description": "`true` when the forge considered the delivery successful." }, "deliveredAt": { - "type": "string", - "format": "date-time" + "type": "object", + "properties": { + "$date": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "$date" + ], + "additionalProperties": false, + "description": "Date, as `{ \"$date\": \"\" }`." }, "duration": { "type": "number", diff --git a/src/wire.ts b/src/wire.ts new file mode 100644 index 000000000..590c0c401 --- /dev/null +++ b/src/wire.ts @@ -0,0 +1,81 @@ +import { fromBase64 } from './contents.ts' +import { toBase64 } from './crypto.ts' + +/** Fields that hold the forge's own JSON, which the codec keeps as-is. */ +const OPAQUE_FIELDS = new Set(['raw', 'payload']) + +function isRecord(value: unknown): value is Record { + return !!value && typeof value === 'object' && !Array.isArray(value) +} + +function singleKey(value: Record): string | undefined { + const keys = Object.keys(value) + return keys.length === 1 + ? keys[0] + : undefined +} + +/** `Date`s as `{ "$date": ISO }`, bytes as `{ "$bytes": base64 }`. */ +export function encode(value: unknown): unknown { + if (value instanceof Date) { + if (Number.isNaN(value.getTime())) { + throw new TypeError('Cannot encode an invalid Date') + } + return { + $date: value.toISOString(), + } + } + if (value instanceof Uint8Array) { + return { + $bytes: toBase64(value), + } + } + if (Array.isArray(value)) { + return value.map(encode) + } + if (!isRecord(value)) { + return value + } + return Object.fromEntries(Object.entries(value).map(([key, item]) => [ + key, + OPAQUE_FIELDS.has(key) + ? item + : encode(item), + ])) +} + +/** Restores the `Date` and `Uint8Array` values in encoded JSON. */ +export function decode(value: unknown): unknown { + if (Array.isArray(value)) { + return value.map(decode) + } + if (!isRecord(value)) { + return value + } + const key = singleKey(value) + if (key === '$date') { + const date = value[key] + if (typeof date !== 'string' || Number.isNaN(Date.parse(date))) { + throw new TypeError('Invalid $date') + } + return new Date(date) + } + if (key === '$bytes') { + const bytes = value[key] + if (typeof bytes !== 'string') { + throw new TypeError('Invalid $bytes') + } + try { + return fromBase64(bytes) + } + catch { + throw new TypeError('Invalid $bytes') + } + } + return Object.fromEntries(Object.entries(value).map(([key, item]) => [ + key, + OPAQUE_FIELDS.has(key) + ? item + : decode(item), + ])) +} diff --git a/test/unit/bundle-size.test.ts b/test/unit/bundle-size.test.ts index 2d38edb59..4e05729b8 100644 --- a/test/unit/bundle-size.test.ts +++ b/test/unit/bundle-size.test.ts @@ -25,6 +25,7 @@ beforeEach(() => { } mkdirSync(join(directory, 'web')) writeFileSync(join(directory, 'web', 'index.mjs'), `export const github = 'links'`) + writeFileSync(join(directory, 'wire.mjs'), 'export const decode = 1\nexport const encode = 2') }) afterEach(() => { @@ -42,7 +43,7 @@ describe('browser bundle measurements', () => { expect(result.stderr).toBe('') expect(result.status).toBe(0) const snapshot = parseBundleSnapshot(readFileSync(out, 'utf8')) - expect(snapshot.bundles).toHaveLength(7) + expect(snapshot.bundles).toHaveLength(8) expect(snapshot.bundles[0]!.minified).toBeGreaterThan(4_000) expect(snapshot.bundles.every(bundle => bundle.gzipped > 0)).toBe(true) }) @@ -81,7 +82,7 @@ describe('browser bundle measurements', () => { const out = join(directory, 'base.json') const result = measure('--report', '--out', out) expect(result.status).toBe(0) - expect(parseBundleSnapshot(readFileSync(out, 'utf8')).bundles).toHaveLength(7) + expect(parseBundleSnapshot(readFileSync(out, 'utf8')).bundles).toHaveLength(8) expect(result.stdout).toContain('forges/github') }) @@ -97,6 +98,7 @@ describe('browser bundle measurements', () => { 'forges/gitea', 'forges/bitbucket', 'forges/web', + 'forges/wire', ]) }) diff --git a/test/unit/revive.test.ts b/test/unit/revive.test.ts deleted file mode 100644 index 179b19c53..000000000 --- a/test/unit/revive.test.ts +++ /dev/null @@ -1,117 +0,0 @@ -import { describe, expect, it } from 'vitest' -import { github } from '../../src/github/index.ts' -import { DATE_FIELDS, reviveDates } from '../../src/index.ts' -import { models } from '../../src/schema/index.ts' -import { fixtureFetch } from '../../src/testing/index.ts' - -describe('serialisation helpers', () => { - it('revives model dates at any depth after a JSON round trip', () => { - const value = { - items: [ - { - createdAt: new Date('2026-01-02T03:04:05Z'), - title: '2026-01-02', - nested: { - occurredAt: new Date(0), - }, - }, - ], - } - const revived = reviveDates(JSON.parse(JSON.stringify(value))) - - expect(revived).toEqual(value) - expect(revived.items[0]!.title).toBe('2026-01-02') - }) - - it('revives delivery, commit signature and review dates', () => { - const value = { - deliveredAt: new Date(0), - author: { - date: new Date(1), - }, - submittedAt: new Date(2), - } - - expect(reviveDates(JSON.parse(JSON.stringify(value)))).toEqual(value) - }) - - it('leaves the forge\'s own JSON in `raw` and `payload` untouched', () => { - const value = { - createdAt: new Date(0), - raw: { createdAt: '2020-01-01T00:00:00Z' }, - payload: [ - { updatedAt: '2020-01-01T00:00:00Z' }, - ], - } - const revived = reviveDates(JSON.parse(JSON.stringify(value))) - - expect(revived.createdAt).toEqual(new Date(0)) - expect(revived.raw.createdAt).toBe('2020-01-01T00:00:00Z') - expect(revived.payload[0]!.updatedAt).toBe('2020-01-01T00:00:00Z') - }) - - it('does not revive a push sha named `before`', () => { - const value = { - detail: { type: 'push', before: '0000000000000000000000000000000000000000' }, - } - - expect(reviveDates(value)).toEqual(value) - }) - - it('scopes date revival to the model schemas', () => { - const found = new Set() - const conflicts = new Set() - const visit = (node: unknown): void => { - if (!node || typeof node !== 'object') { - return - } - for (const [key, value] of Object.entries(node)) { - if (key === 'properties' && value && typeof value === 'object') { - for (const [name, property] of Object.entries(value)) { - if ((property as { format?: string }).format === 'date-time') { - found.add(name) - } - else if (DATE_FIELDS.has(name) && (property as { type?: string }).type === 'string') { - conflicts.add(name) - } - } - } - visit(value) - } - } - for (const [name, model] of Object.entries(models)) { - if (!/Options$|Query$/.test(name)) { - visit(model) - } - } - - expect([...found].filter(name => !DATE_FIELDS.has(name))).toEqual([]) - expect([...conflicts]).toEqual([]) - }) - - it('reports the request budget on pages and raw responses', async () => { - const headers = { 'x-ratelimit-limit': '5000', 'x-ratelimit-remaining': '4999', 'x-ratelimit-reset': '1767225600' } - const { fetch } = fixtureFetch([ - { - request: { method: 'GET', url: 'https://api.github.com/user/repos?per_page=100' }, - response: { status: 200, headers, body: [] }, - }, - { - request: { method: 'GET', url: 'https://api.github.com/rate_limit' }, - response: { status: 200, headers, body: {} }, - }, - ]) - const provider = github({ - auth: { type: 'token', token: 't' }, - fetch, - }) - const expected = { - limit: 5000, - remaining: 4999, - resetAt: new Date(1767225600 * 1000), - } - - expect((await provider.repos.list({ perPage: 100 }).page()).rateLimit).toEqual(expected) - expect((await provider.request('GET', '/rate_limit')).rateLimit).toEqual(expected) - }) -}) diff --git a/test/unit/schema.test.ts b/test/unit/schema.test.ts index 96070a1d3..e77691736 100644 --- a/test/unit/schema.test.ts +++ b/test/unit/schema.test.ts @@ -76,6 +76,35 @@ describe('verb signatures', () => { expect(JSON.stringify(models)).not.toContain('x-forges-type":"Uint8Array"') }) + it('describes dates as $date tags', () => { + const plain = new Set() + let tags = 0 + const visit = (node: unknown): void => { + if (!node || typeof node !== 'object') { + return + } + for (const [key, value] of Object.entries(node)) { + if (key === 'properties' && value && typeof value === 'object') { + for (const [name, property] of Object.entries(value)) { + if ((property as { format?: string }).format === 'date-time') { + if (name === '$date') { + tags++ + } + else { + plain.add(name) + } + } + } + } + visit(value) + } + } + visit(models) + + expect([...plain]).toEqual([]) + expect(tags).toBeGreaterThan(0) + }) + it('represents undefined as null, not never', () => { expect(JSON.stringify(verbs)).not.toContain('"not":{}') expect(verbs['releases.latest']?.result).toMatchObject({ diff --git a/test/unit/wire.test.ts b/test/unit/wire.test.ts new file mode 100644 index 000000000..7e30fdf40 --- /dev/null +++ b/test/unit/wire.test.ts @@ -0,0 +1,54 @@ +import { Buffer } from 'node:buffer' +import { describe, expect, it } from 'vitest' +import { decode, encode } from '../../src/wire.ts' + +describe('wire', () => { + it('round-trips dates and bytes through JSON', () => { + const value = { + createdAt: new Date('2026-11-14T10:00:00.000Z'), + content: new Uint8Array([0, 1, 2, 255]), + nested: [ + { + updatedAt: new Date(0), + }, + ], + } + + expect(decode(JSON.parse(JSON.stringify(encode(value))))).toEqual(value) + }) + + it('encodes buffers as bytes', () => { + const value = { + content: Buffer.from([1, 2, 3]), + } + + expect(decode(JSON.parse(JSON.stringify(encode(value))))).toEqual({ + content: new Uint8Array([1, 2, 3]), + }) + }) + + it('leaves plain ISO strings alone', () => { + const value = { before: '0000000000000000000000000000000000000000', since: '2026-11-14' } + + expect(decode(encode(value))).toEqual(value) + }) + + it('leaves the forge\'s own JSON alone', () => { + const value = { + createdAt: new Date('2026-11-14T10:00:00.000Z'), + payload: { $date: 'not a date' }, + raw: { $bytes: 'not base64' }, + } + + expect(decode(JSON.parse(JSON.stringify(encode(value))))).toEqual(value) + }) + + it('rejects malformed tags', () => { + expect(() => decode({ $date: 'not a date' })).toThrow('Invalid $date') + expect(() => decode({ $bytes: 'not base64' })).toThrow('Invalid $bytes') + }) + + it('rejects invalid dates', () => { + expect(() => encode(new Date(Number.NaN))).toThrow('Cannot encode an invalid Date') + }) +}) diff --git a/tsdown.config.ts b/tsdown.config.ts index 921178786..92c7aa9c6 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -26,6 +26,7 @@ export default defineConfig({ 'src/testing/index.ts', 'src/fake/index.ts', 'src/web/index.ts', + 'src/wire.ts', ], dts: { generator: 'oxc' }, exports: {