@atproto/lex-schema 0.0.11 → 0.0.13

package/dist/util/if-any.d.ts

@@ -0,0 +1,2 @@
+export type IfAny<T, TrueValue, FalseValue> = 0 extends 1 & T ? TrueValue : FalseValue;
+//# sourceMappingURL=if-any.d.ts.map

package/dist/util/if-any.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"if-any.d.ts","sourceRoot":"","sources":["../../src/util/if-any.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GACzD,SAAS,GACT,UAAU,CAAA"}

package/dist/util/if-any.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=if-any.js.map

package/dist/util/if-any.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"if-any.js","sourceRoot":"","sources":["../../src/util/if-any.ts"],"names":[],"mappings":"","sourcesContent":["export type IfAny<T, TrueValue, FalseValue> = 0 extends 1 & T\n  ? TrueValue\n  : FalseValue\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-schema",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "license": "MIT",
   "description": "Lexicon schema system for AT Lexicons",
   "keywords": [
@@ -31,13 +31,13 @@
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.js",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
     "@atproto/syntax": "^0.4.3",
-    "@atproto/lex-data": "^0.0.10"
+    "@atproto/lex-data": "^0.0.12"
   },
   "devDependencies": {
     "vitest": "^4.0.16"

package/src/core/$type.ts

@@ -1,6 +1,25 @@
 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,
@@ -12,8 +31,41 @@ export type $Type<
       : `${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'
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function $type<N extends NsidString, H extends string>(
   nsid: N,
@@ -22,12 +74,50 @@ export function $type<N extends NsidString, H extends string>(
   return (hash === 'main' ? nsid : `${nsid}#${hash}`) as $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 function $typed<V extends { $type?: unknown }, T extends string>(
   value: V,
   $type: T,
@@ -35,33 +125,75 @@ export function $typed<V extends { $type?: unknown }, T extends string>(
   return value.$type === $type ? (value as $Typed<V, T>) : { ...value, $type }
 }
 
+/**
+ * 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 }
 
-// In order to prevent places that expect a union of known and unknown $typed
-// objects (like lexicons schema open unions), from accepting an invalid version
-// of the known $typed objects, we need to prevent any other properties from
-// being present.
-//
-// For example, if we expect:
-// ```ts
-// type MyOpenUnion = { $type: 'A'; a: number } | Unknown$TypedObject
-// ```
-// we want to make that that the following is rejected:
-// ```ts
-// { $type: 'A' }
-// ```
-//
-// If we typed `Unknown$TypedObject` as `{ $type: string }`, `{ $type: 'A' }`
-// would be a valid `MyOpenUnion` as it would match the `Unknown$TypedObject`.
-// By using a $type property that uniquely describes unknown values, we ensure
-// that only valid known typed objects, or a type casted value, can be used.
+/**
+ * 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/src/core/record-key.ts

@@ -1,7 +1,36 @@
 import { isValidRecordKey } from '@atproto/syntax'
 
+/**
+ * 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)
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function isLexiconRecordKey<T>(key: T): key is T & LexiconRecordKey {
   return (
@@ -15,6 +44,21 @@ export 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
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function asLexiconRecordKey(key: unknown): LexiconRecordKey {
   if (isLexiconRecordKey(key)) return key

package/src/core/result.ts

@@ -1,23 +1,105 @@
 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
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function success<V>(value: V): ResultSuccess<V> {
   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__*/
 export function failure<E>(reason: E): ResultFailure<E> {
   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__*/
 export function failureReason<T>(result: ResultFailure<T>): T {
   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__*/
 export function successValue<T>(result: ResultSuccess<T>): T {
   return result.value
@@ -27,7 +109,7 @@ export 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
@@ -37,8 +119,8 @@ export 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
  * }
  * ```
  */
@@ -68,7 +150,7 @@ export 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
  * }
  */
 /*@__NO_SIDE_EFFECTS__*/