@atproto/lex-schema 0.0.10 → 0.0.12

package/dist/schema/procedure.js

@@ -2,6 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Procedure = void 0;
 exports.procedure = procedure;
+/**
+ * Represents a Lexicon procedure (HTTP POST) endpoint definition.
+ *
+ * Procedures are operations that may modify state on the server.
+ * They have parameters, an input payload (request body), an output
+ * payload (response body), and optional error types.
+ *
+ * @template TNsid - The NSID identifying this procedure
+ * @template TParameters - The parameters schema type
+ * @template TInputPayload - The request body payload type
+ * @template TOutputPayload - The response body payload type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const createPost = new Procedure(
+ *   'app.bsky.feed.post',
+ *   l.params({}),
+ *   l.jsonPayload({ text: l.string() }),
+ *   l.jsonPayload({ uri: l.string(), cid: l.string() }),
+ *   ['InvalidRecord']
+ * )
+ * ```
+ */
 class Procedure {
     nsid;
     parameters;
@@ -18,6 +42,46 @@ class Procedure {
     }
 }
 exports.Procedure = Procedure;
+/**
+ * Creates a procedure definition for a Lexicon POST endpoint.
+ *
+ * Procedures can modify server state. They accept both URL parameters
+ * and a request body (input payload).
+ *
+ * @param nsid - The NSID identifying this procedure endpoint
+ * @param parameters - Schema for URL query parameters
+ * @param input - Schema for request body payload
+ * @param output - Schema for response body payload
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Procedure} instance
+ *
+ * @example
+ * ```ts
+ * // Create record procedure
+ * const createRecord = l.procedure(
+ *   'com.atproto.repo.createRecord',
+ *   l.params({}),
+ *   l.jsonPayload({
+ *     repo: l.string({ format: 'at-identifier' }),
+ *     collection: l.string({ format: 'nsid' }),
+ *     record: l.unknown(),
+ *   }),
+ *   l.jsonPayload({
+ *     uri: l.string({ format: 'at-uri' }),
+ *     cid: l.string({ format: 'cid' }),
+ *   }),
+ *   ['InvalidRecord', 'RepoNotFound'],
+ * )
+ *
+ * // Procedure with binary input
+ * const uploadBlob = l.procedure(
+ *   'com.atproto.repo.uploadBlob',
+ *   l.params({}),
+ *   l.payload('*\/*', undefined), // Accept any content type
+ *   l.jsonPayload({ blob: l.blob() }),
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function procedure(nsid, parameters, input, output, errors = undefined) {
     return new Procedure(nsid, parameters, input, output, errors);

package/dist/schema/procedure.js.map

@@ -1 +1 @@
-{"version":3,"file":"procedure.js","sourceRoot":"","sources":["../../src/schema/procedure.ts"],"names":[],"mappings":";;;AAyBA,8BAQC;AA7BD,MAAa,SAAS;IAYT;IACA;IACA;IACA;IACA;IAPF,IAAI,GAAG,WAAoB,CAAA;IAEpC,YACW,IAAW,EACX,UAAuB,EACvB,KAAoB,EACpB,MAAsB,EACtB,MAAe;QAJf,SAAI,GAAJ,IAAI,CAAO;QACX,eAAU,GAAV,UAAU,CAAa;QACvB,UAAK,GAAL,KAAK,CAAe;QACpB,WAAM,GAAN,MAAM,CAAgB;QACtB,WAAM,GAAN,MAAM,CAAS;IACvB,CAAC;CACL;AAlBD,8BAkBC;AAED,wBAAwB;AACxB,SAAgB,SAAS,CAMvB,IAAO,EAAE,UAAa,EAAE,KAAQ,EAAE,MAAS,EAAE,SAAY,SAAc;IACvE,OAAO,IAAI,SAAS,CAAgB,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAC9E,CAAC","sourcesContent":["import { NsidString } from '../core.js'\nimport { ParamsSchema } from './params.js'\nimport { Payload } from './payload.js'\n\nexport class Procedure<\n  const TNsid extends NsidString = NsidString,\n  const TParameters extends ParamsSchema = ParamsSchema,\n  const TInputPayload extends Payload = Payload,\n  const TOutputPayload extends Payload = Payload,\n  const TErrors extends undefined | readonly string[] =\n    | undefined\n    | readonly string[],\n> {\n  readonly type = 'procedure' as const\n\n  constructor(\n    readonly nsid: TNsid,\n    readonly parameters: TParameters,\n    readonly input: TInputPayload,\n    readonly output: TOutputPayload,\n    readonly errors: TErrors,\n  ) {}\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function procedure<\n  const N extends NsidString,\n  const P extends ParamsSchema,\n  const I extends Payload,\n  const O extends Payload,\n  const E extends undefined | readonly string[] = undefined,\n>(nsid: N, parameters: P, input: I, output: O, errors: E = undefined as E) {\n  return new Procedure<N, P, I, O, E>(nsid, parameters, input, output, errors)\n}\n"]}
+{"version":3,"file":"procedure.js","sourceRoot":"","sources":["../../src/schema/procedure.ts"],"names":[],"mappings":";;;AAyFA,8BAQC;AA7FD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,SAAS;IAYT;IACA;IACA;IACA;IACA;IAPF,IAAI,GAAG,WAAoB,CAAA;IAEpC,YACW,IAAW,EACX,UAAuB,EACvB,KAAoB,EACpB,MAAsB,EACtB,MAAe;QAJf,SAAI,GAAJ,IAAI,CAAO;QACX,eAAU,GAAV,UAAU,CAAa;QACvB,UAAK,GAAL,KAAK,CAAe;QACpB,WAAM,GAAN,MAAM,CAAgB;QACtB,WAAM,GAAN,MAAM,CAAS;IACvB,CAAC;CACL;AAlBD,8BAkBC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAwB;AACxB,SAAgB,SAAS,CAMvB,IAAO,EAAE,UAAa,EAAE,KAAQ,EAAE,MAAS,EAAE,SAAY,SAAc;IACvE,OAAO,IAAI,SAAS,CAAgB,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAC9E,CAAC","sourcesContent":["import { NsidString } from '../core.js'\nimport { ParamsSchema } from './params.js'\nimport { Payload } from './payload.js'\n\n/**\n * Represents a Lexicon procedure (HTTP POST) endpoint definition.\n *\n * Procedures are operations that may modify state on the server.\n * They have parameters, an input payload (request body), an output\n * payload (response body), and optional error types.\n *\n * @template TNsid - The NSID identifying this procedure\n * @template TParameters - The parameters schema type\n * @template TInputPayload - The request body payload type\n * @template TOutputPayload - The response body payload type\n * @template TErrors - Array of error type strings, or undefined\n *\n * @example\n * ```ts\n * const createPost = new Procedure(\n *   'app.bsky.feed.post',\n *   l.params({}),\n *   l.jsonPayload({ text: l.string() }),\n *   l.jsonPayload({ uri: l.string(), cid: l.string() }),\n *   ['InvalidRecord']\n * )\n * ```\n */\nexport class Procedure<\n  const TNsid extends NsidString = NsidString,\n  const TParameters extends ParamsSchema = ParamsSchema,\n  const TInputPayload extends Payload = Payload,\n  const TOutputPayload extends Payload = Payload,\n  const TErrors extends undefined | readonly string[] =\n    | undefined\n    | readonly string[],\n> {\n  readonly type = 'procedure' as const\n\n  constructor(\n    readonly nsid: TNsid,\n    readonly parameters: TParameters,\n    readonly input: TInputPayload,\n    readonly output: TOutputPayload,\n    readonly errors: TErrors,\n  ) {}\n}\n\n/**\n * Creates a procedure definition for a Lexicon POST endpoint.\n *\n * Procedures can modify server state. They accept both URL parameters\n * and a request body (input payload).\n *\n * @param nsid - The NSID identifying this procedure endpoint\n * @param parameters - Schema for URL query parameters\n * @param input - Schema for request body payload\n * @param output - Schema for response body payload\n * @param errors - Optional array of error type strings\n * @returns A new {@link Procedure} instance\n *\n * @example\n * ```ts\n * // Create record procedure\n * const createRecord = l.procedure(\n *   'com.atproto.repo.createRecord',\n *   l.params({}),\n *   l.jsonPayload({\n *     repo: l.string({ format: 'at-identifier' }),\n *     collection: l.string({ format: 'nsid' }),\n *     record: l.unknown(),\n *   }),\n *   l.jsonPayload({\n *     uri: l.string({ format: 'at-uri' }),\n *     cid: l.string({ format: 'cid' }),\n *   }),\n *   ['InvalidRecord', 'RepoNotFound'],\n * )\n *\n * // Procedure with binary input\n * const uploadBlob = l.procedure(\n *   'com.atproto.repo.uploadBlob',\n *   l.params({}),\n *   l.payload('*\\/*', undefined), // Accept any content type\n *   l.jsonPayload({ blob: l.blob() }),\n * )\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function procedure<\n  const N extends NsidString,\n  const P extends ParamsSchema,\n  const I extends Payload,\n  const O extends Payload,\n  const E extends undefined | readonly string[] = undefined,\n>(nsid: N, parameters: P, input: I, output: O, errors: E = undefined as E) {\n  return new Procedure<N, P, I, O, E>(nsid, parameters, input, output, errors)\n}\n"]}

package/dist/schema/query.d.ts

@@ -1,6 +1,28 @@
 import { NsidString } from '../core.js';
 import { ParamsSchema } from './params.js';
 import { Payload } from './payload.js';
+/**
+ * Represents a Lexicon query (HTTP GET) endpoint definition.
+ *
+ * Queries are read-only operations that retrieve data from a server.
+ * They have parameters (passed as URL query parameters), an output
+ * payload, and optional error types.
+ *
+ * @template TNsid - The NSID identifying this query
+ * @template TParameters - The parameters schema type
+ * @template TOutputPayload - The output payload type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const getPostQuery = new Query(
+ *   'app.bsky.feed.getPost',
+ *   l.params({ uri: l.string({ format: 'at-uri' }) }),
+ *   l.payload('application/json', postSchema),
+ *   ['NotFound']
+ * )
+ * ```
+ */
 export declare class Query<const TNsid extends NsidString = NsidString, const TParameters extends ParamsSchema = ParamsSchema, const TOutputPayload extends Payload = Payload, const TErrors extends undefined | readonly string[] = undefined | readonly string[]> {
     readonly nsid: TNsid;
     readonly parameters: TParameters;
@@ -9,5 +31,38 @@ export declare class Query<const TNsid extends NsidString = NsidString, const TP
     readonly type: "query";
     constructor(nsid: TNsid, parameters: TParameters, output: TOutputPayload, errors: TErrors);
 }
