@atcute/lexicons

core types and syntax validators for AT Protocol.

``sh
npm install @atcute/lexicons
`

this package provides syntax validators for AT Protocol's string formats (handles, DIDs, NSIDs,
etc.) and validation functions for use with lexicon schemas from definition packages.

usage

$3

use the syntax validators to check AT Protocol string formats:

`ts
import {
isHandle,
isDid,
isNsid,
isCid,
isTid,
isRecordKey,
isDatetime,
isResourceUri,
isActorIdentifier,
} from '@atcute/lexicons/syntax';

// handle format (domain names)
isHandle('alice.bsky.social'); // true
isHandle('invalid'); // false (no TLD)

// DID format
isDid('did:plc:z72i7hdynmk6r22z27h6tvur'); // true
isDid('did:web:example.com'); // true
isDid('not-a-did'); // false

// NSID format (namespaced identifiers)
isNsid('app.bsky.feed.post'); // true
isNsid('com.atproto.repo.createRecord'); // true

// CID format (content identifiers)
isCid('bafyreigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi'); // true

// TID format (timestamp identifiers)
isTid('3jzfcijpj2z2a'); // true

// record key format
isRecordKey('3jzfcijpj2z2a'); // true (TID)
isRecordKey('self'); // true (literal "self")

// datetime format (ISO 8601)
isDatetime('2024-01-15T12:00:00.000Z'); // true

// AT URI format
isResourceUri('at://did:plc:123/app.bsky.feed.post/abc'); // true

// actor identifier (handle or DID)
isActorIdentifier('alice.bsky.social'); // true
isActorIdentifier('did:plc:123'); // true
`

$3

parse AT URIs to extract their components:

`ts
import { parseResourceUri, parseCanonicalResourceUri } from '@atcute/lexicons/syntax';

// parse any AT URI (handle or DID authority)
const uri = parseResourceUri('at://alice.bsky.social/app.bsky.feed.post/123');
if (uri.ok) {
console.log(uri.value.repo); // 'alice.bsky.social'
console.log(uri.value.collection); // 'app.bsky.feed.post'
console.log(uri.value.rkey); // '123'
}

// parse canonical AT URI (DID authority only)
const canonical = parseCanonicalResourceUri('at://did:plc:123/app.bsky.feed.post/abc');
if (canonical.ok) {
console.log(canonical.value.repo); // 'did:plc:123'
}
`

$3

the syntax module exports branded types for type-safe string handling:

`ts
import type { Handle, Did, Nsid, Cid, Tid, RecordKey, Datetime } from '@atcute/lexicons/syntax';
import { isHandle } from '@atcute/lexicons/syntax';

function getProfile(handle: Handle): Promise {
// handle is guaranteed to be a valid handle format
}

const input = 'alice.bsky.social';
if (isHandle(input)) {
// input is narrowed to Handle type
getProfile(input);
}
`

$3

validate data against lexicon schemas using is(), safeParse(), or parse(). schemas come from
definition packages like @atcute/bluesky:

`ts
import { is, safeParse, parse, ValidationError } from '@atcute/lexicons';
import { AppBskyFeedPost } from '@atcute/bluesky';

const data: unknown = {
$type: 'app.bsky.feed.post',
text: 'hello world',
createdAt: '2024-01-15T12:00:00.000Z',
};

// type guard - returns boolean
if (is(AppBskyFeedPost.mainSchema, data)) {
// data is typed as AppBskyFeedPost.$record
console.log(data.text);
}

// safe parse - returns result object
const result = safeParse(AppBskyFeedPost.mainSchema, data);
if (result.ok) {
console.log(result.value.text);
} else {
console.log(result.message);
console.log(result.issues);
}

// parse - throws on failure
try {
const post = parse(AppBskyFeedPost.mainSchema, data);
console.log(post.text);
} catch (err) {
if (err instanceof ValidationError) {
console.log(err.message);
console.log(err.issues);
}
}
`

$3

the package exports types for IPLD data structures used in AT Protocol:

`ts
import type { Blob, Bytes, CidLink } from '@atcute/lexicons';

// Blob - reference to uploaded media (images, videos)
// Bytes - raw binary data (base64 encoded in JSON)
// CidLink - reference to content by CID
``