@ atcute/ lex- cli

从词典文档中生成 TypeScript 计划.

npm install @atcute/lex-cli

快速开始

创建配置文件,用于指导工具查找词汇文档的位置 将生成的 TypeScript 计划放入其中:

// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
    },
});

然后运行工具( 它自动查找) lex.config.js 或者说 lex.config.ts:

npm exec lex-cli generate

使用类型脚本编写词典

而不是将词汇表写为 JSON 文件, 你可以在程序上使用 构建器函数来自 @atcute/lexicon-doc/builder。 。 。 .

// file: lexicons-src/com/example/bookmark.ts
import { array, document, object, record, required, string } from '@atcute/lexicon-doc/builder';

export default document({
    id: 'com.example.bookmark',
    defs: {
        main: record({
            key: 'tid',
            description: 'a saved link to come back to later',
            record: object({
                properties: {
                    subject: required(string({ format: 'uri' })),
                    createdAt: required(string({ format: 'datetime' })),
                    tags: array({ items: string(), description: 'tags for organizing bookmarks' }),
                },
            }),
        }),
    },
});

更新您的配置以指向 TypeScript 文件 :

// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons-src/**/*.ts'],
        outdir: 'src/lexicons/',
    },
});

向 JSON 导出词典

如果您需要实际的 JSON 词汇文档(例如用于发布或共享),请配置 导出命令 :

export default defineLexiconConfig({
    generate: {
        files: ['lexicons-src/**/*.ts'],
        outdir: 'src/lexicons/',
    },
    export: {
        outdir: 'lexicons/',
        clean: true,
    },
});

然后运行 :

npm exec lex-cli export

绘制词典

您可以从其他来源调取词汇文件.

git 来源

从 git 寄存器中取出词典 :

// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
    },
    pull: {
        outdir: 'lexicons/',
        clean: true,
        sources: [
            {
                type: 'git',
                remote: 'https://github.com/bluesky-social/atproto.git',
                ref: 'main',
                pattern: ['lexicons/**/*.json'],
            },
        ],
    },
});

原生地来源

从AT协议网络直接拉出词典.

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
    },
    pull: {
        outdir: 'lexicons/',
        sources: [
            {
                type: 'atproto',
                mode: 'nsids',
                nsids: ['app.bsky.feed.post', 'app.bsky.actor.profile'],
            },
            {
                type: 'atproto',
                mode: 'authority',
                authority: 'atproto-lexicons.bsky.social',
                pattern: ['com.atproto.*'], // optional
            },
        ],
    },
});

运行拉动命令

将词典拉入磁盘,然后从中生成类型 :

npm exec lex-cli pull
npm exec lex-cli generate

发布您的计划

如果你正在将生成的策略包装成可出版的库,请添加 atcute:lexicons 字段 给你的包裹 json 它允许其他工程自动发现和导入您的计划 没有手动配置.

{
    "name": "@example/my-schemas",
    "atcute:lexicons": {
        "mappings": {
            "com.example.*": {
                "type": "namespace",
                "path": "./types/{{nsid_remainder}}"
            }
        }
    }
}

页:1 path 字段支持多个模板扩展:

• . 或者说 ./ 开始时用软件包名称替换(例如, ./types/foo 变成 @example/my-schemas/types/foo,或 . 变成 @example/my-schemas(中文(简体) )
• {{nsid}} - 完整的NSID 有点被鞭打所取代(例如, com/example/foo/bar(中文(简体) )
• {{nsid_prefix}} - 通配符前的部分(例如, com/example(中文(简体) )
• {{nsid_remainder}} - 前缀后的部分(例如, foo/bar(中文(简体) )

外部参考资料

当您的词典从您配置的文件以外的命名空间引用类型时, 您需要 配置这些引用是如何解决的 .

例如,如果您的词典引用了另一个命名空间的某个类型:

// file: lexdocs/tools/ozone/team/defs.json
{
    "lexicon": 1,
    "id": "tools.ozone.team.defs",
    "defs": {
        "member": {
            "type": "object",
            "required": ["did", "role"],
            "properties": {
                "profile": {
                    "type": "ref",
                    "ref": "app.bsky.actor.defs#profileViewDetailed",
                    //     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                    //     not covered by any of our included files
                },
            },
        },
    },
}

解决外部引用的最简单方法是 imports 带有软件包的阵列 提供 atcute:lexicons 元数据 :

// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
        imports: ['@atcute/atproto', '@atcute/bluesky'],
    },
});

cLI 将自动从每个软件包中发现命名空间映射 atcute:lexicons (原始内容存档于2018-03-21). field in their package.json.

对于没有元数据的软件包,或者当您需要更精细的导入分辨率控制时, 使用该 mappings 替换配置 :

// file: lex.config.js
import { defineLexiconConfig } from '@atcute/lex-cli';

export default defineLexiconConfig({
    generate: {
        files: ['lexicons/**/*.json'],
        outdir: 'src/lexicons/',
        mappings: [
            {
                nsid: ['com.atproto.*'],
                imports: (nsid) => {
                    const specifier = nsid.slice('com.atproto.'.length).replaceAll('.', '/');
                    return { type: 'namespace', from: `@atcute/atproto/types/${specifier}` };
                },
            },
            {
                nsid: ['app.bsky.*'],
                imports: (nsid) => {
                    const specifier = nsid.slice('app.bsky.'.length).replaceAll('.', '/');
                    return { type: 'namespace', from: `@atcute/bluesky/types/app/${specifier}` };
                },
            },
        ],
    },
});