linked-rolls 0.70.0 → 0.72.0

package/lib/model/Quantity.d.ts

@@ -10,45 +10,133 @@ declare const unit: unique symbol;
 /**
  * The units a record may state. A `Measure` is limited to these, since
  * they are what the `unit` field is allowed to say.
+ * @category Format types
  */
 export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min' | 'px/in' | 'deg' | 'percent';
 export type Quantity<U extends string> = number & {
     readonly [unit]: U;
 };
-/** A place along the roll, or any length on the paper. */
+/**
+ * A place along the roll, or any length on the paper.
+ * @category Units
+ */
 export type Millimeters = Quantity<'mm'>;
+/**
+ * A length in centimetres.
+ * @category Units
+ */
 export type Centimeters = Quantity<'cm'>;
-/** A place in a scan. Comparable within one scan only, since the resolution is the scan's. */
+/**
+ * A place in a scan. Comparable within one scan only, since the resolution is the scan's.
+ * @category Units
+ */
 export type Pixels = Quantity<'px'>;
-/** A position across the roll, numbered as the tracker bar does. */
+/**
+ * A position across the roll, numbered as the tracker bar does.
+ * @category Units
+ */
 export type Track = Quantity<'track'>;
+/**
+ * A time in seconds, such as the moment a performed event falls at.
+ * @category Units
+ */
 export type Seconds = Quantity<'s'>;
+/**
+ * A time in milliseconds.
+ * @category Units
+ */
 export type Milliseconds = Quantity<'ms'>;
+/**
+ * A paper speed in feet per minute.
+ * @category Units
+ */
 export type FeetPerMinute = Quantity<'ft/min'>;
+/**
+ * A paper speed in metres per minute.
+ * @category Units
+ */
 export type MetersPerMinute = Quantity<'m/min'>;
-/** How finely a scan was read: pixels of the image per inch of paper. */
+/**
+ * How finely a scan was read: pixels of the image per inch of paper.
+ * @category Units
+ */
 export type Resolution = Quantity<'px/in'>;
-/** An angle on the roll, turning from the line across the paper towards the end of the roll. */
+/**
+ * An angle on the roll, turning from the line across the paper towards the end of the roll.
+ * @category Units
+ */
 export type Degrees = Quantity<'deg'>;
-/** A share of a length, such as how far the paper has stretched: dimensionless, in hundredths. */
+/**
+ * A share of a length, such as how far the paper has stretched: dimensionless, in hundredths.
+ * @category Units
+ */
 export type Percent = Quantity<'percent'>;
-/** 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 declare const quantity: <U extends string>(value: number) => Quantity<U>;
+/**
+ * Names a number in millimetres.
+ * @category Units
+ */
 export declare const mm: (value: number) => Quantity<"mm">;
+/**
+ * Names a number in centimetres.
+ * @category Units
+ */
 export declare const cm: (value: number) => Quantity<"cm">;
+/**
+ * Names a number in pixels of a scan.
+ * @category Units
+ */
 export declare const px: (value: number) => Quantity<"px">;
+/**
+ * Names a number as a position across the roll, as the tracker bar
+ * numbers it.
+ * @category Units
+ */
 export declare const track: (value: number) => Quantity<"track">;
+/**
+ * Names a number in seconds.
+ * @category Units
+ */
 export declare const seconds: (value: number) => Quantity<"s">;
+/**
+ * Names a number in milliseconds.
+ * @category Units
+ */
 export declare const milliseconds: (value: number) => Quantity<"ms">;
+/**
+ * Names a number as a paper speed in feet per minute.
+ * @category Units
+ */
 export declare const feetPerMinute: (value: number) => Quantity<"ft/min">;
+/**
+ * Names a number as a paper speed in metres per minute.
+ * @category Units
+ */
 export declare const metersPerMinute: (value: number) => Quantity<"m/min">;
+/**
+ * Names a number as the resolution of a scan, in pixels per inch.
+ * @category Units
+ */
 export declare const pixelsPerInch: (value: number) => Quantity<"px/in">;
+/**
+ * Names a number as an angle in degrees.
+ * @category Units
+ */
 export declare const degrees: (value: number) => Quantity<"deg">;
+/**
+ * Names a number as a share in per cent.
+ * @category Units
+ */
 export declare const percent: (value: number) => Quantity<"percent">;
 /**
  * A value together with the unit it was measured in, as a record
  * states it.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface Measure<U extends Unit> {
     /**
@@ -62,26 +150,85 @@ export interface Measure<U extends Unit> {
      */
     unit: U;
 }
+/**
+ * The sum of two quantities in one unit.
+ * @internal
+ */
 export declare const add: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+/**
+ * The first quantity less the second, in their unit.
+ * @internal
+ */
 export declare const subtract: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+/**
+ * How far apart two quantities in one unit lie, whichever is the
+ * larger.
+ * @internal
+ */
 export declare const distance: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
-/** A quantity times a plain factor, such as a stretch. */
+/**
+ * A quantity times a plain factor, such as a stretch.
+ * @internal
+ */
 export declare const scale: <U extends string>(a: Quantity<U>, factor: number) => Quantity<U>;
+/**
+ * The smaller of two quantities in one unit.
+ * @internal
+ */
 export declare const min: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+/**
+ * The larger of two quantities in one unit.
+ * @internal
+ */
 export declare const max: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
-/** 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 declare const clamp: <U extends string>(value: Quantity<U>, low: Quantity<NoInfer<U>>, high: Quantity<NoInfer<U>>) => Quantity<U>;
+/**
+ * The quantities added up, zero where there are none.
+ * @internal
+ */
 export declare const sum: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U>;
+/**
+ * The mean of the quantities.
+ * @internal
+ */
 export declare const mean: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U>;
-/** 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 declare const inMillimeters: (place: Pixels, dpi: number) => Millimeters;
-/** 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 declare const inPixels: (place: Millimeters, dpi: number) => Pixels;
+/**
+ * A length in millimetres, in centimetres.
+ * @internal
+ */
 export declare const inCentimeters: (length: Millimeters) => Centimeters;
+/**
+ * A time in milliseconds, in seconds.
+ * @internal
+ */
 export declare const inSeconds: (time: Milliseconds) => Seconds;
+/**
+ * A time in seconds, in milliseconds.
+ * @internal
+ */
 export declare const inMilliseconds: (time: Seconds) => Milliseconds;
-/** A speed as a record states it, in feet or metres per minute. */
+/**
+ * A speed as a record states it, in feet or metres per minute.
+ * @category Format types
+ */
 export type SpeedMeasure = Measure<'ft/min'> | Measure<'m/min'>;
-/** 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 declare const inMetersPerMinute: (speed: SpeedMeasure) => MetersPerMinute;
 export {};

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;