@atproto/lex-schema 0.0.11 → 0.0.13

package/dist/core/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  ValidationContext,\n  ValidationOptions,\n  ValidationResult,\n  Validator,\n} from './validator.js'\n\ntype ParseOptions = Omit<ValidationOptions, 'mode'>\ntype ValidateOptions = Omit<ValidationOptions, 'mode'>\n\nexport interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {\n  /** @internal The inferred validation type */\n  input: TInput\n\n  /** @internal The inferred parse type */\n  output: TOutput\n}\n\nexport abstract class Schema<\n  out TInput = unknown,\n  out TOutput = TInput,\n  out TInternals extends SchemaInternals<TInput, TOutput> = SchemaInternals<\n    TInput,\n    TOutput\n  >,\n> implements Validator<TInternals['input'], TInternals['output']>\n{\n  declare readonly ['__lex']: TInternals\n\n  abstract validateInContext(\n    input: unknown,\n    ctx: ValidationContext,\n  ): ValidationResult\n\n  /**\n   * @note use {@link check}() instead of {@link assert}() if you encounter a\n   * `ts(2775)` error and you are not able to fully type the validator. This\n   * will typically arise in generic contexts, where the narrowed type is not\n   * needed.\n   */\n  assert(input: unknown): asserts input is InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (!result.success) throw result.reason\n  }\n\n  /**\n   * Alias for {@link assert}(). Most useful in generic contexts where the\n   * validator is not exactly typed, allowing to avoid \"_Assertions require\n   * every name in the call target to be declared with an explicit type\n   * annotation. ts(2775)_\" errors.\n   */\n  check(input: unknown): void {\n    this.assert(input)\n  }\n\n  /**\n   * Casts the input (by validating it) to the output type if it matches the\n   * schema, otherwise throws. This is the same as calling {@link parse}() with\n   * `mode: \"validate\"`.\n   */\n  cast<I>(input: I): I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  matches<I>(input: I): input is I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    return result.success\n  }\n\n  ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.matches(input) ? input : undefined\n  }\n\n  parse(input: unknown, options?: ParseOptions): InferOutput<this> {\n    const result = this.safeParse(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  safeParse(\n    input: unknown,\n    options?: ParseOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'parse',\n    })\n  }\n\n  validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    const result = this.safeValidate(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'validate',\n    })\n  }\n\n  // @NOTE The built lexicons namespaces will export utility functions that\n  // allow accessing the schema's methods without the need to specify \".main.\"\n  // as part of the namespace. This way, a utility for a particular record type\n  // can be called like \"app.bsky.feed.post.<utility>()\" instead of\n  // \"app.bsky.feed.post.main.<utility>()\". Because those utilities could\n  // conflict with other schemas (e.g. if there is a lexicon definition at\n  // \"#<utility>\"), those exported utilities will be prefixed with \"$\". In order\n  // to be able to consistently call the utilities, when using the \"main\" and\n  // non \"main\" definitions, we also expose the same methods with a \"$\" prefix.\n  // Thanks to this, both of the following call will be possible:\n  //\n  // - \"app.bsky.feed.post.$parse(...)\" // calls a utility function created by \"lex build\"\n  // - \"app.bsky.feed.defs.postView.$parse(...)\" // uses the alias defined below on the schema instance\n\n  $assert(input: unknown): asserts input is InferInput<this> {\n    return this.assert(input)\n  }\n\n  $check(input: unknown): void {\n    return this.check(input)\n  }\n\n  $cast<I>(input: I): I & InferInput<this> {\n    return this.cast(input)\n  }\n\n  $matches(input: unknown): input is InferInput<this> {\n    return this.matches(input)\n  }\n\n  $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.ifMatches(input)\n  }\n\n  $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {\n    return this.parse(input, options)\n  }\n\n  $safeParse(\n    input: unknown,\n    options?: ValidateOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return this.safeParse(input, options)\n  }\n\n  $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    return this.validate(input, options)\n  }\n\n  $safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return this.safeValidate(input, options)\n  }\n}\n"]}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  ValidationContext,\n  ValidationOptions,\n  ValidationResult,\n  Validator,\n} from './validator.js'\n\n/**\n * Options for parsing operations.\n * Excludes the `mode` option as it is implicitly set to `\"parse\"`.\n */\nexport type ParseOptions = Omit<ValidationOptions, 'mode'>\n\n/**\n * Options for validation operations.\n * Excludes the `mode` option as it is implicitly set to `\"validate\"`.\n */\nexport type ValidateOptions = Omit<ValidationOptions, 'mode'>\n\n/**\n * Internal type structure for schema type inference.\n *\n * This interface defines the phantom types used for compile-time type inference\n * without affecting runtime behavior. The `input` and `output` properties\n * represent the expected input type during validation and the resulting output\n * type after parsing, respectively.\n *\n * @typeParam TInput - The type accepted as input during validation\n * @typeParam TOutput - The type returned after parsing (may differ from input due to coercion)\n */\nexport interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {\n  input: TInput\n  output: TOutput\n}\n\n/**\n * Abstract base class for all schema validators in the lexicon system.\n *\n * This class provides the standard validation interface that all schema types\n * implement. It offers multiple methods for validating and parsing data:\n *\n * - **Assertion methods**: `assert()`, `check()` - throw on invalid input\n * - **Type guard methods**: `matches()`, `ifMatches()` - return boolean or optional value\n * - **Parse methods**: `parse()`, `safeParse()` - allow value transformation/coercion\n * - **Validate methods**: `validate()`, `safeValidate()` - strict validation without coercion\n *\n * All methods are also available with a `$` prefix (e.g., `$parse()`, `$validate()`)\n * for consistent access in generated lexicon namespaces.\n *\n * @typeParam TInput - The type accepted as valid input during validation\n * @typeParam TOutput - The type returned after parsing (may include transformations)\n * @typeParam TInternals - Internal type structure for type inference\n *\n * @example\n * ```typescript\n * class MySchema extends Schema<string> {\n *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {\n *     if (typeof input !== 'string') {\n *       return ctx.issueUnexpectedType(input, 'string')\n *     }\n *     return ctx.success(input)\n *   }\n * }\n *\n * const schema = new MySchema()\n * schema.assert('hello')     // OK\n * schema.assert(123)         // Throws ValidationError\n * schema.matches('hello')    // true\n * schema.matches(123)        // false\n * ```\n */\nexport abstract class Schema<\n  out TInput = unknown,\n  out TOutput = TInput,\n  out TInternals extends SchemaInternals<TInput, TOutput> = SchemaInternals<\n    TInput,\n    TOutput\n  >,\n> implements Validator<TInternals['input'], TInternals['output']>\n{\n  /**\n   * Internal phantom property for type inference.\n   * This property does not exist at runtime.\n   *\n   * @internal\n   */\n  declare readonly ['__lex']: TInternals\n\n  // Needed to discriminate multiple schema types when used in unions. Without\n  // this, Typescript could allow an EnumSchema<\"foo\" | \"bar\"> to be used where\n  // a StringSchema is expected, since they would both be structurally\n  // compatible.\n  abstract readonly type: string\n\n  /**\n   * Performs validation of the input value within a validation context.\n   *\n   * This method must be implemented by subclasses to define the actual\n   * validation logic. It should not be called directly; use\n   * {@link ValidationContext.validate} instead to ensure proper mode enforcement.\n   *\n   * @param input - The value to validate\n   * @param ctx - The validation context providing path tracking and issue reporting\n   * @returns A validation result indicating success with the validated value or failure with issues\n   *\n   * @internal\n   */\n  abstract validateInContext(\n    input: unknown,\n    ctx: ValidationContext,\n  ): ValidationResult\n\n  /**\n   * @note use {@link check}() instead of {@link assert}() if you encounter a\n   * `ts(2775)` error and you are not able to fully type the validator. This\n   * will typically arise in generic contexts, where the narrowed type is not\n   * needed.\n   */\n  assert(input: unknown): asserts input is InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (!result.success) throw result.reason\n  }\n\n  /**\n   * Alias for {@link assert}(). Most useful in generic contexts where the\n   * validator is not exactly typed, allowing to avoid \"_Assertions require\n   * every name in the call target to be declared with an explicit type\n   * annotation. ts(2775)_\" errors.\n   */\n  check(input: unknown): void {\n    this.assert(input)\n  }\n\n  /**\n   * Casts the input (by validating it) to the output type if it matches the\n   * schema, otherwise throws. This is the same as calling {@link parse}() with\n   * `mode: \"validate\"`.\n   */\n  cast<I>(input: I): I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  /**\n   * Type guard that checks if the input matches this schema.\n   *\n   * @param input - The value to check\n   * @returns `true` if the input is valid according to this schema\n   *\n   * @example\n   * ```typescript\n   * if (schema.matches(data)) {\n   *   // data is narrowed to the schema's input type\n   *   console.log(data)\n   * }\n   * ```\n   */\n  matches<I>(input: I): input is I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    return result.success\n  }\n\n  /**\n   * Returns the input if it matches this schema, otherwise returns `undefined`.\n   *\n   * This is useful for optional filtering operations where you want to\n   * conditionally extract values that match a schema.\n   *\n   * @param input - The value to check\n   * @returns The input value with narrowed type if valid, otherwise `undefined`\n   *\n   * @example\n   * ```typescript\n   * const validData = schema.ifMatches(data)\n   * if (validData !== undefined) {\n   *   // validData is the schema's input type\n   *   console.log(validData)\n   * }\n   * ```\n   */\n  ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.matches(input) ? input : undefined\n  }\n\n  /**\n   * Parses the input, allowing value transformations and coercion.\n   *\n   * Unlike {@link validate}, this method allows the schema to transform\n   * the input value (e.g., applying default values, type coercion).\n   * Throws a {@link ValidationError} if the input is invalid.\n   *\n   * @param input - The value to parse\n   * @param options - Optional parsing configuration\n   * @returns The parsed and potentially transformed value\n   * @throws {ValidationError} If the input fails validation\n   *\n   * @example\n   * ```typescript\n   * const result = schema.parse(rawData)\n   * // result has defaults applied and is fully typed\n   * ```\n   */\n  parse(input: unknown, options?: ParseOptions): InferOutput<this> {\n    const result = this.safeParse(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  /**\n   * Safely parses the input without throwing, returning a result object.\n   *\n   * This method allows value transformations like {@link parse}, but\n   * returns a discriminated union result instead of throwing on error.\n   *\n   * @param input - The value to parse\n   * @param options - Optional parsing configuration\n   * @returns A {@link ValidationResult} with either the parsed value or validation errors\n   *\n   * @example\n   * ```typescript\n   * const result = schema.safeParse(data)\n   * if (result.success) {\n   *   console.log(result.value)\n   * } else {\n   *   console.error(result.reason.issues)\n   * }\n   * ```\n   */\n  safeParse(\n    input: unknown,\n    options?: ParseOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'parse',\n    })\n  }\n\n  /**\n   * Validates the input strictly without allowing transformations.\n   *\n   * Unlike {@link parse}, this method requires the input to exactly match\n   * the schema without any transformations (no defaults applied, no coercion).\n   * Throws a {@link ValidationError} if the input is invalid or would require transformation.\n   *\n   * @typeParam I - The input type (preserved in the return type)\n   * @param input - The value to validate\n   * @param options - Optional validation configuration\n   * @returns The validated input with narrowed type\n   * @throws {ValidationError} If the input fails validation or requires transformation\n   *\n   * @example\n   * ```typescript\n   * const validated = schema.validate(data)\n   * // validated is typed as the intersection of input type and schema type\n   * ```\n   */\n  validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    const result = this.safeValidate(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  /**\n   * Safely validates the input without throwing, returning a result object.\n   *\n   * This method performs strict validation like {@link validate}, but\n   * returns a discriminated union result instead of throwing on error.\n   *\n   * @typeParam I - The input type (preserved in the result value type)\n   * @param input - The value to validate\n   * @param options - Optional validation configuration\n   * @returns A {@link ValidationResult} with either the validated value or validation errors\n   *\n   * @example\n   * ```typescript\n   * const result = schema.safeValidate(data)\n   * if (result.success) {\n   *   console.log(result.value)\n   * } else {\n   *   console.error(result.reason.issues)\n   * }\n   * ```\n   */\n  safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'validate',\n    })\n  }\n\n  // @NOTE Dollar-prefixed aliases\n  //\n  // The built lexicons namespaces export utility functions that allow accessing\n  // the schema's methods without the need to specify \".main.\" as part of the\n  // namespace. This way, a utility for a particular record type can be called\n  // like \"app.bsky.feed.post.<utility>()\" instead of\n  // \"app.bsky.feed.post.main.<utility>()\". Because those utilities could\n  // conflict with other schemas (e.g. if there is a lexicon definition at\n  // \"#<utility>\"), those exported utilities will be prefixed with \"$\". In order\n  // to be able to consistently call the utilities, when using the \"main\" and\n  // non \"main\" definitions, we also expose the same methods with a \"$\" prefix.\n  // Thanks to this, both of the following call will be possible:\n  //\n  // - \"app.bsky.feed.post.$parse(...)\" // calls a utility function created by \"lex build\"\n  // - \"app.bsky.feed.defs.postView.$parse(...)\" // uses the alias defined below on the schema instance\n\n  /**\n   * Alias for {@link assert} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link assert}\n   */\n  $assert(input: unknown): asserts input is InferInput<this> {\n    return this.assert(input)\n  }\n\n  /**\n   * Alias for {@link check} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link check}\n   */\n  $check(input: unknown): void {\n    return this.check(input)\n  }\n\n  /**\n   * Alias for {@link cast} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link cast}\n   */\n  $cast<I>(input: I): I & InferInput<this> {\n    return this.cast(input)\n  }\n\n  /**\n   * Alias for {@link matches} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link matches}\n   */\n  $matches(input: unknown): input is InferInput<this> {\n    return this.matches(input)\n  }\n\n  /**\n   * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link ifMatches}\n   */\n  $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.ifMatches(input)\n  }\n\n  /**\n   * Alias for {@link parse} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link parse}\n   */\n  $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {\n    return this.parse(input, options)\n  }\n\n  /**\n   * Alias for {@link safeParse} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link safeParse}\n   */\n  $safeParse(\n    input: unknown,\n    options?: ValidateOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return this.safeParse(input, options)\n  }\n\n  /**\n   * Alias for {@link validate} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link validate}\n   */\n  $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    return this.validate(input, options)\n  }\n\n  /**\n   * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link safeValidate}\n   */\n  $safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return this.safeValidate(input, options)\n  }\n}\n"]}

