@ atcute/ 语法

aT 协议的核心类型和语法验证符.

npm install @atcute/lexicons

此软件包为 AT 协议的字符串格式提供语法验证器( 手语、 DDEs、 NSIDs, ) , 等),以及用于定义包中用lexicon schemas的验证功能.

使用量

正在验证语法

使用语法验证符检查 AT 协议字符串格式 :

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

解析 AT URI

分析 AT URI 以提取其组件:

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'

品牌类型

用于类型安全字符串处理的语法模块导出品牌类型 :

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

正在验证记录

使用词汇图验证数据 is(), (中文(简体) ), safeParse(),或 parse()计划来自 定义软件包 @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 类型

aT 协议中使用的 IPLD 数据结构的软件包导出类型 :

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