API reference

See the generated Forage API reference. It covers Forage.createCatalog, the createCatalog function, operation definitions, and the search and description result types.

Classes

ForageError

A bounded, machine-readable failure at a Forage public seam.

Extends

• Error

Constructors

Constructor

new ForageError(code, message, options?): ForageError

Parameters

code

"empty_query" | "empty_catalog" | "unknown_target" | "duplicate_operation" | "invalid_input"

message

string

options?

ErrorOptions

Returns

ForageError

Overrides

Error.constructor

Properties

code

readonly code: "empty_query" | "empty_catalog" | "unknown_target" | "duplicate_operation" | "invalid_input"

failure

readonly failure: object

code

code: "empty_query" | "empty_catalog" | "unknown_target" | "duplicate_operation" | "invalid_input"

message

message: string

Type Aliases

ForageCatalog

ForageCatalog = Readonly<{ revision: string; search: (rawInput) => SearchOutput; describe: (rawInput) => DescribeOutput; list: (rawInput) => ListOutput; stamp: () => string; }>

Immutable public facade for one prepared catalog revision.

---

ForageDefinition

ForageDefinition = Readonly<{ replay: "safe"; path: string; description: string; input: typeof forageSearchInput | typeof forageDescribeInput | typeof forageListInput; output: typeof searchOutputSchema | typeof describeOutputSchema | typeof listOutputSchema; }>

Structural operation definition consumed by a capability composer.

---

ForageApi

ForageApi = object

Public convenience namespace contract.

Properties

createCatalog

createCatalog: typeof createCatalog

Construct one immutable catalog revision.

forageSearchDefinition

forageSearchDefinition: typeof forageSearchDefinition

Structural search operation definition.

forageDescribeDefinition

forageDescribeDefinition: typeof forageDescribeDefinition

Structural description operation definition.

forageListDefinition

forageListDefinition: typeof forageListDefinition

Structural exhaustive listing definition.

---

ForageSearchInput

ForageSearchInput = z.input<typeof forageSearchInput>>

Parsed search request type.

---

ForageListInput

ForageListInput = z.input<typeof forageListInput>>

Exhaustive listing request type.

---

ListOutput

ListOutput = z.infer<typeof listOutputSchema>>

Exhaustive page response type.

---

ForageDescribeInput

ForageDescribeInput = z.input<typeof forageDescribeInput>>

Parsed description request type.

---

SearchResult

SearchResult = z.infer<typeof searchResultSchema>>

One ranked search result type.

---

SearchOutput

SearchOutput = z.infer<typeof searchOutputSchema>>

Search response envelope type.

---

DescribeOutput

DescribeOutput = z.infer<typeof describeOutputSchema>>

Description response type.

---

ForageFailure

ForageFailure = z.infer<typeof forageFailureSchema>>

Typed failure value type.

---

Operation

Operation = z.infer<typeof operationSchema>>

Catalog operation descriptor type.

---

CatalogInput

CatalogInput = z.input<typeof catalogInputSchema>>

Catalog construction input type.

Variables

forageSearchDefinition

const forageSearchDefinition: ForageDefinition

The search operation has schema metadata only; it has no host behavior.

---

forageDescribeDefinition

const forageDescribeDefinition: ForageDefinition

The description operation has schema metadata only; it has no host behavior.

---

forageListDefinition

const forageListDefinition: ForageDefinition

Pure exhaustive catalog listing; no execution or authority is granted.

---

Forage

const Forage: ForageApi

Narrow convenience namespace for the package’s public seams.

---

forageSearchInput

const forageSearchInput: ZodObject<{ query: ZodString; maxResults: ZodDefault<ZodNumber>>; }, $strip>>

Input accepted by the pure catalog search seam.

---

forageDescribeInput

const forageDescribeInput: ZodObject<{ path: ZodString; detail: ZodDefault<ZodEnum<{ index: "index"; full: "full"; }>>; methods: ZodOptional<ZodArray<ZodString>>>>; }, $strip>>

Input accepted by the pure catalog description seam.

---

forageListInput

const forageListInput: ZodObject<{ cursor: ZodOptional<ZodString>>; limit: ZodDefault<ZodNumber>>; namespace: ZodOptional<ZodString>>; }, $strip>>