package/dist/core/string-format.d.ts

@@ -1,27 +1,165 @@
 import { AtIdentifierString, AtUriString, DatetimeString, DidString, HandleString, NsidString, RecordKeyString, TidString, UriString } from '@atproto/syntax';
 import { CheckFn } from '../util/assertion-util.js';
-export type { AtIdentifierString };
+/**
+ * Type guard that checks if a value is a valid AT identifier (DID or handle).
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid AT identifier
+ */
 export declare const isAtIdentifierString: CheckFn<AtIdentifierString>;
-export type { AtUriString };
+export type { 
+/**
+ * An AT identifier string - either a DID or a handle.
+ *
+ * @example `"did:plc:1234..."` or `"alice.bsky.social"`
+ */
+AtIdentifierString, };
+/**
+ * Type guard that checks if a value is a valid AT URI.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid AT URI
+ */
 export declare const isAtUriString: CheckFn<AtUriString>;
-export type CidString = string;
+export type { 
+/**
+ * An AT URI string pointing to a resource in the AT Protocol network.
+ *
+ * @example `"at://did:plc:1234.../app.bsky.feed.post/3k2..."`
+ */
+AtUriString, };
+/**
+ * Type guard that checks if a value is a valid CID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid CID string
+ */
 export declare const isCidString: CheckFn<CidString>;
