@atproto/lex-schema 0.1.5 → 0.1.6

package/src/core/string-format.ts

@@ -1,411 +0,0 @@
-import { validateCidString } from '@atproto/lex-data'
-import {
-  AtIdentifierString,
-  AtUriString,
-  DatetimeString,
-  DidString,
-  HandleString,
-  NsidString,
-  RecordKeyString,
-  TidString,
-  UriString,
-  isAtIdentifierString,
-  isAtUriString,
-  isDatetimeString,
-  isDatetimeStringLenient,
-  isValidDid,
-  isValidHandle,
-  isValidLanguage,
-  isValidNsid,
-  isValidRecordKey,
-  isValidTid,
-  isValidUri,
-} from '@atproto/syntax'
-import { CheckFn } from '../util/assertion-util.js'
-
-// -----------------------------------------------------------------------------
-// Individual string format types and type guards
-// -----------------------------------------------------------------------------
-
-// Re-exporting from @atproto/syntax without modification to preserve types and
-// documentation for types and utilities that are already well-defined there.
-// @TODO rework other string formats in @atproto/syntax to follow this pattern
-// and re-export here, e.g. language tags, NSIDs, record keys, etc.
-
-export {
-  type AtIdentifierString,
-  asAtIdentifierString,
-  assertAtIdentifierString,
-  ifAtIdentifierString,
-  isAtIdentifierString,
-} from '@atproto/syntax'
-
-// AtIdentifierString utilities
-export { isDidIdentifier, isHandleIdentifier } from '@atproto/syntax'
-
-export {
-  type DatetimeString,
-  asDatetimeString,
-  assertDatetimeString,
-  ifDatetimeString,
-  isDatetimeString,
-  isDatetimeStringLenient,
-} from '@atproto/syntax'
-
-// DatetimeString utilities
-export { currentDatetimeString, toDatetimeString } from '@atproto/syntax'
-
-export {
-  type AtUriString,
-  asAtUriString,
-  assertAtUriString,
-  ifAtUriString,
-  isAtUriString,
-} from '@atproto/syntax'
-
-/**
- * Lenient version of {@link isAtUriString} that does not enforce the validity
- * of the record key (rkey) path component (if present).
- *
- * @see {@link isAtUriString}
- */
-export function isAtUriStringLenient<I>(input: I): input is I & AtUriString {
-  return isAtUriString(input, { strict: false })
-}
-
-/**
- * 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 const isCidString = ((v) => validateCidString(v)) as CheckFn<CidString>
-/**
- * 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 DID string.
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid DID string
- */
-export const isDidString: CheckFn<DidString> = isValidDid
-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 const isHandleString: CheckFn<HandleString> = isValidHandle
-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 const isLanguageString = isValidLanguage as CheckFn<LanguageString>
-/**
- * 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 const isNsidString: CheckFn<NsidString> = isValidNsid
-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 const isRecordKeyString: CheckFn<RecordKeyString> = isValidRecordKey
-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 const isTidString: CheckFn<TidString> = isValidTid
-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 const isUriString: CheckFn<UriString> = isValidUri
-export type {
-  /**
-   * A standard URI string.
-   *
-   * @example `"https://example.com/path"`
-   */
-  UriString,
-}
-
-// -----------------------------------------------------------------------------
-// String format registry
-// -----------------------------------------------------------------------------
-
-type StringFormats = {
-  'at-identifier': AtIdentifierString
-  'at-uri': AtUriString
-  cid: CidString
-  datetime: DatetimeString
-  did: DidString
-  handle: HandleString
-  language: LanguageString
-  nsid: NsidString
-  'record-key': RecordKeyString
-  tid: TidString
-  uri: UriString
-}
-
-/**
- * Union type of all valid string format names.
- */
-export type StringFormat = Extract<keyof StringFormats, string>
-
-const stringFormatVerifiers: {
-  readonly [K in StringFormat]: readonly [
-    strict: CheckFn<StringFormats[K]>,
-    lenient?: CheckFn<StringFormats[K]>,
-  ]
-} = /*#__PURE__*/ Object.freeze({
-  __proto__: null,
-
-  'at-identifier': [isAtIdentifierString],
-  'at-uri': [isAtUriString, isAtUriStringLenient],
-  cid: [isCidString],
-  datetime: [isDatetimeString, isDatetimeStringLenient],
-  did: [isDidString],
-  handle: [isHandleString],
-  language: [isLanguageString],
-  nsid: [isNsidString],
-  'record-key': [isRecordKeyString],
-  tid: [isTidString],
-  uri: [isUriString],
-})
-
-export type StringFormatValidationOptions = {
-  /**
-   * Allows to be more lenient in validation by using a "lenient" verification
-   * function, if available. The behavior of the lenient verifier depends on the
-   * specific format, but generally it may allow for a wider range of valid
-   * inputs, including values that are not compliant with the AT Protocol
-   * specification.
-   *
-   * @default true
-   */
-  strict?: boolean
-}
-
-/**
- * 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)
- * }
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export function isStringFormat<I extends string, F extends StringFormat>(
-  input: I,
-  format: F,
-  options?: StringFormatValidationOptions,
-): input is I & StringFormats[F] {
-  const formatVerifier = stringFormatVerifiers[format]
-  // Fool-proof
-  if (!formatVerifier) throw new TypeError(`Unknown string format: ${format}`)
-
-  const check: CheckFn<StringFormats[F]> =
-    options?.strict === false && formatVerifier.length > 1
-      ? formatVerifier[1]!
-      : formatVerifier[0]
-
-  return check(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__*/
-export function assertStringFormat<I extends string, F extends StringFormat>(
-  input: I,
-  format: F,
-  options?: StringFormatValidationOptions,
-): asserts input is I & StringFormats[F] {
-  if (!isStringFormat(input, format, options)) {
-    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__*/
-export function asStringFormat<I extends string, F extends StringFormat>(
-  input: I,
-  format: F,
-  options?: StringFormatValidationOptions,
-): I & StringFormats[F] {
-  assertStringFormat(input, format, options)
-  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__*/
-export function ifStringFormat<I extends string, F extends StringFormat>(
-  input: I,
-  format: F,
-  options?: StringFormatValidationOptions,
-): undefined | (I & StringFormats[F]) {
-  return isStringFormat(input, format, options) ? 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', ...
- * }
- * ```
- */
-export const STRING_FORMATS = /*#__PURE__*/ Object.freeze(
-  /*#__PURE__*/ Object.keys(stringFormatVerifiers),
-) as readonly StringFormat[]

package/src/core/types.ts

@@ -1,120 +0,0 @@
-/**
- * Same as `string` but prevents TypeScript from allowing union types to
- * be widened to `string` in IDEs.
- *
- * This is useful when you want autocompletion for known string values
- * while still allowing arbitrary strings.
- *
- * @example
- * ```typescript
- * // With plain string, union is widened:
- * type Status1 = 'active' | 'inactive' | string // just becomes "string"
- *
- * // With UnknownString, union is preserved:
- * type Status2 = 'active' | 'inactive' | UnknownString
- * // Autocomplete will suggest 'active' and 'inactive'
- * ```
- */
-export type UnknownString = string & NonNullable<unknown>
-
-/**
- * Simplifies a type by expanding intersections and mapped types.
- *
- * This improves IDE tooltips by showing the actual shape of a type
- * rather than complex intersections.
- *
- * @typeParam T - The type to simplify
- *
- * @example
- * ```typescript
- * type Complex = { a: string } & { b: number }
- * type Simple = Simplify<Complex>
- * // Hover shows: { a: string; b: number }
- * ```
- */
-export type Simplify<T> = { [K in keyof T]: T[K] } & NonNullable<unknown>
-
-/**
- * Internal symbol for branding restricted types.
- * @internal
- */
-declare const __restricted: unique symbol
-
-/**
- * A type that represents a value that cannot be used, with a custom
- * message explaining the restriction.
- *
- * This is useful for creating "never use this" types that provide
- * helpful error messages when someone tries to use them.
- *
- * @typeParam Message - A string literal type containing the error message
- *
- * @example
- * ```typescript
- * type DeprecatedField = Restricted<'This field has been deprecated. Use newField instead.'>
- *
- * interface MyType {
- *   oldField?: DeprecatedField
- *   newField: string
- * }
- *
- * const obj: MyType = {
- *   oldField: 'value', // Error: Type 'string' is not assignable to type 'Restricted<...>'
- *   newField: 'value'
- * }
- * ```
- */
-export type Restricted<Message extends string> = typeof __restricted & {
-  [__restricted]: Message
-}
-
-/**
- * Converts all properties of `P` that may be `undefined` into actual
- * optional properties on the resulting type.
- *
- * This is useful when working with types where some properties are typed as
- * `T | undefined` but should really be optional (`T?`).
- *
- * @typeParam P - The object type to transform
- *
- * @example
- * ```typescript
- * type Input = {
- *   required: string
- *   optional: string | undefined
- * }
- *
- * type Output = WithOptionalProperties<Input>
- * // Result: {
- * //   required: string
- * //   optional?: string | undefined
- * // }
- * ```
- */
-export type WithOptionalProperties<P> = Simplify<
-  {
-    -readonly [K in keyof P as undefined extends P[K] ? never : K]-?: P[K]
-  } & {
-    -readonly [K in keyof P as undefined extends P[K] ? K : never]?: P[K]
-  }
->
-
-/**
- * Creates a type by omitting a specific key from an object type.
- *
- * Similar to TypeScript's built-in `Omit`, but preserves the type structure
- * more accurately in some edge cases.
- *
- * @typeParam T - The object type to transform
- * @typeParam K - The key to omit (must be a key of T)
- *
- * @example
- * ```typescript
- * type Person = { name: string; age: number; email: string }
- * type PersonWithoutEmail = OmitKey<Person, 'email'>
- * // Result: { name: string; age: number }
- * ```
- */
-export type OmitKey<T, K extends keyof T> = {
-  [K2 in keyof T as K2 extends K ? never : K2]: T[K2]
-}

package/src/core/validation-error.ts

@@ -1,134 +0,0 @@
-import { LexError } from '@atproto/lex-data'
-import { arrayAgg } from '../util/array-agg.js'
-import { ResultFailure } from './result.js'
-import {
-  Issue,
-  IssueInvalidType,
-  IssueInvalidValue,
-} from './validation-issue.js'
-
-/**
- * Error thrown when validation fails.
- *
- * Contains detailed information about all validation issues encountered,
- * including the path to each invalid value and descriptions of what was
- * expected vs what was received.
- *
- * Extends {@link LexError} with the error name "InvalidRequest" for
- * consistency with the AT Protocol error handling conventions.
- *
- * @example
- * ```typescript
- * const error = new LexValidationError([
- *   new IssueInvalidType(['user', 'age'], 'hello', ['number'])
- * ])
- * console.log(error.message)
- * // "Expected integer value type (got "some-string") at $.user.age"
- *
- * console.log(error.issues.length) // 1
- * console.log(error.toJSON())
- * // { error: 'InvalidRequest', message: '...', issues: [...] }
- * ```
- *
- * @note this class implements {@link ResultFailure} to allow it to be used
- * directly as a failure reason in validation results, avoiding the need for
- * wrapping it in an additional object.
- */
-export class LexValidationError
-  extends LexError<'InvalidRequest'>
-  implements ResultFailure<LexValidationError>
-{
-  name = 'LexValidationError'
-
-  /**
-   * The list of validation issues that caused this error.
-   *
-   * Issues are aggregated when possible (e.g., multiple invalid type issues
-   * at the same path are combined into a single issue listing all expected types).
-   */
-  readonly issues: readonly Issue[]
-
-  /**
-   * Creates a new validation error from a list of issues.
-   *
-   * Issues are automatically aggregated to combine related issues at the same
-   * path (e.g., multiple type expectations from a union schema).
-   *
-   * @param issues - The validation issues that caused this error
-   * @param options - Standard Error options (e.g., `cause`)
-   */
-  constructor(issues: Issue[], options?: ErrorOptions) {
-    const issuesAgg = aggregateIssues(issues)
-    super('InvalidRequest', issuesAgg.join(', '), options)
-    this.issues = issuesAgg
-  }
-
-  /** @see {ResultFailure.success} */
-  readonly success = false as const
-
-  /** @see {ResultFailure.reason} */
-  get reason() {
-    return this
-  }
-
-  /**
-   * Converts the error to a JSON-serializable object.
-   *
-   * @returns An object containing the error details and issues details
-   */
-  override toJSON() {
-    return {
-      ...super.toJSON(),
-      issues: this.issues.map((issue) => issue.toJSON()),
-    }
-  }
-}
-
-function aggregateIssues(issues: Issue[]): Issue[] {
-  // Quick path for common cases
-  if (issues.length <= 1) return issues
-  if (issues.length === 2 && issues[0].code !== issues[1].code) return issues
-
-  return [
-    // Aggregate invalid_type with identical paths
-    ...arrayAgg(
-      issues.filter((issue) => issue instanceof IssueInvalidType),
-      (a, b) => comparePropertyPaths(a.path, b.path),
-      (issues) =>
-        new IssueInvalidType(
-          issues[0].path,
-          issues[0].input,
-          Array.from(new Set(issues.flatMap((iss) => iss.expected))),
-        ),
-    ),
-    // Aggregate invalid_value with identical paths
-    ...arrayAgg(
-      issues.filter((issue) => issue instanceof IssueInvalidValue),
-      (a, b) => comparePropertyPaths(a.path, b.path),
-      (issues) =>
-        new IssueInvalidValue(
-          issues[0].path,
-          issues[0].input,
-          Array.from(new Set(issues.flatMap((iss) => iss.values))),
-        ),
-    ),
-    // Pass through other issues
-    ...issues.filter(
-      (issue) =>
-        !(issue instanceof IssueInvalidType) &&
-        !(issue instanceof IssueInvalidValue),
-    ),
-  ]
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-function comparePropertyPaths(
-  a: readonly PropertyKey[],
-  b: readonly PropertyKey[],
-) {
-  if (a.length !== b.length) return false
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) return false
-  }
-  return true
-}