Exhaustive listing request; cursor is scoped to one immutable catalog and filter.

---

searchResultSchema

const searchResultSchema: ZodObject<{ path: ZodString; description: ZodOptional<ZodString>>; score: ZodNumber; matchReason: ZodOptional<ZodString>>; sample: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>>>; capabilityNotes: ZodOptional<ZodString>>; peers: ZodOptional<ZodArray<ZodObject<{ path: ZodString; capabilityNotes: ZodOptional<ZodString>>; }, $strip>>>>>>; }, $strip>>

One ranked operation in a search response.

---

searchOutputSchema

const searchOutputSchema: ZodObject<{ results: ZodArray<ZodObject<{ path: ZodString; description: ZodOptional<ZodString>>; score: ZodNumber; matchReason: ZodOptional<ZodString>>; sample: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>>>; capabilityNotes: ZodOptional<ZodString>>; peers: ZodOptional<ZodArray<ZodObject<{ path: ZodString; capabilityNotes: ZodOptional<ZodString>>; }, $strip>>>>>>; }, $strip>>>>; total: ZodNumber; truncated: ZodBoolean; topScore: ZodNumber; margin: ZodNumber; catalogStamp: ZodString; }, $strip>>

Bounded search response envelope.

---

listOutputSchema

const listOutputSchema: ZodObject<{ results: ZodArray<ZodObject<{ path: ZodString; description: ZodOptional<ZodString>>; score: ZodNumber; matchReason: ZodOptional<ZodString>>; sample: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>>>; capabilityNotes: ZodOptional<ZodString>>; peers: ZodOptional<ZodArray<ZodObject<{ path: ZodString; capabilityNotes: ZodOptional<ZodString>>; }, $strip>>>>>>; }, $strip>>>>; total: ZodNumber; nextCursor: ZodNullable<ZodString>>; catalogStamp: ZodString; }, $strip>>

One exhaustive page, using the exact search operation summary schema.

---

describeOutputSchema

const describeOutputSchema: ZodObject<{ path: ZodString; description: ZodOptional<ZodString>>; types: ZodString; kind: ZodEnum<{ module: "module"; operation: "operation"; }>; usage: ZodOptional<ZodString>>; }, $strip>>

Deterministic description response.

---

forageFailureSchema

const forageFailureSchema: ZodObject<{ code: ZodEnum<{ empty_query: "empty_query"; empty_catalog: "empty_catalog"; unknown_target: "unknown_target"; duplicate_operation: "duplicate_operation"; invalid_input: "invalid_input"; }>; message: ZodString; }, $strip>>

Closed failure vocabulary for malformed or absent catalog requests.

---

operationSchema

const operationSchema: ZodObject<{ path: ZodString; description: ZodOptional<ZodString>>; input: ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>>; output: ZodOptional<ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>>>>; capabilityNotes: ZodOptional<ZodString>>; instructions: ZodOptional<ZodString>>; }, $strip>>

A secret-free, callback-free operation descriptor.

---

catalogInputSchema

const catalogInputSchema: ZodObject<{ revision: ZodString; operations: ZodArray<ZodObject<{ path: ZodString; description: ZodOptional<ZodString>>; input: ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>>; output: ZodOptional<ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>>>>; capabilityNotes: ZodOptional<ZodString>>; instructions: ZodOptional<ZodString>>; }, $strip>>>>; }, $strip>>

Input used to construct one immutable catalog revision.

Functions

createCatalog()

createCatalog(input): ForageCatalog

Construct one immutable catalog revision with a narrow public facade.

Parameters

input

revision

string = ...

operations

object[] = ...

Returns

ForageCatalog

---

listOperations()

listOperations(operations, catalogStamp, rawInput): object

Page a trusted immutable operation-summary view. Hosts may filter the existing catalog to their bound operations before paging; this is the one cursor owner. Order is namespace then full path, compared by UTF-16 code units, never locale. Unlike search, no equivalent operations are merged into peers.

Parameters

operations

readonly object[]

catalogStamp

string

rawInput

cursor?

string = ...

limit?

number = ...

namespace?

string = ...

Returns

object

results

results: object[]

total

total: number

nextCursor

nextCursor: string | null

catalogStamp

catalogStamp: string

References

default

Renames and re-exports Forage