-export type { DatetimeString };
+/**
+ * A Content Identifier (CID) string.
+ *
+ * CIDs are self-describing content addresses used to identify data by its hash.
+ *
+ * @example `"bafyreig..."`
+ */
+export type CidString = string;
+/**
+ * Type guard that checks if a value is a valid datetime string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid datetime string
+ */
 export declare const isDatetimeString: CheckFn<DatetimeString>;
-export type { DidString };
+export type { 
+/**
+ * An ISO 8601 datetime string.
+ *
+ * @example `"2024-01-15T12:30:00.000Z"`
+ */
+DatetimeString, };
+/**
+ * Type guard that checks if a value is a valid DID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid DID string
+ */
 export declare const isDidString: CheckFn<DidString>;
-export type { HandleString };
+export type { 
+/**
+ * A Decentralized Identifier (DID) string.
+ *
+ * DIDs are globally unique identifiers that don't require a central authority.
+ *
+ * @example `"did:plc:1234abcd..."` or `"did:web:example.com"`
+ */
+DidString, };
+/**
+ * Type guard that checks if a value is a valid handle string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid handle string
+ */
 export declare const isHandleString: CheckFn<HandleString>;
-export type LanguageString = string;
+export type { 
+/**
+ * A handle string - a human-readable identifier for users.
+ *
+ * @example `"alice.bsky.social"` or `"bob.example.com"`
+ */
+HandleString, };
+/**
+ * Type guard that checks if a value is a valid BCP-47 language tag.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid language string
+ */
 export declare const isLanguageString: CheckFn<LanguageString>;
-export type { NsidString };
+/**
+ * A BCP-47 language tag string.
+ *
+ * @example `"en"`, `"en-US"`, `"zh-Hans"`
+ */
+export type LanguageString = string;
+/**
+ * Type guard that checks if a value is a valid NSID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid NSID string
+ */
 export declare const isNsidString: CheckFn<NsidString>;