+/**
+ * Creates a query definition for a Lexicon GET endpoint.
+ *
+ * Queries retrieve data without side effects. Parameters are sent as
+ * URL query string parameters.
+ *
+ * @param nsid - The NSID identifying this query endpoint
+ * @param parameters - Schema for URL query parameters
+ * @param output - Expected response payload schema
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Query} instance
+ *
+ * @example
+ * ```ts
+ * // Simple query with JSON output
+ * const getProfile = l.query(
+ *   'app.bsky.actor.getProfile',
+ *   l.params({ actor: l.string({ format: 'at-identifier' }) }),
+ *   l.jsonPayload({ displayName: l.string(), handle: l.string() }),
+ * )
+ *
+ * // Query with pagination and errors
+ * const getTimeline = l.query(
+ *   'app.bsky.feed.getTimeline',
+ *   l.params({
+ *     limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),
+ *     cursor: l.optional(l.string()),
+ *   }),
+ *   l.jsonPayload({ feed: l.array(feedItemSchema), cursor: l.optional(l.string()) }),
+ *   ['BlockedActor', 'BlockedByActor'],
+ * )
+ * ```
+ */
 export declare function query<const N extends NsidString, const P extends ParamsSchema, const O extends Payload, const E extends undefined | readonly string[] = undefined>(nsid: N, parameters: P, output: O, errors?: E): Query<N, P, O, E>;
 //# sourceMappingURL=query.d.ts.map

package/dist/schema/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/schema/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,qBAAa,KAAK,CAChB,KAAK,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EAC3C,KAAK,CAAC,WAAW,SAAS,YAAY,GAAG,YAAY,EACrD,KAAK,CAAC,cAAc,SAAS,OAAO,GAAG,OAAO,EAC9C,KAAK,CAAC,OAAO,SAAS,SAAS,GAAG,SAAS,MAAM,EAAE,GAC/C,SAAS,GACT,SAAS,MAAM,EAAE;IAKnB,QAAQ,CAAC,IAAI,EAAE,KAAK;IACpB,QAAQ,CAAC,UAAU,EAAE,WAAW;IAChC,QAAQ,CAAC,MAAM,EAAE,cAAc;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO;IAN1B,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;gBAGrB,IAAI,EAAE,KAAK,EACX,UAAU,EAAE,WAAW,EACvB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,OAAO;CAE3B;AAGD,wBAAgB,KAAK,CACnB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,CAAC,SAAS,YAAY,EAC5B,KAAK,CAAC,CAAC,SAAS,OAAO,EACvB,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,EACzD,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,CAAkB,qBAE9D"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/schema/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,KAAK,CAChB,KAAK,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EAC3C,KAAK,CAAC,WAAW,SAAS,YAAY,GAAG,YAAY,EACrD,KAAK,CAAC,cAAc,SAAS,OAAO,GAAG,OAAO,EAC9C,KAAK,CAAC,OAAO,SAAS,SAAS,GAAG,SAAS,MAAM,EAAE,GAC/C,SAAS,GACT,SAAS,MAAM,EAAE;IAKnB,QAAQ,CAAC,IAAI,EAAE,KAAK;IACpB,QAAQ,CAAC,UAAU,EAAE,WAAW;IAChC,QAAQ,CAAC,MAAM,EAAE,cAAc;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO;IAN1B,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;gBAGrB,IAAI,EAAE,KAAK,EACX,UAAU,EAAE,WAAW,EACvB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,OAAO;CAE3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,wBAAgB,KAAK,CACnB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,CAAC,SAAS,YAAY,EAC5B,KAAK,CAAC,CAAC,SAAS,OAAO,EACvB,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,EACzD,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,CAAkB,qBAE9D"}

package/dist/schema/query.js

@@ -2,6 +2,28 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Query = void 0;
 exports.query = query;
+/**
+ * Represents a Lexicon query (HTTP GET) endpoint definition.
+ *
+ * Queries are read-only operations that retrieve data from a server.
+ * They have parameters (passed as URL query parameters), an output
+ * payload, and optional error types.
+ *
+ * @template TNsid - The NSID identifying this query
+ * @template TParameters - The parameters schema type
+ * @template TOutputPayload - The output payload type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const getPostQuery = new Query(
+ *   'app.bsky.feed.getPost',
+ *   l.params({ uri: l.string({ format: 'at-uri' }) }),
+ *   l.payload('application/json', postSchema),
+ *   ['NotFound']
+ * )
+ * ```
+ */
 class Query {
     nsid;
     parameters;
@@ -16,6 +38,39 @@ class Query {
     }
 }
 exports.Query = Query;
