@atproto/lex-schema 0.0.10 → 0.0.12

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"]}

package/dist/core/types.d.ts

@@ -1,28 +1,115 @@
 /**
- * Same as {@link string} but prevents TypeScript allowing union types to
+ * 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 are optional (i.e. may be `undefined`)
- * into actual optional properties on the resulting type.
+ * 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/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzE,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAA;AACzC;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,YAAY,GAAG;IACrE,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,QAAQ,CAC9C;IACE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACvE,GAAG;IACF,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACtE,CACF,CAAA;AAED,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KACzC,EAAE,IAAI,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;CACpD,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzE;;;GAGG;AACH,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,YAAY,GAAG;IACrE,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,QAAQ,CAC9C;IACE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACvE,GAAG;IACF,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACtE,CACF,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KACzC,EAAE,IAAI,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;CACpD,CAAA"}

package/dist/core/types.js.map

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