-export type { RecordKeyString };
+export type { 
+/**
+ * A Namespaced Identifier (NSID) string identifying a lexicon.
+ *
+ * NSIDs use reverse-domain notation to identify schemas.
+ *
+ * @example `"app.bsky.feed.post"`, `"com.atproto.repo.createRecord"`
+ */
+NsidString, };
+/**
+ * Type guard that checks if a value is a valid record key string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid record key string
+ */
 export declare const isRecordKeyString: CheckFn<RecordKeyString>;
-export type { TidString };
+export type { 
+/**
+ * A record key string identifying a record within a collection.
+ *
+ * @example `"3k2..."` (TID format) or `"self"` (literal key)
+ */
+RecordKeyString, };
+/**
+ * Type guard that checks if a value is a valid TID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid TID string
+ */
 export declare const isTidString: CheckFn<TidString>;
-export type { UriString };
+export type { 
+/**
+ * A Timestamp Identifier (TID) string.
+ *
+ * TIDs are time-based identifiers used for record keys.
+ *
+ * @example `"3k2..."`
+ */
+TidString, };
+/**
+ * Type guard that checks if a value is a valid URI string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid URI string
+ */
 export declare const isUriString: CheckFn<UriString>;
+export type { 
+/**
+ * A standard URI string.
+ *
+ * @example `"https://example.com/path"`
+ */
+UriString, };
 type StringFormats = {
     'at-identifier': AtIdentifierString;
     'at-uri': AtUriString;
@@ -35,11 +173,106 @@ type StringFormats = {
     tid: TidString;
     uri: UriString;
 };
+/**
+ * Union type of all valid string format names.
+ */
 export type StringFormat = Extract<keyof StringFormats, string>;
+/**
+ * Infers the string type for a given format name.
+ *
+ * @typeParam F - The format name
+ *
+ * @example
+ * ```typescript
+ * type Did = InferStringFormat<'did'>
+ * // Result: DidString
+ * ```
+ */
 export type InferStringFormat<F extends StringFormat> = F extends StringFormat ? StringFormats[F] : never;
+/**
+ * Type guard that checks if a string matches a specific format.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to check
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns `true` if the string matches the format
+ *
+ * @example
+ * ```typescript
+ * const value: string = 'did:plc:1234...'
+ * if (isStringFormat(value, 'did')) {
+ *   // value is typed as DidString
+ *   console.log('Valid DID:', value)
+ * }
+ * ```
+ */
 export declare function isStringFormat<I extends string, F extends StringFormat>(input: I, format: F): input is I & StringFormats[F];
+/**
+ * Asserts that a string matches a specific format, throwing if invalid.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to check
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @throws {TypeError} If the string doesn't match the format
+ *
+ * @example
+ * ```typescript
+ * assertStringFormat(value, 'handle')
+ * // value is now typed as HandleString
+ * ```
+ */
 export declare function assertStringFormat<I extends string, F extends StringFormat>(input: I, format: F): asserts input is I & StringFormats[F];
+/**
+ * Validates and returns a string as the specified format type, throwing if invalid.
+ *
+ * This is useful when you need to convert a string to a format type in an expression.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to validate against
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns The input typed as the format type
+ * @throws {TypeError} If the string doesn't match the format
+ *
+ * @example
+ * ```typescript
+ * const did = asStringFormat(userInput, 'did')
+ * // did is typed as DidString
+ * ```
+ */
 export declare function asStringFormat<I extends string, F extends StringFormat>(input: I, format: F): I & StringFormats[F];
+/**
+ * Returns the string as the format type if valid, otherwise returns `undefined`.
+ *
+ * This is useful for optional validation where you want to handle invalid values
+ * without throwing.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to validate against
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns The typed string if valid, otherwise `undefined`
+ *
+ * @example
+ * ```typescript
+ * const did = ifStringFormat(maybeInvalid, 'did')
+ * if (did) {
+ *   // did is typed as DidString
+ * }
+ * ```
+ */
 export declare function ifStringFormat<I extends string, F extends StringFormat>(input: I, format: F): undefined | (I & StringFormats[F]);
+/**
+ * Array of all valid string format names.
+ *
+ * @example
+ * ```typescript
+ * for (const format of STRING_FORMATS) {
+ *   console.log(format) // 'at-identifier', 'at-uri', 'cid', ...
+ * }
+ * ```
+ */
 export declare const STRING_FORMATS: readonly StringFormat[];
 //# sourceMappingURL=string-format.d.ts.map

package/dist/core/string-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string-format.d.ts","sourceRoot":"","sources":["../../src/core/string-format.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"string-format.d.ts","sourceRoot":"","sources":["../../src/core/string-format.ts"],"names":[],"mappings":"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"}

package/dist/core/string-format.js

@@ -7,16 +7,85 @@ exports.asStringFormat = asStringFormat;
 exports.ifStringFormat = ifStringFormat;
 const lex_data_1 = require("@atproto/lex-data");
 const syntax_1 = require("@atproto/syntax");
+// -----------------------------------------------------------------------------
+// Individual string format types and type guards
+// -----------------------------------------------------------------------------
+/**
+ * Type guard that checks if a value is a valid AT identifier (DID or handle).
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid AT identifier
+ */
 exports.isAtIdentifierString = syntax_1.isValidAtIdentifier;
+/**
+ * Type guard that checks if a value is a valid AT URI.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid AT URI
+ */
 exports.isAtUriString = syntax_1.isValidAtUri;
+/**
+ * Type guard that checks if a value is a valid CID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid CID string
+ */
 exports.isCidString = ((v) => (0, lex_data_1.validateCidString)(v));
+/**
+ * Type guard that checks if a value is a valid datetime string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid datetime string
+ */
 exports.isDatetimeString = syntax_1.isValidDatetime;
+/**
+ * Type guard that checks if a value is a valid DID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid DID string
+ */
 exports.isDidString = syntax_1.isValidDid;