+/**
+ * Creates a query definition for a Lexicon GET endpoint.
+ *
+ * Queries retrieve data without side effects. Parameters are sent as
+ * URL query string parameters.
+ *
+ * @param nsid - The NSID identifying this query endpoint
+ * @param parameters - Schema for URL query parameters
+ * @param output - Expected response payload schema
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Query} instance
+ *
+ * @example
+ * ```ts
+ * // Simple query with JSON output
+ * const getProfile = l.query(
+ *   'app.bsky.actor.getProfile',
+ *   l.params({ actor: l.string({ format: 'at-identifier' }) }),
+ *   l.jsonPayload({ displayName: l.string(), handle: l.string() }),
+ * )
+ *
+ * // Query with pagination and errors
+ * const getTimeline = l.query(
+ *   'app.bsky.feed.getTimeline',
+ *   l.params({
+ *     limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),
+ *     cursor: l.optional(l.string()),
+ *   }),
+ *   l.jsonPayload({ feed: l.array(feedItemSchema), cursor: l.optional(l.string()) }),
+ *   ['BlockedActor', 'BlockedByActor'],
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function query(nsid, parameters, output, errors = undefined) {
     return new Query(nsid, parameters, output, errors);

package/dist/schema/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/schema/query.ts"],"names":[],"mappings":";;;AAuBA,sBAOC;AA1BD,MAAa,KAAK;IAWL;IACA;IACA;IACA;IANF,IAAI,GAAG,OAAgB,CAAA;IAEhC,YACW,IAAW,EACX,UAAuB,EACvB,MAAsB,EACtB,MAAe;QAHf,SAAI,GAAJ,IAAI,CAAO;QACX,eAAU,GAAV,UAAU,CAAa;QACvB,WAAM,GAAN,MAAM,CAAgB;QACtB,WAAM,GAAN,MAAM,CAAS;IACvB,CAAC;CACL;AAhBD,sBAgBC;AAED,wBAAwB;AACxB,SAAgB,KAAK,CAKnB,IAAO,EAAE,UAAa,EAAE,MAAS,EAAE,SAAY,SAAc;IAC7D,OAAO,IAAI,KAAK,CAAa,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAChE,CAAC","sourcesContent":["import { NsidString } from '../core.js'\nimport { ParamsSchema } from './params.js'\nimport { Payload } from './payload.js'\n\nexport class Query<\n  const TNsid extends NsidString = NsidString,\n  const TParameters extends ParamsSchema = ParamsSchema,\n  const TOutputPayload extends Payload = Payload,\n  const TErrors extends undefined | readonly string[] =\n    | undefined\n    | readonly string[],\n> {\n  readonly type = 'query' as const\n\n  constructor(\n    readonly nsid: TNsid,\n    readonly parameters: TParameters,\n    readonly output: TOutputPayload,\n    readonly errors: TErrors,\n  ) {}\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function query<\n  const N extends NsidString,\n  const P extends ParamsSchema,\n  const O extends Payload,\n  const E extends undefined | readonly string[] = undefined,\n>(nsid: N, parameters: P, output: O, errors: E = undefined as E) {\n  return new Query<N, P, O, E>(nsid, parameters, output, errors)\n}\n"]}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/schema/query.ts"],"names":[],"mappings":";;;AA8EA,sBAOC;AAjFD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,KAAK;IAWL;IACA;IACA;IACA;IANF,IAAI,GAAG,OAAgB,CAAA;IAEhC,YACW,IAAW,EACX,UAAuB,EACvB,MAAsB,EACtB,MAAe;QAHf,SAAI,GAAJ,IAAI,CAAO;QACX,eAAU,GAAV,UAAU,CAAa;QACvB,WAAM,GAAN,MAAM,CAAgB;QACtB,WAAM,GAAN,MAAM,CAAS;IACvB,CAAC;CACL;AAhBD,sBAgBC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAwB;AACxB,SAAgB,KAAK,CAKnB,IAAO,EAAE,UAAa,EAAE,MAAS,EAAE,SAAY,SAAc;IAC7D,OAAO,IAAI,KAAK,CAAa,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAChE,CAAC","sourcesContent":["import { NsidString } from '../core.js'\nimport { ParamsSchema } from './params.js'\nimport { Payload } from './payload.js'\n\n/**\n * Represents a Lexicon query (HTTP GET) endpoint definition.\n *\n * Queries are read-only operations that retrieve data from a server.\n * They have parameters (passed as URL query parameters), an output\n * payload, and optional error types.\n *\n * @template TNsid - The NSID identifying this query\n * @template TParameters - The parameters schema type\n * @template TOutputPayload - The output payload type\n * @template TErrors - Array of error type strings, or undefined\n *\n * @example\n * ```ts\n * const getPostQuery = new Query(\n *   'app.bsky.feed.getPost',\n *   l.params({ uri: l.string({ format: 'at-uri' }) }),\n *   l.payload('application/json', postSchema),\n *   ['NotFound']\n * )\n * ```\n */\nexport class Query<\n  const TNsid extends NsidString = NsidString,\n  const TParameters extends ParamsSchema = ParamsSchema,\n  const TOutputPayload extends Payload = Payload,\n  const TErrors extends undefined | readonly string[] =\n    | undefined\n    | readonly string[],\n> {\n  readonly type = 'query' as const\n\n  constructor(\n    readonly nsid: TNsid,\n    readonly parameters: TParameters,\n    readonly output: TOutputPayload,\n    readonly errors: TErrors,\n  ) {}\n}\n\n/**\n * Creates a query definition for a Lexicon GET endpoint.\n *\n * Queries retrieve data without side effects. Parameters are sent as\n * URL query string parameters.\n *\n * @param nsid - The NSID identifying this query endpoint\n * @param parameters - Schema for URL query parameters\n * @param output - Expected response payload schema\n * @param errors - Optional array of error type strings\n * @returns A new {@link Query} instance\n *\n * @example\n * ```ts\n * // Simple query with JSON output\n * const getProfile = l.query(\n *   'app.bsky.actor.getProfile',\n *   l.params({ actor: l.string({ format: 'at-identifier' }) }),\n *   l.jsonPayload({ displayName: l.string(), handle: l.string() }),\n * )\n *\n * // Query with pagination and errors\n * const getTimeline = l.query(\n *   'app.bsky.feed.getTimeline',\n *   l.params({\n *     limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),\n *     cursor: l.optional(l.string()),\n *   }),\n *   l.jsonPayload({ feed: l.array(feedItemSchema), cursor: l.optional(l.string()) }),\n *   ['BlockedActor', 'BlockedByActor'],\n * )\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function query<\n  const N extends NsidString,\n  const P extends ParamsSchema,\n  const O extends Payload,\n  const E extends undefined | readonly string[] = undefined,\n>(nsid: N, parameters: P, output: O, errors: E = undefined as E) {\n  return new Query<N, P, O, E>(nsid, parameters, output, errors)\n}\n"]}

package/dist/schema/record.d.ts

@@ -1,5 +1,30 @@
 import { $Typed, InferInput, InferOutput, LexiconRecordKey, NsidString, Schema, TidString, Unknown$TypedObject, ValidationContext, Validator } from '../core.js';
+/**
+ * Infers the record key type from a RecordSchema.
+ *
+ * @template R - The RecordSchema type
+ */
 export type InferRecordKey<R extends RecordSchema> = R extends RecordSchema<infer TKey> ? RecordKeySchemaOutput<TKey> : never;
