defineCandidateSelection

KIT · function · Runtime value

Compile an alternative-proposal envelope contract.

Alternative proposals are bounded and shallow; accepting a task closes this capability. A value that is not an object, or that does not carry the candidate field, is treated as a single implicit candidate and returned as-is. Once the envelope is present it must contain only that field, and its array must hold between minCandidates (default 1) and maxCandidates distinct candidate objects that do not themselves repeat the field.

Import

TypeScript

import { defineCandidateSelection } from '@jangts/agent-core/kits/candidates';

JavaScript

import { defineCandidateSelection } from '@jangts/agent-core/kits/candidates';

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

Definition

Call

defineCandidateSelection(definition: CandidateSelectionDefinition): Readonly<{ field: string; minCandidates: number; maxCandidates: number; parse: ({ value, allowed }: { value: unknown; allowed: boolean; }) => unknown[]; }>

Compile an alternative-proposal envelope contract.

Alternative proposals are bounded and shallow; accepting a task closes this capability. A value that is not an object, or that does not carry the candidate field, is treated as a single implicit candidate and returned as-is. Once the envelope is present it must contain only that field, and its array must hold between minCandidates (default 1) and maxCandidates distinct candidate objects that do not themselves repeat the field.

Parameter	Type	Passing	Description
definition	CandidateSelectionDefinition	Required	—

Fields of definition

Field	Type	Required	Description
field	string	Required	Read-only. Reply field that carries the alternatives.
minCandidates	number | undefined	Optional	Read-only. Minimum number of distinct candidates once the envelope is present; defaults to 1.
maxCandidates	number	Required	Read-only. Maximum number of candidates; must be a safe integer not below the minimum.
error	BreakReason | undefined	Optional	Read-only. Rejection wording, either fixed, a pre-built error or a lazy factory.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to every rejection from this contract.

Returns: Readonly<{ field: string; minCandidates: number; maxCandidates: number; parse: ({ value, allowed }: { value: unknown; allowed: boolean; }) => unknown[]; }>.

Return value structure

Field	Type	Required	Description
field	string	Required	See the type definition and usage context.
minCandidates	number	Required	See the type definition and usage context.
maxCandidates	number	Required	See the type definition and usage context.
parse	({ value, allowed }: { value: unknown; allowed: boolean; }) => unknown[]	Required	See the type definition and usage context.

Examples

• Candidates: a bounded candidate envelope: The same result can be a single proposal or a candidate list; candidate permission and count are controlled by the application.

Accept a single proposal or up to three candidates

Beginner · Node.js

TypeScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', maxCandidates: 3 });
console.log(selection.parse({ value: { action: 'read' }, allowed: true }));
console.log(selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: true }));

JavaScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', maxCandidates: 3 });
console.log(selection.parse({ value: { action: 'read' }, allowed: true }));
console.log(selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: true }));

Add a lower bound and an application-stage constraint to the same parse

Configuration · Node.js

TypeScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', minCandidates: 2, maxCandidates: 3, error: '当前阶段不接受这份候选' });
const taskAccepted = true;
try {
  selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: !taskAccepted });
} catch (error) { console.log((error as Error).message); }

JavaScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', minCandidates: 2, maxCandidates: 3, error: '当前阶段不接受这份候选' });
const taskAccepted = true;
try {
    selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: !taskAccepted });
}
catch (error) {
    console.log(error.message);
}

Related policy source

• Candidate envelope, count, and shallow constraints

Related definitions

• CandidateSelectionDefinition