+/**
+ * Type guard that checks if a value is a valid handle string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid handle string
+ */
 exports.isHandleString = syntax_1.isValidHandle;
+/**
+ * Type guard that checks if a value is a valid BCP-47 language tag.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid language string
+ */
 exports.isLanguageString = syntax_1.isValidLanguage;
+/**
+ * Type guard that checks if a value is a valid NSID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid NSID string
+ */
 exports.isNsidString = syntax_1.isValidNsid;
+/**
+ * Type guard that checks if a value is a valid record key string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid record key string
+ */
 exports.isRecordKeyString = syntax_1.isValidRecordKey;
+/**
+ * Type guard that checks if a value is a valid TID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid TID string
+ */
 exports.isTidString = syntax_1.isValidTid;
+/**
+ * Type guard that checks if a value is a valid URI string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid URI string
+ */
 exports.isUriString = syntax_1.isValidUri;
 const stringFormatVerifiers = /*#__PURE__*/ Object.freeze({
     __proto__: null,
@@ -32,6 +101,24 @@ const stringFormatVerifiers = /*#__PURE__*/ Object.freeze({
     tid: exports.isTidString,
     uri: exports.isUriString,
 });
+/**
+ * Type guard that checks if a string matches a specific format.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to check
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns `true` if the string matches the format
+ *
+ * @example
+ * ```typescript
+ * const value: string = 'did:plc:1234...'
+ * if (isStringFormat(value, 'did')) {
+ *   // value is typed as DidString
+ *   console.log('Valid DID:', value)
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function isStringFormat(input, format) {
     const formatVerifier = stringFormatVerifiers[format];
@@ -40,21 +127,84 @@ function isStringFormat(input, format) {
         throw new TypeError(`Unknown string format: ${format}`);
     return formatVerifier(input);
 }
+/**
+ * Asserts that a string matches a specific format, throwing if invalid.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to check
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @throws {TypeError} If the string doesn't match the format
+ *
+ * @example
+ * ```typescript
+ * assertStringFormat(value, 'handle')
+ * // value is now typed as HandleString
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function assertStringFormat(input, format) {
     if (!isStringFormat(input, format)) {
         throw new TypeError(`Invalid string format (${format}): ${input}`);
     }
 }
+/**
+ * Validates and returns a string as the specified format type, throwing if invalid.
+ *
+ * This is useful when you need to convert a string to a format type in an expression.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to validate against
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns The input typed as the format type
+ * @throws {TypeError} If the string doesn't match the format
+ *
+ * @example
+ * ```typescript
+ * const did = asStringFormat(userInput, 'did')
+ * // did is typed as DidString
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function asStringFormat(input, format) {
     assertStringFormat(input, format);
     return input;
 }
+/**
+ * Returns the string as the format type if valid, otherwise returns `undefined`.
+ *
+ * This is useful for optional validation where you want to handle invalid values
+ * without throwing.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to validate against
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns The typed string if valid, otherwise `undefined`
+ *
+ * @example
+ * ```typescript
+ * const did = ifStringFormat(maybeInvalid, 'did')
+ * if (did) {
+ *   // did is typed as DidString
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function ifStringFormat(input, format) {
     return isStringFormat(input, format) ? input : undefined;
 }
+/**
+ * Array of all valid string format names.
+ *
+ * @example
+ * ```typescript
+ * for (const format of STRING_FORMATS) {
+ *   console.log(format) // 'at-identifier', 'at-uri', 'cid', ...
+ * }
+ * ```
+ */
 exports.STRING_FORMATS = Object.freeze(
 /*#__PURE__*/ Object.keys(stringFormatVerifiers));
 //# sourceMappingURL=string-format.js.map

package/dist/core/string-format.js.map

@@ -1 +1 @@
-{"version":3,"file":"string-format.js","sourceRoot":"","sources":["../../src/core/string-format.ts"],"names":[],"mappings":";;;AAoGA,wCASC;AAGD,gDAOC;AAGD,wCAMC;AAGD,wCAKC;AAxID,gDAAqD;AACrD,4CAoBwB;AAMX,QAAA,oBAAoB,GAAgC,4BAAW,CAAA;AAG/D,QAAA,aAAa,GAAyB,qBAAY,CAAA;AAGlD,QAAA,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,4BAAiB,EAAC,CAAC,CAAC,CAAuB,CAAA;AAGjE,QAAA,gBAAgB,GAA4B,wBAAe,CAAA;AAG3D,QAAA,WAAW,GAAuB,mBAAU,CAAA;AAG5C,QAAA,cAAc,GAA0B,sBAAa,CAAA;AAGrD,QAAA,gBAAgB,GAAG,wBAA0C,CAAA;AAG7D,QAAA,YAAY,GAAwB,oBAAW,CAAA;AAG/C,QAAA,iBAAiB,GAA6B,yBAAgB,CAAA;AAG9D,QAAA,WAAW,GAAuB,mBAAU,CAAA;AAG5C,QAAA,WAAW,GAAuB,mBAAU,CAAA;AAoBzD,MAAM,qBAAqB,GAEvB,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;IAC9B,SAAS,EAAE,IAAI;IAEf,eAAe,EAAE,4BAAoB;IACrC,QAAQ,EAAE,qBAAa;IACvB,GAAG,EAAE,mBAAW;IAChB,QAAQ,EAAE,wBAAgB;IAC1B,GAAG,EAAE,mBAAW;IAChB,MAAM,EAAE,sBAAc;IACtB,QAAQ,EAAE,wBAAgB;IAC1B,IAAI,EAAE,oBAAY;IAClB,YAAY,EAAE,yBAAiB;IAC/B,GAAG,EAAE,mBAAW;IAChB,GAAG,EAAE,mBAAW;CACjB,CAAC,CAAA;AAMF,wBAAwB;AACxB,SAAgB,cAAc,CAC5B,KAAQ,EACR,MAAS;IAET,MAAM,cAAc,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;IACpD,aAAa;IACb,IAAI,CAAC,cAAc;QAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAA;IAE5E,OAAO,cAAc,CAAC,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED,wBAAwB;AACxB,SAAgB,kBAAkB,CAChC,KAAQ,EACR,MAAS;IAET,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,0BAA0B,MAAM,MAAM,KAAK,EAAE,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED,wBAAwB;AACxB,SAAgB,cAAc,CAC5B,KAAQ,EACR,MAAS;IAET,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACjC,OAAO,KAAK,CAAA;AACd,CAAC;AAED,wBAAwB;AACxB,SAAgB,cAAc,CAC5B,KAAQ,EACR,MAAS;IAET,OAAO,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1D,CAAC;AAEY,QAAA,cAAc,GAAiB,MAAM,CAAC,MAAM;AACvD,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,CACtB,CAAA","sourcesContent":["import { validateCidString } from '@atproto/lex-data'\nimport {\n  AtIdentifierString,\n  AtUriString,\n  DatetimeString,\n  DidString,\n  HandleString,\n  NsidString,\n  RecordKeyString,\n  TidString,\n  UriString,\n  isValidAtIdentifier as isValidAtId,\n  isValidAtUri,\n  isValidDatetime,\n  isValidDid,\n  isValidHandle,\n  isValidLanguage,\n  isValidNsid,\n  isValidRecordKey,\n  isValidTid,\n  isValidUri,\n} from '@atproto/syntax'\nimport { CheckFn } from '../util/assertion-util.js'\n\n// Expose all individual string format types and type guards\n\nexport type { AtIdentifierString }\nexport const isAtIdentifierString: CheckFn<AtIdentifierString> = isValidAtId\n\nexport type { AtUriString }\nexport const isAtUriString: CheckFn<AtUriString> = isValidAtUri\n\nexport type CidString = string\nexport const isCidString = ((v) => validateCidString(v)) as CheckFn<CidString>\n\nexport type { DatetimeString }\nexport const isDatetimeString: CheckFn<DatetimeString> = isValidDatetime\n\nexport type { DidString }\nexport const isDidString: CheckFn<DidString> = isValidDid\n\nexport type { HandleString }\nexport const isHandleString: CheckFn<HandleString> = isValidHandle\n\nexport type LanguageString = string\nexport const isLanguageString = isValidLanguage as CheckFn<LanguageString>\n\nexport type { NsidString }\nexport const isNsidString: CheckFn<NsidString> = isValidNsid\n\nexport type { RecordKeyString }\nexport const isRecordKeyString: CheckFn<RecordKeyString> = isValidRecordKey\n\nexport type { TidString }\nexport const isTidString: CheckFn<TidString> = isValidTid\n\nexport type { UriString }\nexport const isUriString: CheckFn<UriString> = isValidUri\n\n// String format registry (maps format names to their types and type guards)\n\ntype StringFormats = {\n  'at-identifier': AtIdentifierString\n  'at-uri': AtUriString\n  cid: CidString\n  datetime: DatetimeString\n  did: DidString\n  handle: HandleString\n  language: LanguageString\n  nsid: NsidString\n  'record-key': RecordKeyString\n  tid: TidString\n  uri: UriString\n}\n\nexport type StringFormat = Extract<keyof StringFormats, string>\n\nconst stringFormatVerifiers: {\n  readonly [K in StringFormat]: CheckFn<StringFormats[K]>\n} = /*#__PURE__*/ Object.freeze({\n  __proto__: null,\n\n  'at-identifier': isAtIdentifierString,\n  'at-uri': isAtUriString,\n  cid: isCidString,\n  datetime: isDatetimeString,\n  did: isDidString,\n  handle: isHandleString,\n  language: isLanguageString,\n  nsid: isNsidString,\n  'record-key': isRecordKeyString,\n  tid: isTidString,\n  uri: isUriString,\n})\n\nexport type InferStringFormat<F extends StringFormat> = F extends StringFormat\n  ? StringFormats[F]\n  : never\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function isStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): input is I & StringFormats[F] {\n  const formatVerifier = stringFormatVerifiers[format]\n  // Fool-proof\n  if (!formatVerifier) throw new TypeError(`Unknown string format: ${format}`)\n\n  return formatVerifier(input)\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function assertStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): asserts input is I & StringFormats[F] {\n  if (!isStringFormat(input, format)) {\n    throw new TypeError(`Invalid string format (${format}): ${input}`)\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function asStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): I & StringFormats[F] {\n  assertStringFormat(input, format)\n  return input\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function ifStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): undefined | (I & StringFormats[F]) {\n  return isStringFormat(input, format) ? input : undefined\n}\n\nexport const STRING_FORMATS = /*#__PURE__*/ Object.freeze(\n  /*#__PURE__*/ Object.keys(stringFormatVerifiers),\n) as readonly StringFormat[]\n"]}
+{"version":3,"file":"string-format.js","sourceRoot":"","sources":["../../src/core/string-format.ts"],"names":[],"mappings":";;;AA2RA,wCASC;AAkBD,gDAOC;AAqBD,wCAMC;AAuBD,wCAKC;AApXD,gDAAqD;AACrD,4CAoBwB;AAGxB,gFAAgF;AAChF,iDAAiD;AACjD,gFAAgF;AAEhF;;;;;GAKG;AACU,QAAA,oBAAoB,GAAgC,4BAAW,CAAA;AAU5E;;;;;GAKG;AACU,QAAA,aAAa,GAAyB,qBAAY,CAAA;AAU/D;;;;;GAKG;AACU,QAAA,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,4BAAiB,EAAC,CAAC,CAAC,CAAuB,CAAA;AAU9E;;;;;GAKG;AACU,QAAA,gBAAgB,GAA4B,wBAAe,CAAA;AAUxE;;;;;GAKG;AACU,QAAA,WAAW,GAAuB,mBAAU,CAAA;AAYzD;;;;;GAKG;AACU,QAAA,cAAc,GAA0B,sBAAa,CAAA;AAUlE;;;;;GAKG;AACU,QAAA,gBAAgB,GAAG,wBAA0C,CAAA;AAQ1E;;;;;GAKG;AACU,QAAA,YAAY,GAAwB,oBAAW,CAAA;AAY5D;;;;;GAKG;AACU,QAAA,iBAAiB,GAA6B,yBAAgB,CAAA;AAU3E;;;;;GAKG;AACU,QAAA,WAAW,GAAuB,mBAAU,CAAA;AAYzD;;;;;GAKG;AACU,QAAA,WAAW,GAAuB,mBAAU,CAAA;AAiCzD,MAAM,qBAAqB,GAEvB,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;IAC9B,SAAS,EAAE,IAAI;IAEf,eAAe,EAAE,4BAAoB;IACrC,QAAQ,EAAE,qBAAa;IACvB,GAAG,EAAE,mBAAW;IAChB,QAAQ,EAAE,wBAAgB;IAC1B,GAAG,EAAE,mBAAW;IAChB,MAAM,EAAE,sBAAc;IACtB,QAAQ,EAAE,wBAAgB;IAC1B,IAAI,EAAE,oBAAY;IAClB,YAAY,EAAE,yBAAiB;IAC/B,GAAG,EAAE,mBAAW;IAChB,GAAG,EAAE,mBAAW;CACjB,CAAC,CAAA;AAiBF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAwB;AACxB,SAAgB,cAAc,CAC5B,KAAQ,EACR,MAAS;IAET,MAAM,cAAc,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;IACpD,aAAa;IACb,IAAI,CAAC,cAAc;QAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAA;IAE5E,OAAO,cAAc,CAAC,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAwB;AACxB,SAAgB,kBAAkB,CAChC,KAAQ,EACR,MAAS;IAET,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,0BAA0B,MAAM,MAAM,KAAK,EAAE,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAwB;AACxB,SAAgB,cAAc,CAC5B,KAAQ,EACR,MAAS;IAET,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACjC,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAwB;AACxB,SAAgB,cAAc,CAC5B,KAAQ,EACR,MAAS;IAET,OAAO,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,cAAc,GAAiB,MAAM,CAAC,MAAM;AACvD,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,CACtB,CAAA","sourcesContent":["import { validateCidString } from '@atproto/lex-data'\nimport {\n  AtIdentifierString,\n  AtUriString,\n  DatetimeString,\n  DidString,\n  HandleString,\n  NsidString,\n  RecordKeyString,\n  TidString,\n  UriString,\n  isValidAtIdentifier as isValidAtId,\n  isValidAtUri,\n  isValidDatetime,\n  isValidDid,\n  isValidHandle,\n  isValidLanguage,\n  isValidNsid,\n  isValidRecordKey,\n  isValidTid,\n  isValidUri,\n} from '@atproto/syntax'\nimport { CheckFn } from '../util/assertion-util.js'\n\n// -----------------------------------------------------------------------------\n// Individual string format types and type guards\n// -----------------------------------------------------------------------------\n\n/**\n * Type guard that checks if a value is a valid AT identifier (DID or handle).\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid AT identifier\n */\nexport const isAtIdentifierString: CheckFn<AtIdentifierString> = isValidAtId\nexport type {\n  /**\n   * An AT identifier string - either a DID or a handle.\n   *\n   * @example `\"did:plc:1234...\"` or `\"alice.bsky.social\"`\n   */\n  AtIdentifierString,\n}\n\n/**\n * Type guard that checks if a value is a valid AT URI.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid AT URI\n */\nexport const isAtUriString: CheckFn<AtUriString> = isValidAtUri\nexport type {\n  /**\n   * An AT URI string pointing to a resource in the AT Protocol network.\n   *\n   * @example `\"at://did:plc:1234.../app.bsky.feed.post/3k2...\"`\n   */\n  AtUriString,\n}\n\n/**\n * Type guard that checks if a value is a valid CID string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid CID string\n */\nexport const isCidString = ((v) => validateCidString(v)) as CheckFn<CidString>\n/**\n * A Content Identifier (CID) string.\n *\n * CIDs are self-describing content addresses used to identify data by its hash.\n *\n * @example `\"bafyreig...\"`\n */\nexport type CidString = string\n\n/**\n * Type guard that checks if a value is a valid datetime string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid datetime string\n */\nexport const isDatetimeString: CheckFn<DatetimeString> = isValidDatetime\nexport type {\n  /**\n   * An ISO 8601 datetime string.\n   *\n   * @example `\"2024-01-15T12:30:00.000Z\"`\n   */\n  DatetimeString,\n}\n\n/**\n * Type guard that checks if a value is a valid DID string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid DID string\n */\nexport const isDidString: CheckFn<DidString> = isValidDid\nexport type {\n  /**\n   * A Decentralized Identifier (DID) string.\n   *\n   * DIDs are globally unique identifiers that don't require a central authority.\n   *\n   * @example `\"did:plc:1234abcd...\"` or `\"did:web:example.com\"`\n   */\n  DidString,\n}\n\n/**\n * Type guard that checks if a value is a valid handle string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid handle string\n */\nexport const isHandleString: CheckFn<HandleString> = isValidHandle\nexport type {\n  /**\n   * A handle string - a human-readable identifier for users.\n   *\n   * @example `\"alice.bsky.social\"` or `\"bob.example.com\"`\n   */\n  HandleString,\n}\n\n/**\n * Type guard that checks if a value is a valid BCP-47 language tag.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid language string\n */\nexport const isLanguageString = isValidLanguage as CheckFn<LanguageString>\n/**\n * A BCP-47 language tag string.\n *\n * @example `\"en\"`, `\"en-US\"`, `\"zh-Hans\"`\n */\nexport type LanguageString = string\n\n/**\n * Type guard that checks if a value is a valid NSID string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid NSID string\n */\nexport const isNsidString: CheckFn<NsidString> = isValidNsid\nexport type {\n  /**\n   * A Namespaced Identifier (NSID) string identifying a lexicon.\n   *\n   * NSIDs use reverse-domain notation to identify schemas.\n   *\n   * @example `\"app.bsky.feed.post\"`, `\"com.atproto.repo.createRecord\"`\n   */\n  NsidString,\n}\n\n/**\n * Type guard that checks if a value is a valid record key string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid record key string\n */\nexport const isRecordKeyString: CheckFn<RecordKeyString> = isValidRecordKey\nexport type {\n  /**\n   * A record key string identifying a record within a collection.\n   *\n   * @example `\"3k2...\"` (TID format) or `\"self\"` (literal key)\n   */\n  RecordKeyString,\n}\n\n/**\n * Type guard that checks if a value is a valid TID string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid TID string\n */\nexport const isTidString: CheckFn<TidString> = isValidTid\nexport type {\n  /**\n   * A Timestamp Identifier (TID) string.\n   *\n   * TIDs are time-based identifiers used for record keys.\n   *\n   * @example `\"3k2...\"`\n   */\n  TidString,\n}\n\n/**\n * Type guard that checks if a value is a valid URI string.\n *\n * @param value - The value to check\n * @returns `true` if the value is a valid URI string\n */\nexport const isUriString: CheckFn<UriString> = isValidUri\nexport type {\n  /**\n   * A standard URI string.\n   *\n   * @example `\"https://example.com/path\"`\n   */\n  UriString,\n}\n\n// -----------------------------------------------------------------------------\n// String format registry\n// -----------------------------------------------------------------------------\n\ntype StringFormats = {\n  'at-identifier': AtIdentifierString\n  'at-uri': AtUriString\n  cid: CidString\n  datetime: DatetimeString\n  did: DidString\n  handle: HandleString\n  language: LanguageString\n  nsid: NsidString\n  'record-key': RecordKeyString\n  tid: TidString\n  uri: UriString\n}\n\n/**\n * Union type of all valid string format names.\n */\nexport type StringFormat = Extract<keyof StringFormats, string>\n\nconst stringFormatVerifiers: {\n  readonly [K in StringFormat]: CheckFn<StringFormats[K]>\n} = /*#__PURE__*/ Object.freeze({\n  __proto__: null,\n\n  'at-identifier': isAtIdentifierString,\n  'at-uri': isAtUriString,\n  cid: isCidString,\n  datetime: isDatetimeString,\n  did: isDidString,\n  handle: isHandleString,\n  language: isLanguageString,\n  nsid: isNsidString,\n  'record-key': isRecordKeyString,\n  tid: isTidString,\n  uri: isUriString,\n})\n\n/**\n * Infers the string type for a given format name.\n *\n * @typeParam F - The format name\n *\n * @example\n * ```typescript\n * type Did = InferStringFormat<'did'>\n * // Result: DidString\n * ```\n */\nexport type InferStringFormat<F extends StringFormat> = F extends StringFormat\n  ? StringFormats[F]\n  : never\n\n/**\n * Type guard that checks if a string matches a specific format.\n *\n * @typeParam I - The input string type\n * @typeParam F - The format to check\n * @param input - The string to validate\n * @param format - The format name to validate against\n * @returns `true` if the string matches the format\n *\n * @example\n * ```typescript\n * const value: string = 'did:plc:1234...'\n * if (isStringFormat(value, 'did')) {\n *   // value is typed as DidString\n *   console.log('Valid DID:', value)\n * }\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function isStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): input is I & StringFormats[F] {\n  const formatVerifier = stringFormatVerifiers[format]\n  // Fool-proof\n  if (!formatVerifier) throw new TypeError(`Unknown string format: ${format}`)\n\n  return formatVerifier(input)\n}\n\n/**\n * Asserts that a string matches a specific format, throwing if invalid.\n *\n * @typeParam I - The input string type\n * @typeParam F - The format to check\n * @param input - The string to validate\n * @param format - The format name to validate against\n * @throws {TypeError} If the string doesn't match the format\n *\n * @example\n * ```typescript\n * assertStringFormat(value, 'handle')\n * // value is now typed as HandleString\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function assertStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): asserts input is I & StringFormats[F] {\n  if (!isStringFormat(input, format)) {\n    throw new TypeError(`Invalid string format (${format}): ${input}`)\n  }\n}\n\n/**\n * Validates and returns a string as the specified format type, throwing if invalid.\n *\n * This is useful when you need to convert a string to a format type in an expression.\n *\n * @typeParam I - The input string type\n * @typeParam F - The format to validate against\n * @param input - The string to validate\n * @param format - The format name to validate against\n * @returns The input typed as the format type\n * @throws {TypeError} If the string doesn't match the format\n *\n * @example\n * ```typescript\n * const did = asStringFormat(userInput, 'did')\n * // did is typed as DidString\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function asStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): I & StringFormats[F] {\n  assertStringFormat(input, format)\n  return input\n}\n\n/**\n * Returns the string as the format type if valid, otherwise returns `undefined`.\n *\n * This is useful for optional validation where you want to handle invalid values\n * without throwing.\n *\n * @typeParam I - The input string type\n * @typeParam F - The format to validate against\n * @param input - The string to validate\n * @param format - The format name to validate against\n * @returns The typed string if valid, otherwise `undefined`\n *\n * @example\n * ```typescript\n * const did = ifStringFormat(maybeInvalid, 'did')\n * if (did) {\n *   // did is typed as DidString\n * }\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function ifStringFormat<I extends string, F extends StringFormat>(\n  input: I,\n  format: F,\n): undefined | (I & StringFormats[F]) {\n  return isStringFormat(input, format) ? input : undefined\n}\n\n/**\n * Array of all valid string format names.\n *\n * @example\n * ```typescript\n * for (const format of STRING_FORMATS) {\n *   console.log(format) // 'at-identifier', 'at-uri', 'cid', ...\n * }\n * ```\n */\nexport const STRING_FORMATS = /*#__PURE__*/ Object.freeze(\n  /*#__PURE__*/ Object.keys(stringFormatVerifiers),\n) as readonly StringFormat[]\n"]}