@atproto/lex-schema 0.0.10 → 0.0.12

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @atproto/lex-schema
 
+## 0.0.12
+
+### Patch Changes
+
+- [#4603](https://github.com/bluesky-social/atproto/pull/4603) [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Constrain XRPC `Payload` to be `LexValue` instead of `unknown` (better reflecting reality)
+
+- [#4603](https://github.com/bluesky-social/atproto/pull/4603) [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Properly infer type of generic `Payload` body
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix `exports` field in package.json
+
+- [#4603](https://github.com/bluesky-social/atproto/pull/4603) [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Properly coerce params into arrays when defined as such
+
+- [#4603](https://github.com/bluesky-social/atproto/pull/4603) [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Constrain subscription `message` schema to validate `LexValue` only
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add JSDoc
+
+- Updated dependencies [[`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015)]:
+  - @atproto/lex-data@0.0.11
+
+## 0.0.11
+
+### Patch Changes
+
+- Updated dependencies [[`369bb02`](https://github.com/bluesky-social/atproto/commit/369bb02b9f80f0e15e5242e54f09bd4e01117f3a)]:
+  - @atproto/lex-data@0.0.10
+
 ## 0.0.10
 
 ### Patch Changes

package/dist/core/$type.d.ts

@@ -1,26 +1,175 @@
 import { NsidString } from './string-format.js';
 import { OmitKey, Simplify } from './types.js';
+/**
+ * Constructs the `$type` string type for a given NSID and hash.
+ *
+ * The `$type` value identifies a schema definition within a lexicon:
+ * - For "main" definitions: just the NSID (e.g., `'app.bsky.feed.post'`)
+ * - For named definitions: NSID + hash + name (e.g., `'app.bsky.feed.defs#postView'`)
+ *
+ * @typeParam N - The NSID string type
+ * @typeParam H - The hash/definition name (use `'main'` for the main definition)
+ *
+ * @example
+ * ```typescript
+ * type MainType = $Type<'app.bsky.feed.post', 'main'>
+ * // Result: 'app.bsky.feed.post'
+ *
+ * type DefType = $Type<'app.bsky.feed.defs', 'postView'>
+ * // Result: 'app.bsky.feed.defs#postView'
+ * ```
+ */
 export type $Type<N extends NsidString = NsidString, H extends string = string> = N extends NsidString ? string extends H ? N | `${N}#${string}` : H extends 'main' ? N : `${N}#${H}` : never;
+/**
+ * Extracts the `$type` string type from an object type.
+ *
+ * @typeParam O - An object type with an optional `$type` property
+ *
+ * @example
+ * ```typescript
+ * type Post = { $type: 'app.bsky.feed.post'; text: string }
+ * type PostType = $TypeOf<Post>
+ * // Result: 'app.bsky.feed.post'
+ * ```
+ */
 export type $TypeOf<O extends {
     $type?: string;
 }> = NonNullable<O['$type']>;
+/**
+ * Constructs a `$type` string value from an NSID and definition name.
+ *
+ * For the "main" definition, returns just the NSID. For named definitions,
+ * returns the NSID followed by `#` and the definition name.
+ *
+ * @typeParam N - The NSID string type
+ * @typeParam H - The definition name type
+ * @param nsid - The NSID of the lexicon
+ * @param hash - The definition name within the lexicon (use `'main'` for the main definition)
+ * @returns The constructed `$type` string
+ *
+ * @example
+ * ```typescript
+ * $type('app.bsky.feed.post', 'main')
+ * // Returns: 'app.bsky.feed.post'
+ *
+ * $type('app.bsky.feed.defs', 'postView')
+ * // Returns: 'app.bsky.feed.defs#postView'
+ * ```
+ */
 export declare function $type<N extends NsidString, H extends string>(nsid: N, hash: H): $Type<N, H>;
+/**
+ * Represents an object with a required `$type` property.
+ *
+ * This type adds a `$type` property to an existing object type, useful for
+ * representing typed AT Protocol objects.
+ *
+ * @typeParam V - The base object type
+ * @typeParam T - The `$type` string literal type
+ *
+ * @example
+ * ```typescript
+ * type Post = $Typed<{ text: string; createdAt: string }, 'app.bsky.feed.post'>
+ * // Result: { $type: 'app.bsky.feed.post'; text: string; createdAt: string }
+ * ```
+ */
 export type $Typed<V, T extends string = string> = Simplify<V & {
     $type: T;
 }>;
+/**
+ * Ensures an object has the specified `$type` property.
+ *
+ * If the object already has the correct `$type`, returns it unchanged.
+ * Otherwise, creates a new object with the `$type` property added.
+ *
+ * @typeParam V - The object type (may already have `$type`)
+ * @typeParam T - The expected `$type` string
+ * @param value - The object to add `$type` to
+ * @param $type - The `$type` value to ensure
+ * @returns The object with the `$type` property
+ *
+ * @example
+ * ```typescript
+ * const post = $typed({ text: 'hello' }, 'app.bsky.feed.post')
+ * // Result: { $type: 'app.bsky.feed.post', text: 'hello' }
+ *
+ * // If already typed, returns same object
+ * const typed = { $type: 'app.bsky.feed.post', text: 'hello' }
+ * const same = $typed(typed, 'app.bsky.feed.post')
+ * console.log(typed === same) // true
+ * ```
+ */
 export declare function $typed<V extends {
     $type?: unknown;
 }, T extends string>(value: V, $type: T): $Typed<V, T>;
+/**
+ * Represents an object with an optional `$type` property.
+ *
+ * This is used for objects that may or may not have type information,
+ * such as input parameters that accept both typed and untyped values.
+ *
+ * @typeParam V - The base object type
+ * @typeParam T - The optional `$type` string literal type
+ */
 export type $TypedMaybe<V, T extends string = string> = Simplify<V & {
     $type?: T;
 }>;
+/**
+ * Removes the `$type` property from an object type.
+ *
+ * Useful for extracting the "content" of a typed object without the type marker.
+ *
+ * @typeParam V - An object type with an optional `$type` property
+ *
+ * @example
+ * ```typescript
+ * type Post = { $type: 'app.bsky.feed.post'; text: string }
+ * type PostContent = Un$Typed<Post>
+ * // Result: { text: string }
+ * ```
+ */
 export type Un$Typed<V extends {
     $type?: string;
 }> = OmitKey<V, '$type'>;
+/**
+ * Unique symbol for branding unknown `$type` strings.
+ * @internal
+ */
 declare const unknown$TypeSymbol: unique symbol;
+/**
+ * Represents an unknown or unrecognized `$type` string.
+ *
+ * This branded type is used in union types to distinguish between
+ * known typed objects and unknown typed objects (from open unions).
+ * The branding prevents accidentally matching known `$type` values.
+ */
 export type Unknown$Type = string & {
     [unknown$TypeSymbol]: true;
 };
+/**
+ * Represents an object with an unknown `$type` value.
+ *
+ * This type is used in open union schemas to represent typed objects that
+ * don't match any of the known types. The {@link Unknown$Type} branding ensures
+ * that invalid instances of known types don't accidentally match this type.
+ *
+ * For example, in an open union like:
+ * ```typescript
+ * type MyOpenUnion = { $type: 'A'; a: number } | Unknown$TypedObject
+ * ```
+ *
+ * A value `{ $type: 'A' }` (missing the required `a` property) will NOT match
+ * `Unknown$TypedObject` because `'A'` is not assignable to `Unknown$Type`.
+ * This ensures that malformed instances of known types are properly rejected.
+ *
+ * @example
+ * ```typescript
+ * // This represents any typed object we don't recognize
+ * const unknownTyped: Unknown$TypedObject = {
+ *   $type: 'some.unknown.type' as Unknown$Type,
+ *   // ... arbitrary properties
+ * }
+ * ```
+ */
 export type Unknown$TypedObject = {
     $type: Unknown$Type;
 };

package/dist/core/$type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"$type.d.ts","sourceRoot":"","sources":["../../src/core/$type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,MAAM,KAAK,CACf,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,MAAM,GAAG,MAAM,IACvB,CAAC,SAAS,UAAU,GACpB,MAAM,SAAS,CAAC,GACd,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,EAAE,GACpB,CAAC,SAAS,MAAM,GACd,CAAC,GACD,GAAG,CAAC,IAAI,CAAC,EAAE,GACf,KAAK,CAAA;AAET,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,IAAI,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;AAG3E,wBAAgB,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,MAAM,EAC1D,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,CAAC,GACN,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAEb;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CACzD,CAAC,GAAG;IACF,KAAK,EAAE,CAAC,CAAA;CACT,CACF,CAAA;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,CAAC,SAAS,MAAM,EACpE,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,CAAC,GACP,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAEd;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAC9D,CAAC,GAAG;IACF,KAAK,CAAC,EAAE,CAAC,CAAA;CACV,CACF,CAAA;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,IAAI,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;AAExE,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAA;AAC/C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAoBlE,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,CAAA"}
+{"version":3,"file":"$type.d.ts","sourceRoot":"","sources":["../../src/core/$type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,KAAK,CACf,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,MAAM,GAAG,MAAM,IACvB,CAAC,SAAS,UAAU,GACpB,MAAM,SAAS,CAAC,GACd,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,EAAE,GACpB,CAAC,SAAS,MAAM,GACd,CAAC,GACD,GAAG,CAAC,IAAI,CAAC,EAAE,GACf,KAAK,CAAA;AAET;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,IAAI,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wBAAgB,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,MAAM,EAC1D,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,CAAC,GACN,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAEb;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CACzD,CAAC,GAAG;IACF,KAAK,EAAE,CAAC,CAAA;CACT,CACF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,CAAC,SAAS,MAAM,EACpE,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,CAAC,GACP,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAEd;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAC9D,CAAC,GAAG;IACF,KAAK,CAAC,EAAE,CAAC,CAAA;CACV,CACF,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,IAAI,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;AAExE;;;GAGG;AACH,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,CAAA"}

package/dist/core/$type.js

@@ -2,10 +2,54 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.$type = $type;
 exports.$typed = $typed;
+/**
+ * Constructs a `$type` string value from an NSID and definition name.
+ *
+ * For the "main" definition, returns just the NSID. For named definitions,
+ * returns the NSID followed by `#` and the definition name.
+ *
+ * @typeParam N - The NSID string type
+ * @typeParam H - The definition name type
+ * @param nsid - The NSID of the lexicon
+ * @param hash - The definition name within the lexicon (use `'main'` for the main definition)
+ * @returns The constructed `$type` string
+ *
+ * @example
+ * ```typescript
+ * $type('app.bsky.feed.post', 'main')
+ * // Returns: 'app.bsky.feed.post'
+ *
+ * $type('app.bsky.feed.defs', 'postView')
+ * // Returns: 'app.bsky.feed.defs#postView'
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function $type(nsid, hash) {
     return (hash === 'main' ? nsid : `${nsid}#${hash}`);
 }
+/**
+ * Ensures an object has the specified `$type` property.
+ *
+ * If the object already has the correct `$type`, returns it unchanged.
+ * Otherwise, creates a new object with the `$type` property added.
+ *
+ * @typeParam V - The object type (may already have `$type`)
+ * @typeParam T - The expected `$type` string
+ * @param value - The object to add `$type` to
+ * @param $type - The `$type` value to ensure
+ * @returns The object with the `$type` property
+ *
+ * @example
+ * ```typescript
+ * const post = $typed({ text: 'hello' }, 'app.bsky.feed.post')
+ * // Result: { $type: 'app.bsky.feed.post', text: 'hello' }
+ *
+ * // If already typed, returns same object
+ * const typed = { $type: 'app.bsky.feed.post', text: 'hello' }
+ * const same = $typed(typed, 'app.bsky.feed.post')
+ * console.log(typed === same) // true
+ * ```
+ */
 function $typed(value, $type) {
     return value.$type === $type ? value : { ...value, $type };
 }

package/dist/core/$type.js.map

@@ -1 +1 @@
-{"version":3,"file":"$type.js","sourceRoot":"","sources":["../../src/core/$type.ts"],"names":[],"mappings":";;AAiBA,sBAKC;AAQD,wBAKC;AAnBD,wBAAwB;AACxB,SAAgB,KAAK,CACnB,IAAO,EACP,IAAO;IAEP,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAgB,CAAA;AACpE,CAAC;AAQD,SAAgB,MAAM,CACpB,KAAQ,EACR,KAAQ;IAER,OAAO,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAE,KAAsB,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAA;AAC9E,CAAC","sourcesContent":["import { NsidString } from './string-format.js'\nimport { OmitKey, Simplify } from './types.js'\n\nexport type $Type<\n  N extends NsidString = NsidString,\n  H extends string = string,\n> = N extends NsidString\n  ? string extends H\n    ? N | `${N}#${string}`\n    : H extends 'main'\n      ? N\n      : `${N}#${H}`\n  : never\n\nexport type $TypeOf<O extends { $type?: string }> = NonNullable<O['$type']>\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function $type<N extends NsidString, H extends string>(\n  nsid: N,\n  hash: H,\n): $Type<N, H> {\n  return (hash === 'main' ? nsid : `${nsid}#${hash}`) as $Type<N, H>\n}\n\nexport type $Typed<V, T extends string = string> = Simplify<\n  V & {\n    $type: T\n  }\n>\n\nexport function $typed<V extends { $type?: unknown }, T extends string>(\n  value: V,\n  $type: T,\n): $Typed<V, T> {\n  return value.$type === $type ? (value as $Typed<V, T>) : { ...value, $type }\n}\n\nexport type $TypedMaybe<V, T extends string = string> = Simplify<\n  V & {\n    $type?: T\n  }\n>\n\nexport type Un$Typed<V extends { $type?: string }> = OmitKey<V, '$type'>\n\ndeclare const unknown$TypeSymbol: unique symbol\nexport type Unknown$Type = string & { [unknown$TypeSymbol]: true }\n\n// In order to prevent places that expect a union of known and unknown $typed\n// objects (like lexicons schema open unions), from accepting an invalid version\n// of the known $typed objects, we need to prevent any other properties from\n// being present.\n//\n// For example, if we expect:\n// ```ts\n// type MyOpenUnion = { $type: 'A'; a: number } | Unknown$TypedObject\n// ```\n// we want to make that that the following is rejected:\n// ```ts\n// { $type: 'A' }\n// ```\n//\n// If we typed `Unknown$TypedObject` as `{ $type: string }`, `{ $type: 'A' }`\n// would be a valid `MyOpenUnion` as it would match the `Unknown$TypedObject`.\n// By using a $type property that uniquely describes unknown values, we ensure\n// that only valid known typed objects, or a type casted value, can be used.\nexport type Unknown$TypedObject = { $type: Unknown$Type }\n"]}
+{"version":3,"file":"$type.js","sourceRoot":"","sources":["../../src/core/$type.ts"],"names":[],"mappings":";;AAqEA,sBAKC;AA8CD,wBAKC;AA9ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAwB;AACxB,SAAgB,KAAK,CACnB,IAAO,EACP,IAAO;IAEP,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAgB,CAAA;AACpE,CAAC;AAuBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,MAAM,CACpB,KAAQ,EACR,KAAQ;IAER,OAAO,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAE,KAAsB,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAA;AAC9E,CAAC","sourcesContent":["import { NsidString } from './string-format.js'\nimport { OmitKey, Simplify } from './types.js'\n\n/**\n * Constructs the `$type` string type for a given NSID and hash.\n *\n * The `$type` value identifies a schema definition within a lexicon:\n * - For \"main\" definitions: just the NSID (e.g., `'app.bsky.feed.post'`)\n * - For named definitions: NSID + hash + name (e.g., `'app.bsky.feed.defs#postView'`)\n *\n * @typeParam N - The NSID string type\n * @typeParam H - The hash/definition name (use `'main'` for the main definition)\n *\n * @example\n * ```typescript\n * type MainType = $Type<'app.bsky.feed.post', 'main'>\n * // Result: 'app.bsky.feed.post'\n *\n * type DefType = $Type<'app.bsky.feed.defs', 'postView'>\n * // Result: 'app.bsky.feed.defs#postView'\n * ```\n */\nexport type $Type<\n  N extends NsidString = NsidString,\n  H extends string = string,\n> = N extends NsidString\n  ? string extends H\n    ? N | `${N}#${string}`\n    : H extends 'main'\n      ? N\n      : `${N}#${H}`\n  : never\n\n/**\n * Extracts the `$type` string type from an object type.\n *\n * @typeParam O - An object type with an optional `$type` property\n *\n * @example\n * ```typescript\n * type Post = { $type: 'app.bsky.feed.post'; text: string }\n * type PostType = $TypeOf<Post>\n * // Result: 'app.bsky.feed.post'\n * ```\n */\nexport type $TypeOf<O extends { $type?: string }> = NonNullable<O['$type']>\n\n/**\n * Constructs a `$type` string value from an NSID and definition name.\n *\n * For the \"main\" definition, returns just the NSID. For named definitions,\n * returns the NSID followed by `#` and the definition name.\n *\n * @typeParam N - The NSID string type\n * @typeParam H - The definition name type\n * @param nsid - The NSID of the lexicon\n * @param hash - The definition name within the lexicon (use `'main'` for the main definition)\n * @returns The constructed `$type` string\n *\n * @example\n * ```typescript\n * $type('app.bsky.feed.post', 'main')\n * // Returns: 'app.bsky.feed.post'\n *\n * $type('app.bsky.feed.defs', 'postView')\n * // Returns: 'app.bsky.feed.defs#postView'\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function $type<N extends NsidString, H extends string>(\n  nsid: N,\n  hash: H,\n): $Type<N, H> {\n  return (hash === 'main' ? nsid : `${nsid}#${hash}`) as $Type<N, H>\n}\n\n/**\n * Represents an object with a required `$type` property.\n *\n * This type adds a `$type` property to an existing object type, useful for\n * representing typed AT Protocol objects.\n *\n * @typeParam V - The base object type\n * @typeParam T - The `$type` string literal type\n *\n * @example\n * ```typescript\n * type Post = $Typed<{ text: string; createdAt: string }, 'app.bsky.feed.post'>\n * // Result: { $type: 'app.bsky.feed.post'; text: string; createdAt: string }\n * ```\n */\nexport type $Typed<V, T extends string = string> = Simplify<\n  V & {\n    $type: T\n  }\n>\n\n/**\n * Ensures an object has the specified `$type` property.\n *\n * If the object already has the correct `$type`, returns it unchanged.\n * Otherwise, creates a new object with the `$type` property added.\n *\n * @typeParam V - The object type (may already have `$type`)\n * @typeParam T - The expected `$type` string\n * @param value - The object to add `$type` to\n * @param $type - The `$type` value to ensure\n * @returns The object with the `$type` property\n *\n * @example\n * ```typescript\n * const post = $typed({ text: 'hello' }, 'app.bsky.feed.post')\n * // Result: { $type: 'app.bsky.feed.post', text: 'hello' }\n *\n * // If already typed, returns same object\n * const typed = { $type: 'app.bsky.feed.post', text: 'hello' }\n * const same = $typed(typed, 'app.bsky.feed.post')\n * console.log(typed === same) // true\n * ```\n */\nexport function $typed<V extends { $type?: unknown }, T extends string>(\n  value: V,\n  $type: T,\n): $Typed<V, T> {\n  return value.$type === $type ? (value as $Typed<V, T>) : { ...value, $type }\n}\n\n/**\n * Represents an object with an optional `$type` property.\n *\n * This is used for objects that may or may not have type information,\n * such as input parameters that accept both typed and untyped values.\n *\n * @typeParam V - The base object type\n * @typeParam T - The optional `$type` string literal type\n */\nexport type $TypedMaybe<V, T extends string = string> = Simplify<\n  V & {\n    $type?: T\n  }\n>\n\n/**\n * Removes the `$type` property from an object type.\n *\n * Useful for extracting the \"content\" of a typed object without the type marker.\n *\n * @typeParam V - An object type with an optional `$type` property\n *\n * @example\n * ```typescript\n * type Post = { $type: 'app.bsky.feed.post'; text: string }\n * type PostContent = Un$Typed<Post>\n * // Result: { text: string }\n * ```\n */\nexport type Un$Typed<V extends { $type?: string }> = OmitKey<V, '$type'>\n\n/**\n * Unique symbol for branding unknown `$type` strings.\n * @internal\n */\ndeclare const unknown$TypeSymbol: unique symbol\n\n/**\n * Represents an unknown or unrecognized `$type` string.\n *\n * This branded type is used in union types to distinguish between\n * known typed objects and unknown typed objects (from open unions).\n * The branding prevents accidentally matching known `$type` values.\n */\nexport type Unknown$Type = string & { [unknown$TypeSymbol]: true }\n\n/**\n * Represents an object with an unknown `$type` value.\n *\n * This type is used in open union schemas to represent typed objects that\n * don't match any of the known types. The {@link Unknown$Type} branding ensures\n * that invalid instances of known types don't accidentally match this type.\n *\n * For example, in an open union like:\n * ```typescript\n * type MyOpenUnion = { $type: 'A'; a: number } | Unknown$TypedObject\n * ```\n *\n * A value `{ $type: 'A' }` (missing the required `a` property) will NOT match\n * `Unknown$TypedObject` because `'A'` is not assignable to `Unknown$Type`.\n * This ensures that malformed instances of known types are properly rejected.\n *\n * @example\n * ```typescript\n * // This represents any typed object we don't recognize\n * const unknownTyped: Unknown$TypedObject = {\n *   $type: 'some.unknown.type' as Unknown$Type,\n *   // ... arbitrary properties\n * }\n * ```\n */\nexport type Unknown$TypedObject = { $type: Unknown$Type }\n"]}

package/dist/core/record-key.d.ts

@@ -1,4 +1,48 @@
+/**
+ * The valid record key constraint types in a lexicon definition.
+ *
+ * - `'any'` - Accepts any valid record key
+ * - `'nsid'` - Record key must be a valid NSID
+ * - `'tid'` - Record key must be a valid TID
+ * - `'literal:...'` - Record key must be the exact specified value
+ *
+ * @example
+ * ```typescript
+ * const constraint: LexiconRecordKey = 'tid'
+ * const literalConstraint: LexiconRecordKey = 'literal:self'
+ * ```
+ */
 export type LexiconRecordKey = 'any' | 'nsid' | 'tid' | `literal:${string}`;
+/**
+ * Type guard that checks if a value is a valid lexicon record key constraint.
+ *
+ * @typeParam T - The input type
+ * @param key - The value to check
+ * @returns `true` if the value is a valid record key constraint
+ *
+ * @example
+ * ```typescript
+ * if (isLexiconRecordKey(value)) {
+ *   // value is typed as LexiconRecordKey
+ *   console.log('Valid constraint:', value)
+ * }
+ * ```
+ */
 export declare function isLexiconRecordKey<T>(key: T): key is T & LexiconRecordKey;
+/**
+ * Validates and returns a value as a lexicon record key constraint, throwing if invalid.
+ *
+ * @param key - The value to validate
+ * @returns The value typed as {@link LexiconRecordKey}
+ * @throws {Error} If the value is not a valid record key constraint
+ *
+ * @example
+ * ```typescript
+ * const constraint = asLexiconRecordKey('tid')
+ * // constraint is typed as LexiconRecordKey
+ *
+ * asLexiconRecordKey('invalid') // throws Error
+ * ```
+ */
 export declare function asLexiconRecordKey(key: unknown): LexiconRecordKey;
 //# sourceMappingURL=record-key.d.ts.map

package/dist/core/record-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-key.d.ts","sourceRoot":"","sources":["../../src/core/record-key.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,MAAM,EAAE,CAAA;AAG3E,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,gBAAgB,CAUzE;AAGD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAGjE"}
+{"version":3,"file":"record-key.d.ts","sourceRoot":"","sources":["../../src/core/record-key.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,MAAM,EAAE,CAAA;AAE3E;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,gBAAgB,CAUzE;AAED;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAGjE"}

package/dist/core/record-key.js

@@ -3,6 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isLexiconRecordKey = isLexiconRecordKey;
 exports.asLexiconRecordKey = asLexiconRecordKey;
 const syntax_1 = require("@atproto/syntax");
+/**
+ * Type guard that checks if a value is a valid lexicon record key constraint.
+ *
+ * @typeParam T - The input type
+ * @param key - The value to check
+ * @returns `true` if the value is a valid record key constraint
+ *
+ * @example
+ * ```typescript
+ * if (isLexiconRecordKey(value)) {
+ *   // value is typed as LexiconRecordKey
+ *   console.log('Valid constraint:', value)
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function isLexiconRecordKey(key) {
     return (key === 'any' ||
@@ -13,6 +28,21 @@ function isLexiconRecordKey(key) {
             key.length > 8 &&
             (0, syntax_1.isValidRecordKey)(key.slice(8))));
 }
+/**
+ * Validates and returns a value as a lexicon record key constraint, throwing if invalid.
+ *
+ * @param key - The value to validate
+ * @returns The value typed as {@link LexiconRecordKey}
+ * @throws {Error} If the value is not a valid record key constraint
+ *
+ * @example
+ * ```typescript
+ * const constraint = asLexiconRecordKey('tid')
+ * // constraint is typed as LexiconRecordKey
+ *
+ * asLexiconRecordKey('invalid') // throws Error
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function asLexiconRecordKey(key) {
     if (isLexiconRecordKey(key))

package/dist/core/record-key.js.map

@@ -1 +1 @@
-{"version":3,"file":"record-key.js","sourceRoot":"","sources":["../../src/core/record-key.ts"],"names":[],"mappings":";;AAKA,gDAUC;AAGD,gDAGC;AArBD,4CAAkD;AAIlD,wBAAwB;AACxB,SAAgB,kBAAkB,CAAI,GAAM;IAC1C,OAAO,CACL,GAAG,KAAK,KAAK;QACb,GAAG,KAAK,MAAM;QACd,GAAG,KAAK,KAAK;QACb,CAAC,OAAO,GAAG,KAAK,QAAQ;YACtB,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAC1B,GAAG,CAAC,MAAM,GAAG,CAAC;YACd,IAAA,yBAAgB,EAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAClC,CAAA;AACH,CAAC;AAED,wBAAwB;AACxB,SAAgB,kBAAkB,CAAC,GAAY;IAC7C,IAAI,kBAAkB,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IACvC,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AACvD,CAAC","sourcesContent":["import { isValidRecordKey } from '@atproto/syntax'\n\nexport type LexiconRecordKey = 'any' | 'nsid' | 'tid' | `literal:${string}`\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function isLexiconRecordKey<T>(key: T): key is T & LexiconRecordKey {\n  return (\n    key === 'any' ||\n    key === 'nsid' ||\n    key === 'tid' ||\n    (typeof key === 'string' &&\n      key.startsWith('literal:') &&\n      key.length > 8 &&\n      isValidRecordKey(key.slice(8)))\n  )\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function asLexiconRecordKey(key: unknown): LexiconRecordKey {\n  if (isLexiconRecordKey(key)) return key\n  throw new Error(`Invalid record key: ${String(key)}`)\n}\n"]}
+{"version":3,"file":"record-key.js","sourceRoot":"","sources":["../../src/core/record-key.ts"],"names":[],"mappings":";;AAkCA,gDAUC;AAkBD,gDAGC;AAjED,4CAAkD;AAkBlD;;;;;;;;;;;;;;GAcG;AACH,wBAAwB;AACxB,SAAgB,kBAAkB,CAAI,GAAM;IAC1C,OAAO,CACL,GAAG,KAAK,KAAK;QACb,GAAG,KAAK,MAAM;QACd,GAAG,KAAK,KAAK;QACb,CAAC,OAAO,GAAG,KAAK,QAAQ;YACtB,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAC1B,GAAG,CAAC,MAAM,GAAG,CAAC;YACd,IAAA,yBAAgB,EAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAClC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAwB;AACxB,SAAgB,kBAAkB,CAAC,GAAY;IAC7C,IAAI,kBAAkB,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IACvC,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AACvD,CAAC","sourcesContent":["import { isValidRecordKey } from '@atproto/syntax'\n\n/**\n * The valid record key constraint types in a lexicon definition.\n *\n * - `'any'` - Accepts any valid record key\n * - `'nsid'` - Record key must be a valid NSID\n * - `'tid'` - Record key must be a valid TID\n * - `'literal:...'` - Record key must be the exact specified value\n *\n * @example\n * ```typescript\n * const constraint: LexiconRecordKey = 'tid'\n * const literalConstraint: LexiconRecordKey = 'literal:self'\n * ```\n */\nexport type LexiconRecordKey = 'any' | 'nsid' | 'tid' | `literal:${string}`\n\n/**\n * Type guard that checks if a value is a valid lexicon record key constraint.\n *\n * @typeParam T - The input type\n * @param key - The value to check\n * @returns `true` if the value is a valid record key constraint\n *\n * @example\n * ```typescript\n * if (isLexiconRecordKey(value)) {\n *   // value is typed as LexiconRecordKey\n *   console.log('Valid constraint:', value)\n * }\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function isLexiconRecordKey<T>(key: T): key is T & LexiconRecordKey {\n  return (\n    key === 'any' ||\n    key === 'nsid' ||\n    key === 'tid' ||\n    (typeof key === 'string' &&\n      key.startsWith('literal:') &&\n      key.length > 8 &&\n      isValidRecordKey(key.slice(8)))\n  )\n}\n\n/**\n * Validates and returns a value as a lexicon record key constraint, throwing if invalid.\n *\n * @param key - The value to validate\n * @returns The value typed as {@link LexiconRecordKey}\n * @throws {Error} If the value is not a valid record key constraint\n *\n * @example\n * ```typescript\n * const constraint = asLexiconRecordKey('tid')\n * // constraint is typed as LexiconRecordKey\n *\n * asLexiconRecordKey('invalid') // throws Error\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function asLexiconRecordKey(key: unknown): LexiconRecordKey {\n  if (isLexiconRecordKey(key)) return key\n  throw new Error(`Invalid record key: ${String(key)}`)\n}\n"]}

package/dist/core/result.d.ts

@@ -2,20 +2,101 @@ export type ResultSuccess<V = any> = {
     success: true;
     value: V;
 };
+/**
+ * Represents a failed result containing an error reason.
+ *
+ * @typeParam E - The type of the error reason
+ */
 export type ResultFailure<E = Error> = {
     success: false;
     reason: E;
 };
+/**
+ * A discriminated union type representing either a success or failure outcome.
+ *
+ * Check the `success` property to determine the outcome and access the
+ * appropriate property (`value` for success, `reason` for failure).
+ *
+ * @typeParam V - The type of the success value
+ * @typeParam E - The type of the error reason
+ *
+ * @example
+ * ```typescript
+ * function parseJson(text: string): Result<unknown, SyntaxError> {
+ *   try {
+ *     return success(JSON.parse(text))
+ *   } catch (e) {
+ *     return failure(e as SyntaxError)
+ *   }
+ * }
+ * ```
+ */
 export type Result<V = any, E = Error> = ResultSuccess<V> | ResultFailure<E>;
+/**
+ * Creates a successful result wrapping the given value.
+ *
+ * @typeParam V - The type of the value
+ * @param value - The success value to wrap
+ * @returns {ResultSuccess} A success result containing the value
+ *
+ * @example
+ * ```typescript
+ * const result = success(42)
+ * console.log(result.success) // true
+ * console.log(result.value)   // 42
+ * ```
+ */
 export declare function success<V>(value: V): ResultSuccess<V>;
+/**
+ * Creates a failed result wrapping the given error reason.
+ *
+ * @typeParam E - The type of the error reason
+ * @param reason - The error reason to wrap
+ * @returns {ResultFailure} A failure result containing the error
+ *
+ * @example
+ * ```typescript
+ * const result = failure(new Error('Something went wrong'))
+ * console.log(result.success) // false
+ * console.log(result.reason.message) // "Something went wrong"
+ * ```
+ */
 export declare function failure<E>(reason: E): ResultFailure<E>;
+/**
+ * Extracts the error reason from a failure result.
+ *
+ * @typeParam T - The type of the error reason
+ * @param result - A failure result
+ * @returns {T} The error reason
+ *
+ * @example
+ * ```typescript
+ * const result = failure(new Error('oops'))
+ * const error = failureReason(result)
+ * console.log(error.message) // "oops"
+ * ```
+ */
 export declare function failureReason<T>(result: ResultFailure<T>): T;
+/**
+ * Extracts the value from a success result.
+ *
+ * @typeParam T - The type of the success value
+ * @param result - A success result
+ * @returns {T} The success value
+ *
+ * @example
+ * ```typescript
+ * const result = success(42)
+ * const value = successValue(result)
+ * console.log(value) // 42
+ * ```
+ */
 export declare function successValue<T>(result: ResultSuccess<T>): T;
 /**
  * Catches any error and wraps it in a {@link ResultFailure<Error>}.
  *
  * @param err - The error to catch.
- * @returns A {@link ResultFailure<Error>} containing the caught error.
+ * @returns {ResultFailure} A failure result containing the error.
  * @example
  *
  * ```ts
@@ -25,8 +106,8 @@ export declare function successValue<T>(result: ResultSuccess<T>): T;
  * if (result.success) {
  *   console.log(result.value) // string
  * } else {
- *   console.error(result.error instanceof Error) // true
- *   console.error(result.error.message) // string
+ *   console.error(result.reason instanceof Error) // true
+ *   console.error(result.reason.message) // string
  * }
  * ```
  */
@@ -51,7 +132,7 @@ export declare function catchall(err: unknown): ResultFailure<Error>;
  * if (result.success) {
  *   console.log(result.value) // string
  * } else {
- *   console.error(result.error) // FooError | BarError
+ *   console.error(result.reason) // FooError | BarError
  * }
  */
 export declare function createCatcher<T>(Ctor: new (...args: any[]) => T): (err: unknown) => ResultFailure<T>;

package/dist/core/result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,GAAG,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAA;AAChE,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,KAAK,IAAI;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAA;AAEpE,MAAM,MAAM,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;AAG5E,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAErD;AAGD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEtD;AAGD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAE5D;AAGD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAE3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAG3D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,IACtD,KAAK,OAAO,KAAG,aAAa,CAAC,CAAC,CAAC,CAIxC"}
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,GAAG,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAA;AAEhE;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,KAAK,IAAI;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;AAE5E;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAErD;AAED;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEtD;AAED;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAE5D;AAED;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAE3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAG3D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,IACtD,KAAK,OAAO,KAAG,aAAa,CAAC,CAAC,CAAC,CAIxC"}

package/dist/core/result.js

@@ -6,18 +6,74 @@ exports.failureReason = failureReason;
 exports.successValue = successValue;
 exports.catchall = catchall;
 exports.createCatcher = createCatcher;
+/**
+ * Creates a successful result wrapping the given value.
+ *
+ * @typeParam V - The type of the value
+ * @param value - The success value to wrap
+ * @returns {ResultSuccess} A success result containing the value
+ *
+ * @example
+ * ```typescript
+ * const result = success(42)
+ * console.log(result.success) // true
+ * console.log(result.value)   // 42
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function success(value) {
     return { success: true, value };
 }
+/**
+ * Creates a failed result wrapping the given error reason.
+ *
+ * @typeParam E - The type of the error reason
+ * @param reason - The error reason to wrap
+ * @returns {ResultFailure} A failure result containing the error
+ *
+ * @example
+ * ```typescript
+ * const result = failure(new Error('Something went wrong'))
+ * console.log(result.success) // false
+ * console.log(result.reason.message) // "Something went wrong"
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function failure(reason) {
     return { success: false, reason };
 }
+/**
+ * Extracts the error reason from a failure result.
+ *
+ * @typeParam T - The type of the error reason
+ * @param result - A failure result
+ * @returns {T} The error reason
+ *
+ * @example
+ * ```typescript
+ * const result = failure(new Error('oops'))
+ * const error = failureReason(result)
+ * console.log(error.message) // "oops"
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function failureReason(result) {
     return result.reason;
 }
+/**
+ * Extracts the value from a success result.
+ *
+ * @typeParam T - The type of the success value
+ * @param result - A success result
+ * @returns {T} The success value
+ *
+ * @example
+ * ```typescript
+ * const result = success(42)
+ * const value = successValue(result)
+ * console.log(value) // 42
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function successValue(result) {
     return result.value;
@@ -26,7 +82,7 @@ function successValue(result) {
  * Catches any error and wraps it in a {@link ResultFailure<Error>}.
  *
  * @param err - The error to catch.
- * @returns A {@link ResultFailure<Error>} containing the caught error.
+ * @returns {ResultFailure} A failure result containing the error.
  * @example
  *
  * ```ts
@@ -36,8 +92,8 @@ function successValue(result) {
  * if (result.success) {
  *   console.log(result.value) // string
  * } else {
- *   console.error(result.error instanceof Error) // true
- *   console.error(result.error.message) // string
+ *   console.error(result.reason instanceof Error) // true
+ *   console.error(result.reason.message) // string
  * }
  * ```
  */
@@ -67,7 +123,7 @@ function catchall(err) {
  * if (result.success) {
  *   console.log(result.value) // string
  * } else {
- *   console.error(result.error) // FooError | BarError
+ *   console.error(result.reason) // FooError | BarError
  * }
  */
 /*@__NO_SIDE_EFFECTS__*/