@gnldev/options

中文文档
0.18.0发布于 2026/11/09Apache-2.0TypeScriptES Module零依赖构建来源已验证近 30 天下载 3575

One rule for every GNL options object: a name it does not take is refused, with the option it is closest to. No dependencies.

原始使用文档

@gnldev/options

Part of GNL, a full agent framework for TypeScript — works with the rest of it, or on its own.

One rule for every options object GNL reads: a name it does not take is refused, with the option it is closest to.

An options object read by name and never checked drops a misspelled name without a word. Measured across the GNL packages before this rule: a misspelled authorize left a door without its policy, a misspelled guard left an agent without its guard, limits.maxToolCall let a tool run past its limit, and an SSO issuer written isuer accepted any issuer's token. Each now fails where the object is read:

createChatRoute: `authorise` is not an option — did you mean `authorize`? Nothing would read it, so it would run without it.

You do not install this package: every GNL package that checks its options depends on it.

For a package author

import { refuseUnknownNames, optionNames } from '@gnldev/options';

interface MyOptions { retries?: number; timeoutMs?: number }

// The list is held to the type by the compiler: a name that is no member, or a member left out, fails typecheck.
const NAMES = optionNames<MyOptions>()(['retries', 'timeoutMs']);

export function myThing(opts: MyOptions = {}) {
  refuseUnknownNames('myThing', opts, NAMES);
  // …
}
  • refuseUnknownNames(where, value, names, removed?) — refuses any name not in names. removed maps a former option to the sentence that says what replaced it.
  • refuseMisspelledNames(where, value, names) — for an object passed on to another library (GNL's runDurable passes the AI SDK's options to generateText): a name is refused only when it is a misspelling of a known one, so an option a newer version of that library adds still passes.
  • optionNames<T>() / variantNames<T>() — the name list of an object type, or of every variant of a union.

A name set to undefined is no name: spreading an optional value is never refused. Only options bags are checked — an implementation of an interface (a storage, a model, a provider) may carry members of its own.

When a package's options change

Nothing has to be remembered: the compiler and pnpm check:option-names (CI) say what to update.

ChangeWhat failsFix
A field added to an options typetypecheck: the name list reports missing: "<field>"add the name to the list
A field removed or renamedtypecheck: the list names a field the type no longer hasdrop it; to say what replaced it, add the old name to the removed table
A new exported function, constructor, method or options type without the checkcheck:option-nameshand the bag to refuseUnknownNames, or tag gnl-internal plumbing @internal — <why>
A new gnl.config field for gnl devtypecheck in @gnldev/cli (pinned both ways to PROJECT_CONFIG_NAMES)add it to PROJECT_CONFIG_NAMES in @gnldev/durable
A newer AI SDK adds an optionnothing for the host: a name close to none passes on to the AI SDK; on upgrade, typecheck asks for the SDK's new namesadd them to the AI SDK list

One blind spot: a method of an object a factory returns (createCache(...).set) is held only by its options type having a list — check:option-names cannot see that the method body reads it. Review that call when adding such a method.

版本与发布记录

@gnldev/options 共发布 11 个版本,首次发布于 2026/10/06;过去 12 个月发布了 11 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.18.0latest2026/11/097 天前
0.17.02026/11/079 天前
0.16.02026/11/0214 天前
0.15.02026/10/2522 天前
0.14.02026/10/2324 天前
0.13.02026/10/2126 天前

关于 @gnldev/options 的常见问题

@gnldev/options 是什么?

One rule for every GNL options object: a name it does not take is refused, with the option it is closest to. No dependencies.

如何安装 @gnldev/options?

在项目目录运行 npm install @gnldev/options,或使用 pnpm add / yarn add / bun add。

@gnldev/options 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gnldev/options 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gnldev/options 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.13.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gnldev/options 可以商用吗?

@gnldev/options 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gnldev/options 的下载量有多少?

根据 npm 官方下载统计,@gnldev/options 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,575 次,日均约 119 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gnldev/options 还在维护吗?

最新版本 0.18.0 发布于 2026/11/09(7 天前);至今共发布 11 个版本,其中过去 12 个月发布了 11 个;首次发布于 2026/10/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。