linked-rolls 0.70.0 → 0.71.0

package/lib/model/Quantity.js

@@ -1,42 +1,146 @@
-/** Names a number in a unit. Partially apply it to make a constructor. */
+/**
+ * Names a number in a unit. Partially apply it to make a constructor.
+ * @category Units
+ */
 export const quantity = (value) => value;
+/**
+ * Names a number in millimetres.
+ * @category Units
+ */
 export const mm = quantity;
+/**
+ * Names a number in centimetres.
+ * @category Units
+ */
 export const cm = quantity;
+/**
+ * Names a number in pixels of a scan.
+ * @category Units
+ */
 export const px = quantity;
+/**
+ * Names a number as a position across the roll, as the tracker bar
+ * numbers it.
+ * @category Units
+ */
 export const track = quantity;
+/**
+ * Names a number in seconds.
+ * @category Units
+ */
 export const seconds = quantity;
+/**
+ * Names a number in milliseconds.
+ * @category Units
+ */
 export const milliseconds = quantity;
+/**
+ * Names a number as a paper speed in feet per minute.
+ * @category Units
+ */
 export const feetPerMinute = quantity;
+/**
+ * Names a number as a paper speed in metres per minute.
+ * @category Units
+ */
 export const metersPerMinute = quantity;
+/**
+ * Names a number as the resolution of a scan, in pixels per inch.
+ * @category Units
+ */
 export const pixelsPerInch = quantity;
+/**
+ * Names a number as an angle in degrees.
+ * @category Units
+ */
 export const degrees = quantity;
+/**
+ * Names a number as a share in per cent.
+ * @category Units
+ */
 export const percent = quantity;
 // The second operand takes its unit from the first. Inferred from both,
 // TypeScript would unite two units rather than reject them.
+/**
+ * The sum of two quantities in one unit.
+ * @internal
+ */
 export const add = (a, b) => quantity(a + b);
+/**
+ * The first quantity less the second, in their unit.
+ * @internal
+ */
 export const subtract = (a, b) => quantity(a - b);
+/**
+ * How far apart two quantities in one unit lie, whichever is the
+ * larger.
+ * @internal
+ */
 export const distance = (a, b) => quantity(Math.abs(a - b));
-/** A quantity times a plain factor, such as a stretch. */
+/**
+ * A quantity times a plain factor, such as a stretch.
+ * @internal
+ */
 export const scale = (a, factor) => quantity(a * factor);
 // Math.min and Math.max are declared over plain numbers, so a quantity
 // passed through them comes back without its unit.
+/**
+ * The smaller of two quantities in one unit.
+ * @internal
+ */
 export const min = (a, b) => quantity(Math.min(a, b));
+/**
+ * The larger of two quantities in one unit.
+ * @internal
+ */
 export const max = (a, b) => quantity(Math.max(a, b));
-/** The value brought inside the bounds, which must not be the wrong way round. */
+/**
+ * The value brought inside the bounds, which must not be the wrong way round.
+ * @internal
+ */
 export const clamp = (value, low, high) => quantity(Math.min(high, Math.max(low, value)));
 // A list is taken at its element type, so one that mixes units yields a
 // union unit rather than an error; only the binary operations reject a mix.
+/**
+ * The quantities added up, zero where there are none.
+ * @internal
+ */
 export const sum = (values) => quantity(values.reduce((total, value) => total + value, 0));
+/**
+ * The mean of the quantities.
+ * @internal
+ */
 export const mean = (values) => quantity(sum(values) / values.length);
 const MM_PER_INCH = 25.4;
-/** A place in a scan taken at `dpi` dots per inch, on the paper. */
+/**
+ * A place in a scan taken at `dpi` dots per inch, on the paper.
+ * @internal
+ */
 export const inMillimeters = (place, dpi) => mm(place / dpi * MM_PER_INCH);
-/** A place on the paper, in a scan taken at `dpi` dots per inch. */
+/**
+ * A place on the paper, in a scan taken at `dpi` dots per inch.
+ * @internal
+ */
 export const inPixels = (place, dpi) => px(place / MM_PER_INCH * dpi);
+/**
+ * A length in millimetres, in centimetres.
+ * @internal
+ */
 export const inCentimeters = (length) => cm(length / 10);
 const MS_PER_SECOND = 1000;
+/**
+ * A time in milliseconds, in seconds.
+ * @internal
+ */
 export const inSeconds = (time) => seconds(time / MS_PER_SECOND);
