IF Commons GitHub

governance/annotation

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-governance FR-007

Annotations (commons data 0003-governance FR-007): a typed value of a kind that a vocabulary defines, on an element. A kind is made by annotationKind<T>(name, about) and says which kinds of element it may be on; annotate(kind, value) types the value by it, so that a value of another type does not compile; annotationsOf reads them back, typed. The kinds are open: a vocabulary an extension adds defines more, and nothing here knows them.

const synonym = annotationKind<string>("docs.synonym", ["concept", "attribute"]);
annotate(synonym, "client");

Source: commons/data/governance/annotation.ts

4 of 7 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Annotatedinterfaceno test imports it
interface Annotated

Whatever carries annotations: every element.

MemberTypeWhat it is
annotationsreadonly Annotation[]
Annotationinterface
interface Annotation

An annotation on an element: its kind, where that kind may be, and its value.

MemberTypeWhat it is
kind`${string}.${string}`
aboutreadonly ElementKind[]
valueunknown

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

AnnotationKindinterfaceno test imports it
interface AnnotationKind<T>

A kind of annotation: its name, the kinds of element it may be on, and (for the compiler only) the type of its value.

MemberTypeWhat it is
name`${string}.${string}`
aboutreadonly ElementKind[]
__value?TNever set: carries the type of the value, for the compiler.
AnnotationNametypeno test imports it
type AnnotationName = `${string}.${string}`;

The name of an annotation kind: a vocabulary, a dot and a name (privacy.personal).

annotatefunction
function annotate<T>(kind: AnnotationKind<T>, value: T): Annotation

Annotates, typed by the kind: a value of another type does not compile.

ParameterWhat it is
kindthe kind
valueits value

Returns: the annotation, frozen

Imported by 123 tests of the run (123 passed, 0 failed): the library's results

annotationKindfunction
function annotationKind<T>(name: `${string}.${string}`, about: readonly ElementKind[]): AnnotationKind<T>

Declares a kind of annotation.

ParameterWhat it is
namethe vocabulary and the name, such as security.classification
aboutthe kinds of element it may be on

Returns: the kind, frozen

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

annotationsOffunction
function annotationsOf<T>(element: Annotated, kind: AnnotationKind<T>): readonly T[]

The values of the annotations of a kind on an element, typed.

ParameterWhat it is
elementthe element
kindthe kind

Returns: the values, in the order they were written

Imported by 25 tests of the run (25 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.