diff --git a/mk/make-pkg-tsconfig.mjs b/mk/make-pkg-tsconfig.mjs index 4fadc005..7898a6b7 100644 --- a/mk/make-pkg-tsconfig.mjs +++ b/mk/make-pkg-tsconfig.mjs @@ -18,6 +18,7 @@ const tsconfig = { exclude: ["**/node_modules", "**/lib", "**/test-fixture", "**/tests"], excludeExternals: true, excludePrivate: true, + jsDocCompatibility: false, validation: { notExported: false, }, diff --git a/mk/typedoc.config.cjs b/mk/typedoc.config.cjs index c63fd8b7..4e050ee6 100644 --- a/mk/typedoc.config.cjs +++ b/mk/typedoc.config.cjs @@ -8,4 +8,5 @@ module.exports = { readme: "./typedoc-README.md", customFooterHtml: ``, customFooterHtmlDisableWrapper: true, + // comments/validation-related options should be written in make-pkg-tsconfig script }; diff --git a/package.json b/package.json index f9948d2f..92a8e0a3 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "@yoursunny/xo-config": "0.58.0", "codedown": "^3.1.0", "tslib": "^2.6.3", - "typedoc": "^0.26.2", + "typedoc": "^0.26.3", "typescript": "~5.5.2", "vitest": "^1.6.0" }, diff --git a/pkg/endpoint/src/common.ts b/pkg/endpoint/src/common.ts new file mode 100644 index 00000000..b787f5e9 --- /dev/null +++ b/pkg/endpoint/src/common.ts @@ -0,0 +1,36 @@ +import type { Forwarder } from "@ndn/fw"; + +export interface CommonOptions { + /** + * Logical forwarder instance. + * @defaultValue `Forwarder.getDefault()` + */ + fw?: Forwarder; + + /** + * Description for debugging purpose. + * @defaultValue + * In a consumer, "consume" + Interest name. + * In a producer, "produce" + main prefix. + */ + describe?: string; + + /** + * AbortSignal that allows cancelation via AbortController. + * + * @remarks + * In a consumer, the promise returned by consume() is rejected. + * In a producer, the producer is closed. + */ + signal?: AbortSignal; +} + +const commonKeys: readonly string[] = [ + "fw", "describe", "signal", +] satisfies ReadonlyArray; + +export function exactOptions(opts: O, keys: ReadonlyArray): O { + return Object.fromEntries(Object.entries(opts).filter( + ([key]) => commonKeys.includes(key) || (keys as readonly string[]).includes(key)), + ) as O; +} diff --git a/pkg/endpoint/src/consumer.ts b/pkg/endpoint/src/consumer.ts index 02775e35..c59e9014 100644 --- a/pkg/endpoint/src/consumer.ts +++ b/pkg/endpoint/src/consumer.ts @@ -2,26 +2,11 @@ import { CancelInterest, Forwarder, FwPacket } from "@ndn/fw"; import { Data, Interest, type NameLike, type Verifier } from "@ndn/packet"; import { pushable } from "@ndn/util"; +import { type CommonOptions, exactOptions } from "./common"; import { makeRetxGenerator, type RetxPolicy } from "./retx"; /** {@link consume} options. */ -export interface ConsumerOptions { - /** - * Logical forwarder instance. - * @defaultValue `Forwarder.getDefault()` - */ - fw?: Forwarder; - - /** - * Description for debugging purpose. - * @defaultValue - * "consume" + Interest name. - */ - describe?: string; - - /** AbortSignal that allows canceling the Interest via AbortController. */ - signal?: AbortSignal; - +export interface ConsumerOptions extends CommonOptions { /** * Modify Interest according to specified options. * @defaultValue @@ -44,12 +29,8 @@ export interface ConsumerOptions { verifier?: Verifier; } export namespace ConsumerOptions { - const keys: readonly string[] = [ - "fw", "describe", "signal", "modifyInterest", "retx", "verifier", - ] satisfies ReadonlyArray; - export function exact(opts: ConsumerOptions = {}): ConsumerOptions { - return Object.fromEntries(Object.entries(opts).filter(([key]) => keys.includes(key))); + return exactOptions(opts, ["modifyInterest", "retx", "verifier"]); } } diff --git a/pkg/endpoint/src/producer.ts b/pkg/endpoint/src/producer.ts index f991248f..5abec2ce 100644 --- a/pkg/endpoint/src/producer.ts +++ b/pkg/endpoint/src/producer.ts @@ -2,6 +2,7 @@ import { Forwarder, type FwFace, FwPacket } from "@ndn/fw"; import { Data, Interest, Name, type NameLike, Signer } from "@ndn/packet"; import { flatTransform } from "streaming-iterables"; +import { type CommonOptions, exactOptions } from "./common"; import type { DataBuffer } from "./data-buffer"; /** @@ -21,23 +22,7 @@ import type { DataBuffer } from "./data-buffer"; export type ProducerHandler = (interest: Interest, producer: Producer) => Promise; /** {@link produce} options. */ -export interface ProducerOptions { - /** - * Logical forwarder instance. - * @defaultValue `Forwarder.getDefault()` - */ - fw?: Forwarder; - - /** - * Description for debugging purpose. - * @defaultValue - * "produce" + prefix. - */ - describe?: string; - - /** AbortSignal that allows closing the producer via AbortController. */ - signal?: AbortSignal; - +export interface ProducerOptions extends CommonOptions { /** * Whether routes registered by producer would cause `@ndn/fw` internal FIB to stop matching * toward shorter prefixes. @@ -107,13 +92,8 @@ export namespace ProducerOptions { /** Describe how to derive route announcement from name prefix in {@link produce}. */ export type RouteAnnouncement = FwFace.RouteAnnouncement; - const keys: readonly string[] = [ - "fw", "describe", "signal", "routeCapture", "announcement", - "concurrency", "dataSigner", "dataBuffer", "autoBuffer", - ] satisfies ReadonlyArray; - export function exact(opts: ProducerOptions = {}): ProducerOptions { - return Object.fromEntries(Object.entries(opts).filter(([key]) => keys.includes(key))); + return exactOptions(opts, ["routeCapture", "announcement", "concurrency", "dataSigner", "dataBuffer", "autoBuffer"]); } } @@ -182,7 +162,7 @@ class ProducerImpl implements Producer { this.processInterest = this.dataBuffer ? this.processBuffered.bind(this, autoBuffer) : - this.processUnbuffered.bind(this); + this.processUnbuffered; signal?.addEventListener("abort", this.close); } @@ -203,7 +183,7 @@ class ProducerImpl implements Producer { public readonly processInterest: (interest: Interest) => Promise; - private async processUnbuffered(interest: Interest): Promise { + private processUnbuffered = async (interest: Interest): Promise => { const data = await this.handler(interest, this); if (!(data instanceof Data)) { return undefined; @@ -214,7 +194,7 @@ class ProducerImpl implements Producer { return undefined; } return data; - } + }; private async processBuffered(autoBuffer: boolean, interest: Interest): Promise { let found = await this.dataBuffer!.find(interest); diff --git a/pkg/nac/README.md b/pkg/nac/README.md index 819643db..e982d81b 100644 --- a/pkg/nac/README.md +++ b/pkg/nac/README.md @@ -3,4 +3,4 @@ This package is part of [NDNts](https://yoursunny.com/p/NDNts/), Named Data Networking libraries for the modern web. This package implements [NAC-RSA](https://github.com/named-data/name-based-access-control) named based access control protocol, as introduced in [NAC: Automating Access Control via Named Data](https://named-data.net/publications/zhang2018nac/) section 3. -This implementation is validated against the reference implementation using [nac-interop](../../integ/nac-interop/README.md). +This implementation is validated against the reference implementation using [nac-interop](../../integ/nac-interop). diff --git a/pkg/ndncert/README.md b/pkg/ndncert/README.md index a18d0561..cd29bd1e 100644 --- a/pkg/ndncert/README.md +++ b/pkg/ndncert/README.md @@ -3,7 +3,7 @@ This package is part of [NDNts](https://yoursunny.com/p/NDNts/), Named Data Networking libraries for the modern web. This package partially implements [NDN Certificate Management protocol v0.3](https://github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3/841f2a2e66cc3256d113cfe61242420b9cdab6c1) and [challenges](https://github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3-Challenges/46700d99c67dc94d13d26f838e4594f1f66d7c76). -This implementation is validated against the reference implementation using [ndncert-interop](../../integ/ndncert-interop/README.md). +This implementation is validated against the reference implementation using [ndncert-interop](../../integ/ndncert-interop). Features: diff --git a/pkg/nfdmgmt/README.md b/pkg/nfdmgmt/README.md index 17019b98..4bddd51f 100644 --- a/pkg/nfdmgmt/README.md +++ b/pkg/nfdmgmt/README.md @@ -13,7 +13,7 @@ It includes both a generic variant and a NFD-specific variant with additional ty * [X] NFD: `FaceDataset`, `FaceQuery`, `CsInfo`, `StrategyChoice`, `RibEntry` * [ ] NotificationStream -This implementation is validated against NFD using [nfdmgmt-interop](../../integ/nfdmgmt-interop/README.md). +This implementation is validated against NFD using [nfdmgmt-interop](../../integ/nfdmgmt-interop). ```ts import { enableNfdPrefixReg } from "@ndn/nfdmgmt"; diff --git a/pkg/psync/README.md b/pkg/psync/README.md index f2e65f87..3ae25fc3 100644 --- a/pkg/psync/README.md +++ b/pkg/psync/README.md @@ -15,7 +15,7 @@ This package contains **PSync** and related protocols, including: These implementations are parameterized. Certain algorithm settings (e.g. hashtable size) and encoding details (e.g. endianness) are extracted from the core logic and put into `Parameters` structures. -Each protocol has at least a set of *compat* parameters that is consistent with the reference implementation, validated in [sync-interop](../../integ/sync-interop/README.md). +Each protocol has at least a set of *compat* parameters that is consistent with the reference implementation, validated in [sync-interop](../../integ/sync-interop). In the future, there would be alternative parameter sets optimized for the modern web (e.g. smaller code bundle size), but incompatible with the reference implementation. NOTICE: diff --git a/pkg/svs/README.md b/pkg/svs/README.md index a1d50b3c..dae43632 100644 --- a/pkg/svs/README.md +++ b/pkg/svs/README.md @@ -10,7 +10,7 @@ This package contains **StateVectorSync** and related protocols, including: * [SVS-PS](https://named-data.github.io/StateVectorSync/PubSubSpec.html), revision 2023-05-19 * simple unit test -Compatibility with the reference implementation is validated in [sync-interop](../../integ/sync-interop/README.md). +Compatibility with the reference implementation is validated in [sync-interop](../../integ/sync-interop). [SVS v2](https://github.com/named-data/StateVectorSync/pull/14) is being implemented: