ReadonlyCatalog

CORE · interface · Type contract

Read-only projection of a definition set; the implementation owns ordering and validation.

Import

TypeScript

import type { ReadonlyCatalog } from '@jangts/agent-core';

JavaScript

/** @typedef {import('@jangts/agent-core').ReadonlyCatalog} ReadonlyCatalog */

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs.

Definition

interface ReadonlyCatalog<Definition>

Type parameters

Type parameter	Constraint	Default type
Definition	{ readonly id: string }	—

Field structure

Field	Type	Required	Description
definitions	readonly Readonly<Definition>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<Definition>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<Definition>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<Definition> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Definition>	Required	Returns the definition or throws; use when the id is a required reference.

Member index

Member	Purpose
ids	Ids in the same order as definitions.
values	See the overload below for full inputs and outputs.
entries	See the overload below for full inputs and outputs.
has	See the overload below for full inputs and outputs.
get	Returns the definition or undefined; the caller decides whether absence is an error.
require	Returns the definition or throws; use when the id is a required reference.

Member details

ids

Ids in the same order as definitions.

ReadonlyCatalog.ids(): readonly string[]

Ids in the same order as definitions.

No call parameters.

Returns: readonly string[].

values

ReadonlyCatalog.values(): IterableIterator<Readonly<Definition>>

No call parameters.

Returns: IterableIterator<Readonly<Definition>>.

entries

ReadonlyCatalog.entries(): IterableIterator<readonly [string, Readonly<Definition>]>

No call parameters.

Returns: IterableIterator<readonly [string, Readonly<Definition>]>.

has

ReadonlyCatalog.has(id: string): boolean

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

get

Returns the definition or undefined; the caller decides whether absence is an error.

ReadonlyCatalog.get(id: string): Readonly<Definition> | undefined

Returns the definition or undefined; the caller decides whether absence is an error.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Definition> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	Definition["id"]	Required	Read-only. See the type definition and usage context.

require

Returns the definition or throws; use when the id is a required reference.

ReadonlyCatalog.require(id: string): Readonly<Definition>

Returns the definition or throws; use when the id is a required reference.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Definition>.

Return value structure

Field	Type	Required	Description
id	Definition["id"]	Required	Read-only. See the type definition and usage context.

Examples

• Tool module composition and declarative installation: List modules, tool references, and registration order in one place; the generic loop consumes only that actual list.

Reuse existing module declarations directly

Beginner · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const modules = [{ id: 'service', description: '服务查询能力', tools: [{ id: 'get_status' }] }];
const catalog = Support.defineCapabilityCatalog(modules);
console.log(catalog.ids(), catalog.findToolOwner('get_status')?.id);

JavaScript

import { Support } from '@jangts/agent-core';
const modules = [{ id: 'service', description: '服务查询能力', tools: [{ id: 'get_status' }] }];
const catalog = Support.defineCapabilityCatalog(modules);
console.log(catalog.ids(), catalog.findToolOwner('get_status')?.id);

Add tool references and ordered installation

Configuration · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const modules = [{ id: 'service', description: '服务查询', tools: [{ id: 'get_status' }],
  references: [{ id: 'status-skill', requiredToolIds: ['get_status'], optionalToolIds: [] }] }];
const moduleCatalog = Support.defineCapabilityCatalog(modules, { toolReferences: module => module.references });
const registration = Support.defineRegistrationCatalog<{ installed: string[] }>([
  { id: 'service', register: app => { app.installed.push(moduleCatalog.require('service').id); } },
  { id: 'status-view', when: app => app.installed.includes('service'), register: app => { app.installed.push('status-view'); } },
]);
const app = { installed: [] as string[] };
registration.install(app);
console.log(app.installed);

JavaScript

import { Support } from '@jangts/agent-core';
const modules = [{ id: 'service', description: '服务查询', tools: [{ id: 'get_status' }],
        references: [{ id: 'status-skill', requiredToolIds: ['get_status'], optionalToolIds: [] }] }];
const moduleCatalog = Support.defineCapabilityCatalog(modules, { toolReferences: module => module.references });
const registration = Support.defineRegistrationCatalog([
    { id: 'service', register: app => { app.installed.push(moduleCatalog.require('service').id); } },
    { id: 'status-view', when: app => app.installed.includes('service'), register: app => { app.installed.push('status-view'); } },
]);
const app = { installed: [] };
registration.install(app);
console.log(app.installed);

Related policy source

• Reference checks and same-source tool module composition
• Owner-to-tool relationship projection