@atcute/lexicons

core types and syntax validators for AT Protocol.

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

validating syntax

use the syntax validators to check AT Protocol string formats:

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

parsing AT URIs

parse AT URIs to extract their components:

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

// parse any AT URI (handle or DID authority); throws SyntaxError on invalid input
const uri = parseResourceUri('at://alice.bsky.social/app.bsky.feed.post/123');
console.log(uri.repo); // 'alice.bsky.social'
console.log(uri.collection); // 'app.bsky.feed.post'
console.log(uri.rkey); // '123'

// parse canonical AT URI (DID authority only); throws SyntaxError on invalid input
const canonical = parseCanonicalResourceUri('at://did:plc:123/app.bsky.feed.post/abc');
console.log(canonical.repo); // 'did:plc:123'

branded types

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

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

function getProfile(handle: Handle): Promise<Profile> {
    // 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);
}

validating records

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

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);
    }
}

IPLD types

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

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