+/**
+ * A time in seconds, in milliseconds.
+ * @internal
+ */
 export const inMilliseconds = (time) => milliseconds(time * MS_PER_SECOND);
 const METERS_PER_FOOT = 0.3048;
-/** A speed in metres per minute, whichever unit it was stated in. */
+/**
+ * A speed in metres per minute, whichever unit it was stated in.
+ * @category Units
+ */
 export const inMetersPerMinute = (speed) => speed.unit === 'm/min' ? speed.value : metersPerMinute(speed.value * METERS_PER_FOOT);

package/lib/model/RollCopy.d.ts

@@ -17,6 +17,7 @@ import { Perforator } from "./Perforator.js";
  * tenths of one. It is taken in one direction, along the roll or across
  * it, since machine-made paper does not stretch the same way in both.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface Strain extends Measure<'percent'> {
     /**
@@ -35,6 +36,7 @@ export interface Strain extends Measure<'percent'> {
  * stated here, so that a condition stands only where something was
  * measured. A strain along the roll goes into that working out.
  * @see crm:E3 Condition State
+ * @category Format types
  */
 export interface PaperStretch extends ConditionState<'paper-stretch'> {
     /**
@@ -53,6 +55,7 @@ export interface PaperStretch extends ConditionState<'paper-stretch'> {
  * A general condition description for a roll copy, e.g.
  * overall wear, discoloration, or other observations.
  * @see crm:E3 Condition State
+ * @category Format types
  */
 export interface GeneralRollCondition extends ConditionState<'general'> {
 }
@@ -63,6 +66,7 @@ export interface GeneralRollCondition extends ConditionState<'general'> {
  * that runs into a chain of holes damages the chain as well, which is
  * then stated of the chain as `partially-torn`.
  * @see crm:E3 Condition State
+ * @category Format types
  */
 export interface Tear extends ConditionState<'torn'> {
     /**
@@ -92,18 +96,25 @@ export interface Tear extends ConditionState<'torn'> {
 /**
  * An assignment of a condition (general, paper-stretch or a tear)
  * to a roll copy, annotatable with a belief about its certainty.
+ * @category Format types
  */
 export type RollConditionAssignment = ObjectAssumption<GeneralRollCondition | PaperStretch | Tear>;
 /**
  * The keeper a copy is held by, as an object assumption, so that the
  * statement can carry the belief it rests on and the reasons for it.
+ * @category Format types
  */
 export type KeeperAssignment = ObjectAssumption<Agent>;
+/**
+ * The kinds of condition a copy may be stated to be in.
+ * @category Vocabulary
+ */
 export declare const rollConditions: readonly ['general', 'paper-stretch', 'torn'];
 /**
  * How far an alignment moves a copy's places before it scales them:
  * along the roll, in the copy's own millimetres, and across it, in
  * tracks.
+ * @category Format types
  */
 export interface Shift {
     /** Along the roll. */
@@ -128,6 +139,7 @@ export interface Shift {
  * What the scale is put down to, the paper or the speed the copy was
  * cut for, is worked out from all the alignments together (`paperOf`).
  * Not exported to RDF.
+ * @category Format types
  */
 export interface Alignment {
     /**
@@ -165,6 +177,7 @@ export interface Alignment {
  * The width and length of a roll copy's paper, as they were measured on
  * it or on its scan.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface RollDimensions {
     /**
@@ -183,7 +196,10 @@ export interface RollDimensions {
      */
     unit: 'mm';
 }
-/** The margins on the treble and bass sides of the roll, in the unit the scan was measured in. */
+/**
+ * The margins on the treble and bass sides of the roll, in the unit the scan was measured in.
+ * @category Format types
+ */
 export interface Margins<U extends 'px' | 'mm'> {
     treble: Quantity<U>;
     bass: Quantity<U>;
@@ -193,6 +209,7 @@ export interface Margins<U extends 'px' | 'mm'> {
  * A paper speed, as a roll's label, its catalogue or its format
  * states it.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export type PaperSpeed = Measure<'ft/min'> | Measure<'m/min'>;
 /**
@@ -200,6 +217,7 @@ export type PaperSpeed = Measure<'ft/min'> | Measure<'m/min'>;
  * the paper used, the date, and the system and paper speed the
  * copy was cut for.
  * @see lrmoo:F32 Item Production Event
+ * @category Format types
  */
 export interface ProductionEvent {
     /**
@@ -260,8 +278,15 @@ export interface ProductionEvent {
      */
     produced?: AnyFeature[];
 }
+/**
+ * What a modification of a copy may have been for.
+ * @category Vocabulary
+ */
 export declare const modificationPurposes: readonly ['musical-improvement', 'technical-improvement', 'repair', 'labeling', 'control', 'dating', 'glossing'];
-/** What a modification of a copy was for, as far as it can be told. */
+/**
+ * What a modification of a copy was for, as far as it can be told.
+ * @category Format types
+ */
 export type ModificationPurpose = typeof modificationPurposes[number];
 /**
  * An identifiable act that changed the roll copy after it was punched.
@@ -271,6 +296,7 @@ export type ModificationPurpose = typeof modificationPurposes[number];
  * is not: drawing, writing and punching bring a feature into being and
  * are productions.
  * @see crm:E79 Part Addition, crm:E80 Part Removal, crm:E12 Production
+ * @category Format types
  */
 export type Modification = Partial<{
     /**
@@ -329,6 +355,7 @@ export type Modification = Partial<{
  * Multiple copies of the same roll may exist across different archives
  * or collections.
  * @see reo:RollCopy
+ * @category Format types
  */
 export interface RollCopy extends WithType<'RollCopy'>, WithId {
     /**
@@ -471,37 +498,69 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      */
     carries?: ReferenceAssumption[];
 }
-/** What an act brought onto the copy: what it produced or glued on, a removal nothing. */
+/**
+ * What an act brought onto the copy: what it produced or glued on, a removal nothing.
+ * @category Lookups
+ */
 export declare const featuresMadeBy: (modification: Modification) => FeatureOrPatch[];
-/** Whether the act is one that modified the copy, rather than the production that punched it. */
+/**
+ * Whether the act is one that modified the copy, rather than the production that punched it.
+ * @category Lookups
+ */
 export declare const isModification: (act: ProductionEvent | Modification) => act is Modification;
-/** Whether the act is left stating nothing: it produced, added or removed nothing. */
+/**
+ * Whether the act is left stating nothing: it produced, added or removed nothing.
+ * @category Lookups
+ */
 export declare const statesNothing: (modification: Modification) => boolean;
 /**
  * The features of the copy act by act: what the punching produced
  * first, then what each modification produced or glued on. A feature a
  * patch bears states no place of its own and is not among them;
  * `withBorneFeatures` reaches those.
+ * @category Lookups
  */
 export declare const featuresByAct: (copy: Pick<RollCopy, 'production' | 'modifications'>) => FeatureOrPatch[][];
-/** Every feature the copy states at a place of its own, whichever act made it. */
+/**
+ * Every feature the copy states at a place of its own, whichever act made it.
+ * @category Lookups
+ */
 export declare const featuresOf: (copy: Pick<RollCopy, 'production' | 'modifications'>) => FeatureOrPatch[];
-/** The programs the measurements of a copy name as having taken them, each once, as far as they name any. */
+/**
+ * The programs the measurements of a copy name as having taken them, each once, as far as they name any.
+ * @category Lookups
+ */
 export declare const measuringSoftwareOf: (copy: Pick<RollCopy, 'measurements'>) => Software[];
-/** Whether the condition is the stretch or shrinkage of the paper, as measured on the copy. */
+/**
+ * Whether the condition is the stretch or shrinkage of the paper, as measured on the copy.
+ * @category Lookups
+ */
 export declare const isPaperStretch: (condition: RollConditionAssignment) => condition is ObjectAssumption<PaperStretch>;
-/** What the copy's paper was measured to have done, where anything was measured. */
+/**
+ * What the copy's paper was measured to have done, where anything was measured.
+ * @category Lookups
+ */
 export declare const paperStretchOf: (copy: Pick<RollCopy, 'conditions'>) => ObjectAssumption<PaperStretch> | undefined;
-/** Whether the condition is a tear in the paper. */
+/**
+ * Whether the condition is a tear in the paper.
+ * @category Lookups
+ */
 export declare const isTear: (condition: RollConditionAssignment) => condition is ObjectAssumption<Tear>;
-/** The tears the copy is stated to have. */
+/**
+ * The tears the copy is stated to have.
+ * @category Lookups
+ */
 export declare const tearsOf: (copy: Pick<RollCopy, 'conditions'>) => ObjectAssumption<Tear>[];
 /**
  * The bar a copy is read by, which is the one it was cut for. A copy
  * that names no system falls back to `defaultTrackerBar`.
+ * @category Systems and emulation
  */
 export declare const barOf: (copy: Pick<RollCopy, 'production'>) => TrackerBar;
-/** The diameter of the punch the copy was cut with, where the edition holds it true or likely. */
+/**
+ * The diameter of the punch the copy was cut with, where the edition holds it true or likely.
+ * @category Lookups
+ */
 export declare const punchDiameterOf: (copy: Pick<RollCopy, 'production'>) => Millimeters | undefined;
 /**
  * Reads the features of a copy as the tracker bar would read them.
@@ -518,6 +577,7 @@ export declare const punchDiameterOf: (copy: Pick<RollCopy, 'production'>) => Mi
  * would be 318 notes nobody played. The features stay on the copy,
  * since they are really on the paper and are his calibration of his own
  * scan; it is the reading that stops.
+ * @category Sources
  */
 export declare function asSymbols(features: readonly FeatureOrPatch[], bar: TrackerBar): AnySymbol[];
 /**
@@ -525,6 +585,7 @@ export declare function asSymbols(features: readonly FeatureOrPatch[], bar: Trac
  * A non-empty result usually means the scan is calibrated wrongly. A chain
  * lying across several positions is counted against each one the bar
  * cannot read, and not at all where it reads them all.
+ * @category Sources
  */
 export declare function unreadTracks(features: readonly FeatureOrPatch[], bar: TrackerBar): Map<Track, number>;
 /**
@@ -536,5 +597,6 @@ export declare function unreadTracks(features: readonly FeatureOrPatch[], bar: T
  * were laid out with, and on the rolls measured so far it comes within
  * about a quarter of a track. It is kept for copies imported before the
  * calibration was written down; anything read since carries its own.
+ * @internal
  */
 export declare const calibrationOf: (copy: RollCopy) => TrackCalibration | undefined;

package/lib/model/RollCopy.js

@@ -2,11 +2,19 @@ import { v4 } from "uuid";
 import { defaultTrackerBar, trackerBarOf } from "../systems/index.js";
 import { assignReference, certaintyOf, isAsserted } from "./Assumption.js";
 import { px, track } from "./Quantity.js";
+/**
+ * The kinds of condition a copy may be stated to be in.
+ * @category Vocabulary
+ */
 export const rollConditions = [
     'general',
     'paper-stretch',
     'torn'
 ];
+/**
+ * What a modification of a copy may have been for.
+ * @category Vocabulary
+ */
 export const modificationPurposes = [
     'musical-improvement',
     'technical-improvement',
@@ -16,49 +24,81 @@ export const modificationPurposes = [
     'dating',
     'glossing'
 ];
-/** What an act brought onto the copy: what it produced or glued on, a removal nothing. */
+/**
+ * What an act brought onto the copy: what it produced or glued on, a removal nothing.
+ * @category Lookups
+ */
 export const featuresMadeBy = (modification) => {
     if (modification.type === 'Alteration')
         return modification.produced;
     return modification.type === 'Attachment' ? modification.added : [];
 };
-/** Whether the act is one that modified the copy, rather than the production that punched it. */
+/**
+ * Whether the act is one that modified the copy, rather than the production that punched it.
+ * @category Lookups
+ */
 export const isModification = (act) => 'type' in act;
-/** Whether the act is left stating nothing: it produced, added or removed nothing. */
+/**
+ * Whether the act is left stating nothing: it produced, added or removed nothing.
+ * @category Lookups
+ */
 export const statesNothing = (modification) => modification.type === 'Removal' ? modification.removed.length === 0 : featuresMadeBy(modification).length === 0;
 /**
  * The features of the copy act by act: what the punching produced
  * first, then what each modification produced or glued on. A feature a
  * patch bears states no place of its own and is not among them;
  * `withBorneFeatures` reaches those.
+ * @category Lookups
  */
 export const featuresByAct = (copy) => [copy.production?.produced ?? [], ...copy.modifications.map(featuresMadeBy)];
-/** Every feature the copy states at a place of its own, whichever act made it. */
+/**
+ * Every feature the copy states at a place of its own, whichever act made it.
+ * @category Lookups
+ */
 export const featuresOf = (copy) => featuresByAct(copy).flat();
 /** The measurements of a copy the edition exports, each of which can say what took it. */
 const exportedMeasurementsOf = (copy) => [copy.measurements.dimensions, copy.measurements.holeSeparation, copy.measurements.scanResolution]
     .filter(value => value !== undefined);
-/** The programs the measurements of a copy name as having taken them, each once, as far as they name any. */
+/**
+ * The programs the measurements of a copy name as having taken them, each once, as far as they name any.
+ * @category Lookups
+ */
 export const measuringSoftwareOf = (copy) => {
     const named = exportedMeasurementsOf(copy)
         .flatMap(value => value['@annotation']?.belief.reasons ?? [])
         .flatMap(reason => reason.type === 'measurement' ? reason.software ?? [] : []);
     return [...new Map(named.map(software => [`${software.name}\u0000${software.version ?? ''}`, software])).values()];
 };
-/** Whether the condition is the stretch or shrinkage of the paper, as measured on the copy. */
+/**
+ * Whether the condition is the stretch or shrinkage of the paper, as measured on the copy.
+ * @category Lookups
+ */
 export const isPaperStretch = (condition) => condition.conditionType === 'paper-stretch';
-/** What the copy's paper was measured to have done, where anything was measured. */
+/**
+ * What the copy's paper was measured to have done, where anything was measured.
+ * @category Lookups
+ */
 export const paperStretchOf = (copy) => copy.conditions.find(isPaperStretch);
-/** Whether the condition is a tear in the paper. */
+/**
+ * Whether the condition is a tear in the paper.
+ * @category Lookups
+ */
 export const isTear = (condition) => condition.conditionType === 'torn';
-/** The tears the copy is stated to have. */
+/**
+ * The tears the copy is stated to have.
+ * @category Lookups
+ */
 export const tearsOf = (copy) => copy.conditions.filter(isTear);
 /**
  * The bar a copy is read by, which is the one it was cut for. A copy
  * that names no system falls back to `defaultTrackerBar`.
+ * @category Systems and emulation
  */
 export const barOf = (copy) => trackerBarOf(copy.production?.system) ?? defaultTrackerBar;
-/** The diameter of the punch the copy was cut with, where the edition holds it true or likely. */
+/**
+ * The diameter of the punch the copy was cut with, where the edition holds it true or likely.
+ * @category Lookups
+ */
 export const punchDiameterOf = (copy) => {
     const diameter = copy.production?.perforator?.condition?.punchDiameter;
     return diameter && isAsserted(certaintyOf(diameter)) ? diameter.value : undefined;
@@ -78,6 +118,7 @@ export const punchDiameterOf = (copy) => {
  * would be 318 notes nobody played. The features stay on the copy,
  * since they are really on the paper and are his calibration of his own
  * scan; it is the reading that stops.
+ * @category Sources
  */
 export function asSymbols(features, bar) {
     const chains = features.filter(feature => feature.type === 'HoleChain');
@@ -97,6 +138,7 @@ export function asSymbols(features, bar) {
  * A non-empty result usually means the scan is calibrated wrongly. A chain
  * lying across several positions is counted against each one the bar
  * cannot read, and not at all where it reads them all.
+ * @category Sources
  */
 export function unreadTracks(features, bar) {
     const counts = new Map();
@@ -116,6 +158,7 @@ export function unreadTracks(features, bar) {
  * were laid out with, and on the rolls measured so far it comes within
  * about a quarter of a track. It is kept for copies imported before the
  * calibration was written down; anything read since carries its own.
+ * @internal
  */
 export const calibrationOf = (copy) => {
     if (copy.measurements.trackCalibration) {

package/lib/model/Symbol.d.ts

@@ -5,6 +5,7 @@ import { WithId } from "../shared/utils.js";
  * physical features on the roll. Symbols are the result of interpreting
  * the physical features (chains of holes, writings, etc.) on the roll copies.
  * @see crm:E90 Symbolic Object
+ * @category Format types
  */
 export interface Symbol<T extends string> extends WithId {
     type: T;
@@ -18,7 +19,16 @@ export interface Symbol<T extends string> extends WithId {
      */
     carriers: ReferenceAssumption[];
 }
+/**
+ * Whether the object is a symbol: a note, an expression or a text.
+ * @category Lookups
+ */
 export declare const isSymbol: (object: any) => object is AnySymbol;
+/**
+ * Whether the symbol is a command, a note or an expression, rather than
+ * a text.
+ * @category Lookups
+ */
 export declare const isCommand: (symbol: object | undefined) => symbol is AnyCommand;
 /**
  * A command is what the tracker bar reads from a chain of holes: the
@@ -26,6 +36,7 @@ export declare const isCommand: (symbol: object | undefined) => symbol is AnyCom
  * by such a chain, but it might also have different physical
  * appearances.
  * @see reo:Command
+ * @category Format types
  */
 export interface Command<T extends string> extends Symbol<T> {
     /**
@@ -63,10 +74,24 @@ export interface Command<T extends string> extends Symbol<T> {
      */
     pairedWith?: ReferenceAssumption;
 }
+/**
+ * The ways a command may be placed relative to another, in the order
+ * `placementsOf` reports them.
+ * @category Vocabulary
+ */
 export declare const placementRelations: readonly ['alignedWith', 'before', 'after'];
-/** The ways a command may be placed relative to another. */
+/**
+ * The ways a command may be placed relative to another.
+ * @category Format types
+ */
 export type PlacementRelation = typeof placementRelations[number];
+/** @inline */
 type Placeable = Partial<Record<PlacementRelation, ReferenceAssumption>>;
+/**
+ * A statement placing a command relative to another: how, and relative
+ * to which.
+ * @category Format types
+ */
 export type Placement = {
     relation: PlacementRelation;
     reference: ReferenceAssumption;
@@ -75,20 +100,24 @@ export type Placement = {
  * The statements placing a command relative to others, alignment first.
  * A command is meant to make one at most; the first is the one a
  * performance applies.
+ * @category Lookups
  */
 export declare const placementsOf: (command: Placeable) => Placement[];
+/** @inline */
 type Pairable = WithId & {
     pairedWith?: ReferenceAssumption;
 };
 /**
  * The pairs among the given commands, each once and in the order the
  * pairing is stated. A pair whose partner is absent is left out.
+ * @category Lookups
  */
 export declare const pairsAmong: <S extends Pairable>(commands: readonly S[]) => [S, S][];
 /**
  * A note symbol, representing a single pitched musical event on the roll.
  * The pitch is encoded via the tracker bar position (track number).
  * @see reo:Note
+ * @category Format types
  */
 export interface Note extends Command<'note'> {
     /**
@@ -101,6 +130,7 @@ export interface Note extends Command<'note'> {
  * The scope of an expression command, indicating whether it applies to
  * the bass or treble register of the piano.
  * @see reo:scope
+ * @category Format types
  */
 export type ExpressionScope = 'bass' | 'treble';
 /**
@@ -109,6 +139,7 @@ export type ExpressionScope = 'bass' | 'treble';
  * than sounding a note. Each expression has a scope (bass or treble)
  * and a specific expression type.
  * @see reo:Expression
+ * @category Format types
  */
 export interface Expression extends Command<'expression'> {
     /**
@@ -128,6 +159,7 @@ export interface Expression extends Command<'expression'> {
 /**
  * A textual symbol, e.g. a label or annotation found on the roll.
  * @see crm:E33 Linguistic Object
+ * @category Format types
  */
 export interface Text extends Symbol<'text'> {
     type: 'text';
@@ -140,7 +172,12 @@ export interface Text extends Symbol<'text'> {
 /**
  * A symbol can be either a note, an expression, or a text.
  * Notes and expressions are commands; texts are carried by writings.
+ * @category Format types
  */
 export type AnySymbol = Note | Expression | Text;
+/**
+ * A command: a note or an expression.
+ * @category Format types
+ */
 export type AnyCommand = Note | Expression;
 export {};

package/lib/model/Symbol.js

@@ -1,14 +1,29 @@
 import { idOf } from "./Assumption.js";
+/**
+ * Whether the object is a symbol: a note, an expression or a text.
+ * @category Lookups
+ */
 export const isSymbol = (object) => {
     return ('type' in object
         && (object.type === 'note' || object.type === 'expression' || object.type === 'text'));
 };
+/**
+ * Whether the symbol is a command, a note or an expression, rather than
+ * a text.
+ * @category Lookups
+ */
 export const isCommand = (symbol) => symbol !== undefined && 'type' in symbol && (symbol.type === 'note' || symbol.type === 'expression');
+/**
+ * The ways a command may be placed relative to another, in the order
+ * `placementsOf` reports them.
+ * @category Vocabulary
+ */
 export const placementRelations = ['alignedWith', 'before', 'after'];
 /**
  * The statements placing a command relative to others, alignment first.
  * A command is meant to make one at most; the first is the one a
  * performance applies.
+ * @category Lookups
  */
 export const placementsOf = (command) => placementRelations.flatMap(relation => {
     const reference = command[relation];
@@ -17,6 +32,7 @@ export const placementsOf = (command) => placementRelations.flatMap(relation =>
 /**
  * The pairs among the given commands, each once and in the order the
  * pairing is stated. A pair whose partner is absent is left out.
+ * @category Lookups
  */
 export const pairsAmong = (commands) => {
     const byId = new Map(commands.map(p => [p.id, p]));