Artifacts

KIT · constant · Runtime value

Import

TypeScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';

JavaScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';

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

Definition

Member index

Member	Purpose
defineArtifactCatalog	See the overload below for full inputs and outputs.

Member details

defineArtifactCatalog

Artifacts.defineArtifactCatalog<Value, App>(definitions: readonly ArtifactResolver<Value, App>[]): Readonly<{ resolve: (reference: ArtifactReference, context: OperationContext<App>) => Promise<Value>; definitions: readonly Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>[]; ids(): readonly string[]; values(): IterableIterator<Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>>; entries(): IterableIterator<readonly [string, Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>]>; has(id: string): boolean; get(id: string): Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }> | undefined; require(id: string): Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>; }>

Compile a catalog of artifact resolvers plus a checked resolve entry point.

Type parameter	Constraint	Default type
Value	—	—
App	—	—

Parameter	Type	Passing	Description
definitions	readonly ArtifactResolver<Value, App>[]	Required	—

Returns: Readonly<{ resolve: (reference: ArtifactReference, context: OperationContext<App>) => Promise<Value>; definitions: readonly Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>[]; ids(): readonly string[]; values(): IterableIterator<Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>>; entries(): IterableIterator<readonly [string, Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>]>; has(id: string): boolean; get(id: string): Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }> \| undefined; require(id: string): Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>; }>.

Return value structure

Field	Type	Required	Description
resolve	(reference: ArtifactReference, context: OperationContext<App>) => Promise<Value>	Required	See the type definition and usage context.
definitions	readonly Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>[]	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<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<{ id: string; resolve: (reference: ArtifactReference, context: OperationContext<App>) => MaybePromise<Value>; }>	Required	Returns the definition or throws; use when the id is a required reference.

Examples

• Artifacts: resolve real artifacts by reference: A reference contains only resolverId, artifactId, and an optional revision; the App resolver provides the real content.

First resolve one explicit in-memory artifact

Beginner · Node.js

TypeScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
const content = new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]);
const artifacts = Artifacts.defineArtifactCatalog([
  { id: 'document', resolve(reference) { const value = content.get(reference.artifactId); if (!value) throw new Error('产物不存在'); return value; } },
]);
const result = await artifacts.resolve({ resolverId: 'document', artifactId: 'manual' }, { app: {}, signal: new AbortController().signal });
console.log(result.text);

JavaScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
const content = new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]);
const artifacts = Artifacts.defineArtifactCatalog([
    { id: 'document', resolve(reference) { const value = content.get(reference.artifactId); if (!value)
            throw new Error('产物不存在'); return value; } },
]);
const result = await artifacts.resolve({ resolverId: 'document', artifactId: 'manual' }, { app: {}, signal: new AbortController().signal });
console.log(result.text);

Add real permission and revision verification to the same resolve

Configuration · Node.js

TypeScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
type Value = { text: string; revision: string };
type App = { canRead: boolean; documents: Map<string, Value> };
const artifacts = Artifacts.defineArtifactCatalog<Value, App>([
  { id: 'document', async resolve(reference, { app, signal }) {
    signal.throwIfAborted();
    if (!app.canRead) throw new Error('没有产物读取权限');
    const value = app.documents.get(reference.artifactId);
    if (!value) throw new Error('产物不存在或已到期');
    if (reference.revision && reference.revision !== value.revision) throw new Error('产物版本已变化');
    return structuredClone(value);
  } },
]);
const app = { canRead: true, documents: new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]) };
console.log(await artifacts.resolve({ resolverId: 'document', artifactId: 'manual', revision: '1' }, { app, signal: new AbortController().signal }));

JavaScript

import { Artifacts } from '@jangts/agent-core/kits/artifacts';
const artifacts = Artifacts.defineArtifactCatalog([
    { id: 'document', async resolve(reference, { app, signal }) {
            signal.throwIfAborted();
            if (!app.canRead)
                throw new Error('没有产物读取权限');
            const value = app.documents.get(reference.artifactId);
            if (!value)
                throw new Error('产物不存在或已到期');
            if (reference.revision && reference.revision !== value.revision)
                throw new Error('产物版本已变化');
            return structuredClone(value);
        } },
]);
const app = { canRead: true, documents: new Map([['manual', { text: 'Agent Core 使用说明', revision: '1' }]]) };
console.log(await artifacts.resolve({ resolverId: 'document', artifactId: 'manual', revision: '1' }, { app, signal: new AbortController().signal }));

Related policy source

• Reference snapshot, resolver registration, and cancellation

Related definitions

• ArtifactResolver
• defineArtifactCatalog