+/**
+ * Schema for AT Protocol records with a type identifier and key constraints.
+ *
+ * Records are the primary data unit in AT Protocol. Each record has a `$type`
+ * field identifying its Lexicon schema, and is stored at a specific key
+ * (TID, NSID, or other format) in a repository.
+ *
+ * @template TKey - The record key type ('tid', 'nsid', 'any', or 'literal:...')
+ * @template TType - The NSID string identifying this record type
+ * @template TShape - The validator type for the record's data shape
+ *
+ * @example
+ * ```ts
+ * const postSchema = new RecordSchema(
+ *   'tid',
+ *   'app.bsky.feed.post',
+ *   l.object({ text: l.string(), createdAt: l.string() })
+ * )
+ * ```
+ */
 export declare class RecordSchema<const TKey extends LexiconRecordKey = any, const TType extends NsidString = any, const TShape extends Validator<{
     [k: string]: unknown;
 }> = any> extends Schema<$Typed<InferInput<TShape>, TType>, $Typed<InferOutput<TShape>, TType>> {
@@ -37,15 +62,45 @@ export type RecordKeySchema<Key extends LexiconRecordKey> = Schema<RecordKeySche
  */
 type AsNsid<T> = T extends `${string}#${string}` ? never : T;
 /**
+ * Creates a record schema for AT Protocol records.
+ *
+ * Records are the primary data unit in AT Protocol repositories. They have
+ * a `$type` field identifying their Lexicon schema, and are stored at keys
+ * following a specific format (TID, NSID, etc.).
+ *
  * This function offers two overloads:
- * - One that allows creating a {@link RecordSchema}, and infer the output type
- *   from the provided arguments, without requiring to specify any of the
- *   generics. This is useful when you want to define a record without
- *   explicitly defining its interface. This version does not support circular
- *   references, as TypeScript cannot infer types in such cases.
- * - One allows creating a {@link RecordSchema} with an explicitly defined
- *   interface. This will typically be used by codegen (`lex build`) to generate
- *   schemas that work even if they contain circular references.
+ * - One that infers the output type from the provided arguments (does not
+ *   support circular references)
+ * - One with an explicitly defined interface for use with codegen and
+ *   circular references
+ *
+ * @param key - The record key type: 'tid', 'nsid', 'any', or 'literal:value'
+ * @param type - The NSID identifying this record type (e.g., 'app.bsky.feed.post')
+ * @param validator - Schema validator for the record's properties
+ * @returns A new {@link RecordSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Post record with TID key
+ * const postSchema = l.record('tid', 'app.bsky.feed.post', l.object({
+ *   text: l.string({ maxGraphemes: 300 }),
+ *   createdAt: l.string({ format: 'datetime' }),
+ *   reply: l.optional(l.object({
+ *     root: l.ref(() => strongRefSchema),
+ *     parent: l.ref(() => strongRefSchema),
+ *   })),
+ * }))
+ *
+ * // Profile record with literal 'self' key
+ * const profileSchema = l.record('literal:self', 'app.bsky.actor.profile', l.object({
+ *   displayName: l.optional(l.string({ maxGraphemes: 64 })),
+ *   description: l.optional(l.string({ maxGraphemes: 256 })),
+ *   avatar: l.optional(l.blob({ accept: ['image/*'] })),
+ * }))
+ *
+ * // Build a record with automatic $type injection
+ * const post = postSchema.build({ text: 'Hello!', createdAt: new Date().toISOString() })
+ * ```
  */
 export declare function record<const K extends LexiconRecordKey, const T extends NsidString, const S extends Validator<{
     [k: string]: unknown;

package/dist/schema/record.d.ts.map

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

package/dist/schema/record.js

@@ -5,6 +5,26 @@ exports.record = record;
 const core_js_1 = require("../core.js");
 const literal_js_1 = require("./literal.js");
 const string_js_1 = require("./string.js");
+/**
+ * Schema for AT Protocol records with a type identifier and key constraints.
+ *
+ * Records are the primary data unit in AT Protocol. Each record has a `$type`
+ * field identifying its Lexicon schema, and is stored at a specific key
+ * (TID, NSID, or other format) in a repository.
+ *
+ * @template TKey - The record key type ('tid', 'nsid', 'any', or 'literal:...')
+ * @template TType - The NSID string identifying this record type
+ * @template TShape - The validator type for the record's data shape
+ *
+ * @example
+ * ```ts
+ * const postSchema = new RecordSchema(
+ *   'tid',
+ *   'app.bsky.feed.post',
+ *   l.object({ text: l.string(), createdAt: l.string() })
+ * )
+ * ```
+ */
 class RecordSchema extends core_js_1.Schema {
     key;
     $type;

package/dist/schema/record.js.map

@@ -1 +1 @@
-{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/schema/record.ts"],"names":[],"mappings":";;;AA6IA,wBAMC;AAnJD,wCAYmB;AACnB,6CAAsC;AACtC,2CAAoC;AAKpC,MAAa,YAIX,SAAQ,gBAGT;IAIY;IACA;IACA;IALX,SAAS,CAAuB;IAEhC,YACW,GAAS,EACT,KAAY,EACZ,MAAc;QAEvB,KAAK,EAAE,CAAA;QAJE,QAAG,GAAH,GAAG,CAAM;QACT,UAAK,GAAL,KAAK,CAAO;QACZ,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IACjC,CAAC;IAED,QAAQ,CACN,KAAQ;QAIR,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAA;IACnC,CAAC;IAED,KAAK,CACH,KAAsC;QAEtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,gBAAM,EAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IAC9C,CAAC;IAED,SAAS,CAAgC,KAAQ;QAC/C,OAAO,IAAI,CAAC,QAAQ,CAAI,KAAK,CAAC,CAAA;IAChC,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC1B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAE/C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,MAAM,CAAA;QACf,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,OAAO,GAAG,CAAC,yBAAyB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QAC3E,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAtDD,oCAsDC;AAiBD,MAAM,SAAS,GAAG,IAAA,kBAAM,EAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;AAC1C,MAAM,SAAS,GAAG,IAAA,kBAAM,EAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;AAC3C,MAAM,UAAU,GAAG,IAAA,kBAAM,EAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAC7C,MAAM,iBAAiB,GAAG,IAAA,oBAAO,EAAC,MAAM,CAAC,CAAA;AAEzC,SAAS,SAAS,CAChB,GAAQ;IAER,gDAAgD;IAChD,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,SAAgB,CAAA;IAC1C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,SAAgB,CAAA;IAC1C,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,UAAiB,CAAA;IAC5C,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAA+B,CAAA;QACxD,IAAI,KAAK,KAAK,MAAM;YAAE,OAAO,iBAAwB,CAAA;QACrD,OAAO,IAAA,oBAAO,EAAC,KAAK,CAAC,CAAA;IACvB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAA;AACxD,CAAC;AA+BD,wBAAwB;AACxB,SAAgB,MAAM,CAIpB,GAAM,EAAE,IAAO,EAAE,SAAY;IAC7B,OAAO,IAAI,YAAY,CAAU,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;AACxD,CAAC","sourcesContent":["import {\n  $Typed,\n  $typed,\n  InferInput,\n  InferOutput,\n  LexiconRecordKey,\n  NsidString,\n  Schema,\n  TidString,\n  Unknown$TypedObject,\n  ValidationContext,\n  Validator,\n} from '../core.js'\nimport { literal } from './literal.js'\nimport { string } from './string.js'\n\nexport type InferRecordKey<R extends RecordSchema> =\n  R extends RecordSchema<infer TKey> ? RecordKeySchemaOutput<TKey> : never\n\nexport class RecordSchema<\n  const TKey extends LexiconRecordKey = any,\n  const TType extends NsidString = any,\n  const TShape extends Validator<{ [k: string]: unknown }> = any,\n> extends Schema<\n  $Typed<InferInput<TShape>, TType>,\n  $Typed<InferOutput<TShape>, TType>\n> {\n  keySchema: RecordKeySchema<TKey>\n\n  constructor(\n    readonly key: TKey,\n    readonly $type: TType,\n    readonly schema: TShape,\n  ) {\n    super()\n    this.keySchema = recordKey(key)\n  }\n\n  isTypeOf<X extends { $type?: unknown }>(\n    value: X,\n  ): value is X extends { $type: TType }\n    ? X\n    : $Typed<Exclude<X, Unknown$TypedObject>, TType> {\n    return value.$type === this.$type\n  }\n\n  build(\n    input: Omit<InferInput<this>, '$type'>,\n  ): $Typed<InferOutput<this>, TType> {\n    return this.parse($typed(input, this.$type))\n  }\n\n  $isTypeOf<X extends { $type?: unknown }>(value: X) {\n    return this.isTypeOf<X>(value)\n  }\n\n  $build(input: Omit<InferInput<this>, '$type'>) {\n    return this.build(input)\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    const result = ctx.validate(input, this.schema)\n\n    if (!result.success) {\n      return result\n    }\n\n    if (result.value.$type !== this.$type) {\n      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])\n    }\n\n    return result\n  }\n}\n\nexport type RecordKeySchemaOutput<Key extends LexiconRecordKey> =\n  Key extends 'any'\n    ? string\n    : Key extends 'tid'\n      ? TidString\n      : Key extends 'nsid'\n        ? NsidString\n        : Key extends `literal:${infer L extends string}`\n          ? L\n          : never\n\nexport type RecordKeySchema<Key extends LexiconRecordKey> = Schema<\n  RecordKeySchemaOutput<Key>\n>\n\nconst keySchema = string({ minLength: 1 })\nconst tidSchema = string({ format: 'tid' })\nconst nsidSchema = string({ format: 'nsid' })\nconst selfLiteralSchema = literal('self')\n\nfunction recordKey<Key extends LexiconRecordKey>(\n  key: Key,\n): RecordKeySchema<Key> {\n  // @NOTE Use cached instances for common schemas\n  if (key === 'any') return keySchema as any\n  if (key === 'tid') return tidSchema as any\n  if (key === 'nsid') return nsidSchema as any\n  if (key.startsWith('literal:')) {\n    const value = key.slice(8) as RecordKeySchemaOutput<Key>\n    if (value === 'self') return selfLiteralSchema as any\n    return literal(value)\n  }\n\n  throw new Error(`Unsupported record key type: ${key}`)\n}\n\n/**\n * Ensures that a `$type` used in a record is a valid NSID (i.e. no fragment).\n */\ntype AsNsid<T> = T extends `${string}#${string}` ? never : T\n\n/**\n * This function offers two overloads:\n * - One that allows creating a {@link RecordSchema}, and infer the output type\n *   from the provided arguments, without requiring to specify any of the\n *   generics. This is useful when you want to define a record without\n *   explicitly defining its interface. This version does not support circular\n *   references, as TypeScript cannot infer types in such cases.\n * - One allows creating a {@link RecordSchema} with an explicitly defined\n *   interface. This will typically be used by codegen (`lex build`) to generate\n *   schemas that work even if they contain circular references.\n */\nexport function record<\n  const K extends LexiconRecordKey,\n  const T extends NsidString,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(key: K, type: AsNsid<T>, validator: S): RecordSchema<K, T, S>\nexport function record<\n  const K extends LexiconRecordKey,\n  const V extends { $type: NsidString },\n>(\n  key: K,\n  type: AsNsid<V['$type']>,\n  validator: Validator<Omit<V, '$type'>>,\n): RecordSchema<K, V['$type'], Validator<Omit<V, '$type'>>>\n/*@__NO_SIDE_EFFECTS__*/\nexport function record<\n  const K extends LexiconRecordKey,\n  const T extends NsidString,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(key: K, type: T, validator: S) {\n  return new RecordSchema<K, T, S>(key, type, validator)\n}\n"]}
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/schema/record.ts"],"names":[],"mappings":";;;AAoMA,wBAMC;AA1MD,wCAYmB;AACnB,6CAAsC;AACtC,2CAAoC;AAUpC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,YAIX,SAAQ,gBAGT;IAIY;IACA;IACA;IALX,SAAS,CAAuB;IAEhC,YACW,GAAS,EACT,KAAY,EACZ,MAAc;QAEvB,KAAK,EAAE,CAAA;QAJE,QAAG,GAAH,GAAG,CAAM;QACT,UAAK,GAAL,KAAK,CAAO;QACZ,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IACjC,CAAC;IAED,QAAQ,CACN,KAAQ;QAIR,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAA;IACnC,CAAC;IAED,KAAK,CACH,KAAsC;QAEtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,gBAAM,EAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IAC9C,CAAC;IAED,SAAS,CAAgC,KAAQ;QAC/C,OAAO,IAAI,CAAC,QAAQ,CAAI,KAAK,CAAC,CAAA;IAChC,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC1B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAE/C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,MAAM,CAAA;QACf,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,OAAO,GAAG,CAAC,yBAAyB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QAC3E,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAtDD,oCAsDC;AAiBD,MAAM,SAAS,GAAG,IAAA,kBAAM,EAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;AAC1C,MAAM,SAAS,GAAG,IAAA,kBAAM,EAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;AAC3C,MAAM,UAAU,GAAG,IAAA,kBAAM,EAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAC7C,MAAM,iBAAiB,GAAG,IAAA,oBAAO,EAAC,MAAM,CAAC,CAAA;AAEzC,SAAS,SAAS,CAChB,GAAQ;IAER,gDAAgD;IAChD,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,SAAgB,CAAA;IAC1C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,SAAgB,CAAA;IAC1C,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,UAAiB,CAAA;IAC5C,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAA+B,CAAA;QACxD,IAAI,KAAK,KAAK,MAAM;YAAE,OAAO,iBAAwB,CAAA;QACrD,OAAO,IAAA,oBAAO,EAAC,KAAK,CAAC,CAAA;IACvB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAA;AACxD,CAAC;AA6DD,wBAAwB;AACxB,SAAgB,MAAM,CAIpB,GAAM,EAAE,IAAO,EAAE,SAAY;IAC7B,OAAO,IAAI,YAAY,CAAU,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;AACxD,CAAC","sourcesContent":["import {\n  $Typed,\n  $typed,\n  InferInput,\n  InferOutput,\n  LexiconRecordKey,\n  NsidString,\n  Schema,\n  TidString,\n  Unknown$TypedObject,\n  ValidationContext,\n  Validator,\n} from '../core.js'\nimport { literal } from './literal.js'\nimport { string } from './string.js'\n\n/**\n * Infers the record key type from a RecordSchema.\n *\n * @template R - The RecordSchema type\n */\nexport type InferRecordKey<R extends RecordSchema> =\n  R extends RecordSchema<infer TKey> ? RecordKeySchemaOutput<TKey> : never\n\n/**\n * Schema for AT Protocol records with a type identifier and key constraints.\n *\n * Records are the primary data unit in AT Protocol. Each record has a `$type`\n * field identifying its Lexicon schema, and is stored at a specific key\n * (TID, NSID, or other format) in a repository.\n *\n * @template TKey - The record key type ('tid', 'nsid', 'any', or 'literal:...')\n * @template TType - The NSID string identifying this record type\n * @template TShape - The validator type for the record's data shape\n *\n * @example\n * ```ts\n * const postSchema = new RecordSchema(\n *   'tid',\n *   'app.bsky.feed.post',\n *   l.object({ text: l.string(), createdAt: l.string() })\n * )\n * ```\n */\nexport class RecordSchema<\n  const TKey extends LexiconRecordKey = any,\n  const TType extends NsidString = any,\n  const TShape extends Validator<{ [k: string]: unknown }> = any,\n> extends Schema<\n  $Typed<InferInput<TShape>, TType>,\n  $Typed<InferOutput<TShape>, TType>\n> {\n  keySchema: RecordKeySchema<TKey>\n\n  constructor(\n    readonly key: TKey,\n    readonly $type: TType,\n    readonly schema: TShape,\n  ) {\n    super()\n    this.keySchema = recordKey(key)\n  }\n\n  isTypeOf<X extends { $type?: unknown }>(\n    value: X,\n  ): value is X extends { $type: TType }\n    ? X\n    : $Typed<Exclude<X, Unknown$TypedObject>, TType> {\n    return value.$type === this.$type\n  }\n\n  build(\n    input: Omit<InferInput<this>, '$type'>,\n  ): $Typed<InferOutput<this>, TType> {\n    return this.parse($typed(input, this.$type))\n  }\n\n  $isTypeOf<X extends { $type?: unknown }>(value: X) {\n    return this.isTypeOf<X>(value)\n  }\n\n  $build(input: Omit<InferInput<this>, '$type'>) {\n    return this.build(input)\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    const result = ctx.validate(input, this.schema)\n\n    if (!result.success) {\n      return result\n    }\n\n    if (result.value.$type !== this.$type) {\n      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])\n    }\n\n    return result\n  }\n}\n\nexport type RecordKeySchemaOutput<Key extends LexiconRecordKey> =\n  Key extends 'any'\n    ? string\n    : Key extends 'tid'\n      ? TidString\n      : Key extends 'nsid'\n        ? NsidString\n        : Key extends `literal:${infer L extends string}`\n          ? L\n          : never\n\nexport type RecordKeySchema<Key extends LexiconRecordKey> = Schema<\n  RecordKeySchemaOutput<Key>\n>\n\nconst keySchema = string({ minLength: 1 })\nconst tidSchema = string({ format: 'tid' })\nconst nsidSchema = string({ format: 'nsid' })\nconst selfLiteralSchema = literal('self')\n\nfunction recordKey<Key extends LexiconRecordKey>(\n  key: Key,\n): RecordKeySchema<Key> {\n  // @NOTE Use cached instances for common schemas\n  if (key === 'any') return keySchema as any\n  if (key === 'tid') return tidSchema as any\n  if (key === 'nsid') return nsidSchema as any\n  if (key.startsWith('literal:')) {\n    const value = key.slice(8) as RecordKeySchemaOutput<Key>\n    if (value === 'self') return selfLiteralSchema as any\n    return literal(value)\n  }\n\n  throw new Error(`Unsupported record key type: ${key}`)\n}\n\n/**\n * Ensures that a `$type` used in a record is a valid NSID (i.e. no fragment).\n */\ntype AsNsid<T> = T extends `${string}#${string}` ? never : T\n\n/**\n * Creates a record schema for AT Protocol records.\n *\n * Records are the primary data unit in AT Protocol repositories. They have\n * a `$type` field identifying their Lexicon schema, and are stored at keys\n * following a specific format (TID, NSID, etc.).\n *\n * This function offers two overloads:\n * - One that infers the output type from the provided arguments (does not\n *   support circular references)\n * - One with an explicitly defined interface for use with codegen and\n *   circular references\n *\n * @param key - The record key type: 'tid', 'nsid', 'any', or 'literal:value'\n * @param type - The NSID identifying this record type (e.g., 'app.bsky.feed.post')\n * @param validator - Schema validator for the record's properties\n * @returns A new {@link RecordSchema} instance\n *\n * @example\n * ```ts\n * // Post record with TID key\n * const postSchema = l.record('tid', 'app.bsky.feed.post', l.object({\n *   text: l.string({ maxGraphemes: 300 }),\n *   createdAt: l.string({ format: 'datetime' }),\n *   reply: l.optional(l.object({\n *     root: l.ref(() => strongRefSchema),\n *     parent: l.ref(() => strongRefSchema),\n *   })),\n * }))\n *\n * // Profile record with literal 'self' key\n * const profileSchema = l.record('literal:self', 'app.bsky.actor.profile', l.object({\n *   displayName: l.optional(l.string({ maxGraphemes: 64 })),\n *   description: l.optional(l.string({ maxGraphemes: 256 })),\n *   avatar: l.optional(l.blob({ accept: ['image/*'] })),\n * }))\n *\n * // Build a record with automatic $type injection\n * const post = postSchema.build({ text: 'Hello!', createdAt: new Date().toISOString() })\n * ```\n */\nexport function record<\n  const K extends LexiconRecordKey,\n  const T extends NsidString,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(key: K, type: AsNsid<T>, validator: S): RecordSchema<K, T, S>\nexport function record<\n  const K extends LexiconRecordKey,\n  const V extends { $type: NsidString },\n>(\n  key: K,\n  type: AsNsid<V['$type']>,\n  validator: Validator<Omit<V, '$type'>>,\n): RecordSchema<K, V['$type'], Validator<Omit<V, '$type'>>>\n/*@__NO_SIDE_EFFECTS__*/\nexport function record<\n  const K extends LexiconRecordKey,\n  const T extends NsidString,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(key: K, type: T, validator: S) {\n  return new RecordSchema<K, T, S>(key, type, validator)\n}\n"]}

package/dist/schema/ref.d.ts

@@ -1,5 +1,27 @@
 import { InferInput, InferOutput, Schema, ValidationContext, Validator, WrappedValidator } from '../core.js';
+/**
+ * Function type that returns a validator, used for lazy schema resolution.
+ *
+ * @template TValidator - The validator type that will be returned
+ */
 export type RefSchemaGetter<out TValidator extends Validator> = () => TValidator;
+/**
+ * Schema for creating references to other schemas with lazy resolution.
+ *
+ * Useful for handling circular references or breaking module dependency cycles.
+ * The referenced schema is resolved lazily when first needed for validation.
+ *
+ * @template TValidator - The referenced validator type
+ *
+ * @example
+ * ```ts
+ * // Self-referential schema for tree structure
+ * const nodeSchema = l.object({
+ *   value: l.string(),
+ *   children: l.array(l.ref(() => nodeSchema)),
+ * })
+ * ```
+ */
 export declare class RefSchema<const TValidator extends Validator> extends Schema<InferInput<TValidator>, InferOutput<TValidator>, TValidator['__lex']> implements WrappedValidator<TValidator> {
     #private;
     constructor(getter: RefSchemaGetter<TValidator>);
@@ -7,6 +29,34 @@ export declare class RefSchema<const TValidator extends Validator> extends Schem
     unwrap(): TValidator;
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<InferInput<TValidator>>;
 }
+/**
+ * Creates a reference schema with lazy resolution.
+ *
+ * Allows referencing schemas that may not be defined yet, enabling
+ * circular references and breaking dependency cycles. The getter function
+ * is called lazily when validation is first performed.
+ *
+ * @param get - Function that returns the referenced validator
+ * @returns A new {@link RefSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Circular reference - tree node that contains children of the same type
+ * const treeNodeSchema = l.object({
+ *   name: l.string(),
+ *   children: l.optional(l.array(l.ref(() => treeNodeSchema))),
+ * })
+ *
+ * // Cross-module reference
+ * const commentSchema = l.object({
+ *   text: l.string(),
+ *   author: l.ref(() => userSchema), // userSchema defined elsewhere
+ * })
+ *
+ * // Explicitly typed reference
+ * const itemSchema = l.ref<Item>(() => complexItemSchema)
+ * ```
+ */
 export declare function ref<const TValidator extends Validator>(get: RefSchemaGetter<TValidator>): RefSchema<TValidator>;
 export declare function ref<TInput, TOutput extends TInput = TInput>(get: RefSchemaGetter<Validator<TInput, TOutput>>): RefSchema<Validator<TInput, TOutput>>;
 //# sourceMappingURL=ref.d.ts.map

package/dist/schema/ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/schema/ref.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,eAAe,CAAC,GAAG,CAAC,UAAU,SAAS,SAAS,IAAI,MAAM,UAAU,CAAA;AAEhF,qBAAa,SAAS,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,CACvD,SAAQ,MAAM,CACZ,UAAU,CAAC,UAAU,CAAC,EACtB,WAAW,CAAC,UAAU,CAAC,EACvB,UAAU,CAAC,OAAO,CAAC,CAErB,YAAW,gBAAgB,CAAC,UAAU,CAAC;;gBAI3B,MAAM,EAAE,eAAe,CAAC,UAAU,CAAC;IAS/C,IAAI,SAAS,IAAI,UAAU,CAE1B;IAED,MAAM,IAAI,UAAU;IAIpB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAGzD;AAGD,wBAAgB,GAAG,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,EACpD,GAAG,EAAE,eAAe,CAAC,UAAU,CAAC,GAC/B,SAAS,CAAC,UAAU,CAAC,CAAA;AACxB,wBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,EACzD,GAAG,EAAE,eAAe,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC/C,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA"}
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/schema/ref.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,GAAG,CAAC,UAAU,SAAS,SAAS,IAAI,MAAM,UAAU,CAAA;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,CACvD,SAAQ,MAAM,CACZ,UAAU,CAAC,UAAU,CAAC,EACtB,WAAW,CAAC,UAAU,CAAC,EACvB,UAAU,CAAC,OAAO,CAAC,CAErB,YAAW,gBAAgB,CAAC,UAAU,CAAC;;gBAI3B,MAAM,EAAE,eAAe,CAAC,UAAU,CAAC;IAS/C,IAAI,SAAS,IAAI,UAAU,CAE1B;IAED,MAAM,IAAI,UAAU;IAIpB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,GAAG,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,EACpD,GAAG,EAAE,eAAe,CAAC,UAAU,CAAC,GAC/B,SAAS,CAAC,UAAU,CAAC,CAAA;AACxB,wBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,EACzD,GAAG,EAAE,eAAe,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC/C,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA"}

package/dist/schema/ref.js

@@ -3,6 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RefSchema = void 0;
 exports.ref = ref;
 const core_js_1 = require("../core.js");
+/**
+ * Schema for creating references to other schemas with lazy resolution.
+ *
+ * Useful for handling circular references or breaking module dependency cycles.
+ * The referenced schema is resolved lazily when first needed for validation.
+ *
+ * @template TValidator - The referenced validator type
+ *
+ * @example
+ * ```ts
+ * // Self-referential schema for tree structure
+ * const nodeSchema = l.object({
+ *   value: l.string(),
+ *   children: l.array(l.ref(() => nodeSchema)),
+ * })
+ * ```
+ */
 class RefSchema extends core_js_1.Schema {
     #getter;
     constructor(getter) {

package/dist/schema/ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../src/schema/ref.ts"],"names":[],"mappings":";;;AAkDA,kBAIC;AAtDD,wCAOmB;AAInB,MAAa,SACX,SAAQ,gBAIP;IAGD,OAAO,CAA6B;IAEpC,YAAY,MAAmC;QAC7C,uEAAuE;QACvE,sEAAsE;QAEtE,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5C,CAAC;CACF;AA9BD,8BA8BC;AASD,SAAgB,GAAG,CACjB,GAAgC;IAEhC,OAAO,IAAI,SAAS,CAAa,GAAG,CAAC,CAAA;AACvC,CAAC","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n  WrappedValidator,\n} from '../core.js'\n\nexport type RefSchemaGetter<out TValidator extends Validator> = () => TValidator\n\nexport class RefSchema<const TValidator extends Validator>\n  extends Schema<\n    InferInput<TValidator>,\n    InferOutput<TValidator>,\n    TValidator['__lex']\n  >\n  implements WrappedValidator<TValidator>\n{\n  #getter: RefSchemaGetter<TValidator>\n\n  constructor(getter: RefSchemaGetter<TValidator>) {\n    // @NOTE In order to avoid circular dependency issues, we don't resolve\n    // the schema here. Instead, we resolve it lazily when first accessed.\n\n    super()\n\n    this.#getter = getter\n  }\n\n  get validator(): TValidator {\n    return this.#getter.call(null)\n  }\n\n  unwrap(): TValidator {\n    return this.validator\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    return ctx.validate(input, this.validator)\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function ref<const TValidator extends Validator>(\n  get: RefSchemaGetter<TValidator>,\n): RefSchema<TValidator>\nexport function ref<TInput, TOutput extends TInput = TInput>(\n  get: RefSchemaGetter<Validator<TInput, TOutput>>,\n): RefSchema<Validator<TInput, TOutput>>\nexport function ref<const TValidator extends Validator>(\n  get: RefSchemaGetter<TValidator>,\n) {\n  return new RefSchema<TValidator>(get)\n}\n"]}
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../src/schema/ref.ts"],"names":[],"mappings":";;;AAoGA,kBAIC;AAxGD,wCAOmB;AASnB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,SACX,SAAQ,gBAIP;IAGD,OAAO,CAA6B;IAEpC,YAAY,MAAmC;QAC7C,uEAAuE;QACvE,sEAAsE;QAEtE,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5C,CAAC;CACF;AA9BD,8BA8BC;AAqCD,SAAgB,GAAG,CACjB,GAAgC;IAEhC,OAAO,IAAI,SAAS,CAAa,GAAG,CAAC,CAAA;AACvC,CAAC","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n  WrappedValidator,\n} from '../core.js'\n\n/**\n * Function type that returns a validator, used for lazy schema resolution.\n *\n * @template TValidator - The validator type that will be returned\n */\nexport type RefSchemaGetter<out TValidator extends Validator> = () => TValidator\n\n/**\n * Schema for creating references to other schemas with lazy resolution.\n *\n * Useful for handling circular references or breaking module dependency cycles.\n * The referenced schema is resolved lazily when first needed for validation.\n *\n * @template TValidator - The referenced validator type\n *\n * @example\n * ```ts\n * // Self-referential schema for tree structure\n * const nodeSchema = l.object({\n *   value: l.string(),\n *   children: l.array(l.ref(() => nodeSchema)),\n * })\n * ```\n */\nexport class RefSchema<const TValidator extends Validator>\n  extends Schema<\n    InferInput<TValidator>,\n    InferOutput<TValidator>,\n    TValidator['__lex']\n  >\n  implements WrappedValidator<TValidator>\n{\n  #getter: RefSchemaGetter<TValidator>\n\n  constructor(getter: RefSchemaGetter<TValidator>) {\n    // @NOTE In order to avoid circular dependency issues, we don't resolve\n    // the schema here. Instead, we resolve it lazily when first accessed.\n\n    super()\n\n    this.#getter = getter\n  }\n\n  get validator(): TValidator {\n    return this.#getter.call(null)\n  }\n\n  unwrap(): TValidator {\n    return this.validator\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    return ctx.validate(input, this.validator)\n  }\n}\n\n/**\n * Creates a reference schema with lazy resolution.\n *\n * Allows referencing schemas that may not be defined yet, enabling\n * circular references and breaking dependency cycles. The getter function\n * is called lazily when validation is first performed.\n *\n * @param get - Function that returns the referenced validator\n * @returns A new {@link RefSchema} instance\n *\n * @example\n * ```ts\n * // Circular reference - tree node that contains children of the same type\n * const treeNodeSchema = l.object({\n *   name: l.string(),\n *   children: l.optional(l.array(l.ref(() => treeNodeSchema))),\n * })\n *\n * // Cross-module reference\n * const commentSchema = l.object({\n *   text: l.string(),\n *   author: l.ref(() => userSchema), // userSchema defined elsewhere\n * })\n *\n * // Explicitly typed reference\n * const itemSchema = l.ref<Item>(() => complexItemSchema)\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function ref<const TValidator extends Validator>(\n  get: RefSchemaGetter<TValidator>,\n): RefSchema<TValidator>\nexport function ref<TInput, TOutput extends TInput = TInput>(\n  get: RefSchemaGetter<Validator<TInput, TOutput>>,\n): RefSchema<Validator<TInput, TOutput>>\nexport function ref<const TValidator extends Validator>(\n  get: RefSchemaGetter<TValidator>,\n) {\n  return new RefSchema<TValidator>(get)\n}\n"]}

package/dist/schema/refine.d.ts

@@ -1,32 +1,81 @@
 import { InferInput, PropertyKey, Validator } from '../core.js';
 import { CustomAssertionContext } from './custom.js';
+/**
+ * Configuration for a refinement check that validates a condition.
+ *
+ * @template T - The type being validated
+ * @property check - Function that returns true if the value passes the check
+ * @property message - Error message when the check fails
+ * @property path - Optional path to associate with the error
+ */
 export type RefinementCheck<T> = {
     check: (value: T, ctx: CustomAssertionContext) => boolean;
     message: string;
     path?: PropertyKey | readonly PropertyKey[];
 };
+/**
+ * Configuration for a refinement assertion that narrows the type.
+ *
+ * @template T - The input type being validated
+ * @template Out - The narrowed output type
+ * @property check - Type guard function that narrows the type
+ * @property message - Error message when the assertion fails
+ * @property path - Optional path to associate with the error
+ */
 export type RefinementAssertion<T, Out extends T> = {
     check: (this: null, value: T, ctx: CustomAssertionContext) => value is Out;
     message: string;
     path?: PropertyKey | readonly PropertyKey[];
 };
+/**
+ * Infers the input type from a refinement configuration.
+ *
+ * @template R - The refinement type
+ */
 export type InferRefinement<R> = R extends RefinementCheck<infer T> ? T : R extends RefinementAssertion<infer T, any> ? T : never;
+/**
+ * Union type of refinement check or assertion.
+ *
+ * @template T - The input type being validated
+ * @template Out - The output type (same as T for checks, narrowed for assertions)
+ */
 export type Refinement<T = any, Out extends T = T> = RefinementCheck<T> | RefinementAssertion<T, Out>;
 /**
- * Create a refined schema based on an existing schema and a refinement check.
+ * Creates a refined schema by adding additional validation constraints.
  *
- * @param schema - The base schema to refine.
- * @param refinement - The refinement check to apply.
- * @returns A new schema that includes the refinement.
- * @example
+ * Wraps an existing schema with an additional check function. The base schema
+ * is validated first, then the refinement check is applied to the result.
  *
+ * @param schema - The base schema to refine
+ * @param refinement - The refinement check or assertion to apply
+ * @returns A new schema that includes the refinement
+ *
+ * @example
  * ```ts
- * const PositiveInt = refine(l.integer(), {
+ * // Simple check refinement
+ * const positiveInt = l.refine(l.integer(), {
  *   check: (value) => value > 0,
- *   message: 'Value must be a positive integer',
+ *   message: 'Value must be positive',
  * })
- * const result = PositiveInt.validate(-5)
- * // result.success === false
+ *
+ * positiveInt.parse(5)  // 5
+ * positiveInt.parse(-1) // throws
+ *
+ * // Type-narrowing assertion
+ * const nonEmptyString = l.refine(l.string(), {
+ *   check: (value): value is string & { length: number } => value.length > 0,
+ *   message: 'String must not be empty',
+ * })
+ *
+ * // With custom path for nested errors
+ * const validDateRange = l.refine(
+ *   l.object({ start: l.string(), end: l.string() }),
+ *   {
+ *     check: (v) => new Date(v.start) < new Date(v.end),
+ *     message: 'Start date must be before end date',
+ *     path: ['end'],
+ *   }
+ * )
  * ```
  */
 export declare function refine<const TValidator extends Validator, TInput extends InferInput<TValidator>>(schema: TValidator, refinement: RefinementAssertion<InferInput<TValidator>, TInput>): TValidator & Validator<TInput>;

package/dist/schema/refine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refine.d.ts","sourceRoot":"","sources":["../../src/schema/refine.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,WAAW,EAGX,SAAS,EACV,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAEpD,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,sBAAsB,KAAK,OAAO,CAAA;IACzD,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA;CAC5C,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI;IAClD,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,sBAAsB,KAAK,KAAK,IAAI,GAAG,CAAA;IAC1E,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA;CAC5C,CAAA;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,IAC3B,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GAC9B,CAAC,GACD,CAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GACzC,CAAC,GACD,KAAK,CAAA;AAEb,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,IAC7C,eAAe,CAAC,CAAC,CAAC,GAClB,mBAAmB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;AAE/B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,UAAU,SAAS,SAAS,EAClC,MAAM,SAAS,UAAU,CAAC,UAAU,CAAC,EAErC,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,mBAAmB,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,GAC9D,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;AACjC,wBAAgB,MAAM,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,EACvD,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,GAClD,UAAU,CAAA;AACb,wBAAgB,MAAM,CACpB,WAAW,SAAS,UAAU,EAC9B,KAAK,CAAC,UAAU,SAAS,SAAS,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,EAChE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,GAAG,UAAU,CAAA"}
+{"version":3,"file":"refine.d.ts","sourceRoot":"","sources":["../../src/schema/refine.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,WAAW,EAGX,SAAS,EACV,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,sBAAsB,KAAK,OAAO,CAAA;IACzD,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA;CAC5C,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI;IAClD,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,sBAAsB,KAAK,KAAK,IAAI,GAAG,CAAA;IAC1E,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA;CAC5C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAC3B,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GAC9B,CAAC,GACD,CAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GACzC,CAAC,GACD,KAAK,CAAA;AAEb;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,IAC7C,eAAe,CAAC,CAAC,CAAC,GAClB,mBAAmB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,UAAU,SAAS,SAAS,EAClC,MAAM,SAAS,UAAU,CAAC,UAAU,CAAC,EAErC,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,mBAAmB,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,GAC9D,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;AACjC,wBAAgB,MAAM,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,EACvD,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,GAClD,UAAU,CAAA;AACb,wBAAgB,MAAM,CACpB,WAAW,SAAS,UAAU,EAC9B,KAAK,CAAC,UAAU,SAAS,SAAS,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,EAChE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,GAAG,UAAU,CAAA"}