linked-rolls 0.69.0 → 0.71.0

package/lib/model/Feature.d.ts

@@ -8,6 +8,7 @@ import { Measure, Millimeters, Track } from "./Quantity.js";
  * measured in millimeters from the beginning of the roll.
  * The `from` value is the start position and `to` is the end position.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface HorizontalSpan {
     /**
@@ -34,6 +35,7 @@ export interface HorizontalSpan {
  * measured in track numbers. Track numbers correspond to
  * positions on the tracker bar.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface VerticalSpan {
     /**
@@ -53,14 +55,28 @@ export interface VerticalSpan {
      */
     to?: Track;
 }
+/**
+ * The kinds of feature, a patch among them, each by the type that names
+ * it.
+ * @category Vocabulary
+ */
 export declare const featureTypes: readonly ['HoleChain', 'Writing', 'Mark', 'Patch'];
+/**
+ * The type naming a kind of feature.
+ * @category Format types
+ */
 export type FeatureType = typeof featureTypes[number];
+/**
+ * Whether the value names a kind of feature.
+ * @category Lookups
+ */
 export declare const isFeatureType: (value: unknown) => value is FeatureType;
 /**
  * A feature on the roll, e.g. a perforation, a writing, a mark or a
  * patch, defined by its horizontal and vertical position and
  * extent. Each kind of feature is a class of its own, which its type
  * names.
+ * @category Format types
  */
 export interface RollFeature<T extends FeatureType, DamageT extends string> extends WithId, WithType<T> {
     /**
@@ -85,18 +101,26 @@ export interface RollFeature<T extends FeatureType, DamageT extends string> exte
      */
     condition?: ObjectAssumption<ConditionState<DamageT>>;
 }
+/**
+ * The kinds of condition each kind of feature may be in.
+ * @category Vocabulary
+ */
 export declare const conditions: {
     readonly HoleChain: readonly ["partially-torn", "missing-perforation"];
     readonly Writing: readonly ["illegible"];
     readonly Mark: readonly ["faded"];
     readonly Patch: readonly ["detaching", "ripped"];
 };
-/** The kinds of condition a feature may be in, whichever kind of feature it is. */
+/**
+ * The kinds of condition a feature may be in, whichever kind of feature it is.
+ * @category Format types
+ */
 export type FeatureConditionType = typeof conditions[FeatureType][number];
 /**
  * A condition assigned to a feature, annotatable with a belief about
  * its certainty. Which of the kinds a feature may be in depends on its
  * own kind, which `conditions` states.
+ * @category Format types
  */
 export type FeatureConditionAssignment = ObjectAssumption<ConditionState<FeatureConditionType>>;
 /**
@@ -109,12 +133,14 @@ export type FeatureConditionAssignment = ObjectAssumption<ConditionState<Feature
  * features on mechanical or digital carriers" among the features
  * purposely created by human activity.
  * @see reo:HoleChain
+ * @category Format types
  */
 export interface HoleChain extends RollFeature<'HoleChain', typeof conditions.HoleChain[number]> {
 }
 /**
  * Something that lies on a face of the paper rather than through it. A
  * chain of holes is not one: it goes through, and is on both faces at once.
+ * @category Format types
  */
 export interface OnAFace {
     /**
@@ -124,15 +150,30 @@ export interface OnAFace {
      */
     side?: 'recto' | 'verso';
 }
+/**
+ * The ways a trace may have been put on the paper.
+ * @category Vocabulary
+ */
 export declare const techniques: readonly ['print', 'handwriting', 'stamp'];
-/** How a trace was put on the paper. */
+/**
+ * How a trace was put on the paper.
+ * @category Format types
+ */
 export type Technique = typeof techniques[number];
+/**
+ * What a trace may have been put on the paper with.
+ * @category Vocabulary
+ */
 export declare const media: readonly ['ink', 'pencil', 'crayon'];
-/** What a trace was put on with. */
+/**
+ * What a trace was put on with.
+ * @category Format types
+ */
 export type Medium = typeof media[number];
 /**
  * A trace is a visible mark or writing on the roll surface.
  * Traces may fade over time.
+ * @category Format types
  */
 export interface Trace<T extends FeatureType> extends RollFeature<T, typeof conditions[T][number]>, OnAFace {
     /**
@@ -149,13 +190,17 @@ export interface Trace<T extends FeatureType> extends RollFeature<T, typeof cond
      */
     medium?: Medium;
 }
-/** The text a writing carries. It names no carriers of its own, the writing being its carrier. */
+/**
+ * The text a writing carries. It names no carriers of its own, the writing being its carrier.
+ * @category Format types
+ */
 export type Transcription = Omit<Text, 'carriers'>;
 /**
  * A piece of writing found on the roll, such as a label,
  * catalogue number, or annotation. Writings state how they were made
  * and a transcription of their content.
  * @see reo:Writing
+ * @category Format types
  */
 export interface Writing extends Trace<'Writing'> {
     /**
@@ -187,6 +232,7 @@ export interface Writing extends Trace<'Writing'> {
  * reading of it (crminf:I16 Meaning Comprehension) rather than a
  * property of the feature, so its shape is not stated here.
  * @see reo:Mark
+ * @category Format types
  */
 export interface Mark extends Trace<'Mark'> {
 }
@@ -195,6 +241,7 @@ export interface Mark extends Trace<'Mark'> {
  * strip covering perforations, or a patch reinforcing a tear. A patch
  * may itself carry other features, such as writings or holes.
  * @see reo:Patch
+ * @category Format types
  */
 export interface Patch extends RollFeature<'Patch', typeof conditions.Patch[number]>, OnAFace {
     /**
@@ -220,12 +267,14 @@ export interface Patch extends RollFeature<'Patch', typeof conditions.Patch[numb
  * The features proper: a chain of holes, a writing and a mark are all
  * human-made features, and each of them is borne by whatever it sits on.
  * A patch is an object glued onto the paper and stands apart from them.
+ * @category Format types
  */
 export type AnyFeature = HoleChain | Writing | Mark;
 /**
  * Anything found at a place of its own on the roll: a feature or a
  * patch. E24 Physical Human-Made Thing is the class both fall under,
  * E22 and E25 being its subclasses.
+ * @category Format types
  */
 export type FeatureOrPatch = AnyFeature | Patch;
 /**
@@ -236,14 +285,32 @@ type Unplaced<T> = T extends FeatureOrPatch ? PartialBy<T, 'horizontal' | 'verti
 /**
  * A feature borne by another feature. It states no place of its own,
  * the feature bearing it standing in one.
+ * @category Format types
  */
 export type NestedFeature = Unplaced<FeatureOrPatch>;
-/** Whether the feature states a place of its own, which one a patch bears does not. */
+/**
+ * Whether the feature states a place of its own, which one a patch bears does not.
+ * @category Lookups
+ */
 export declare const isPlaced: (feature: NestedFeature) => feature is FeatureOrPatch;
+/**
+ * Whether the object is a feature or a patch, as its type says.
+ * @category Lookups
+ */
 export declare const isRollFeature: (obj: object) => obj is FeatureOrPatch;
+/**
+ * Whether the feature is a patch.
+ * @category Lookups
+ */
 export declare const isPatch: <T extends NestedFeature>(feature: T) => feature is T & Patch;
-/** The features a feature bears: a patch those stated as parts of it, any other feature none. */
+/**
+ * The features a feature bears: a patch those stated as parts of it, any other feature none.
+ * @category Lookups
+ */
 export declare const featuresBorneBy: (feature: NestedFeature) => NestedFeature[];
-/** The feature together with everything it bears, as deep as a patch on a patch goes. */
+/**
+ * The feature together with everything it bears, as deep as a patch on a patch goes.
+ * @category Lookups
+ */
 export declare const withBorneFeatures: (feature: NestedFeature) => NestedFeature[];
 export {};

package/lib/model/Feature.js

@@ -1,20 +1,58 @@
+/**
+ * The kinds of feature, a patch among them, each by the type that names
+ * it.
+ * @category Vocabulary
+ */
 export const featureTypes = ['HoleChain', 'Writing', 'Mark', 'Patch'];
+/**
+ * Whether the value names a kind of feature.
+ * @category Lookups
+ */
 export const isFeatureType = (value) => featureTypes.includes(value);
+/**
+ * The kinds of condition each kind of feature may be in.
+ * @category Vocabulary
+ */
 export const conditions = {
     HoleChain: ['partially-torn', 'missing-perforation'],
     Writing: ['illegible'],
     Mark: ['faded'],
     Patch: ['detaching', 'ripped']
 };
+/**
+ * The ways a trace may have been put on the paper.
+ * @category Vocabulary
+ */
 export const techniques = ['print', 'handwriting', 'stamp'];
+/**
+ * What a trace may have been put on the paper with.
+ * @category Vocabulary
+ */
 export const media = ['ink', 'pencil', 'crayon'];
-/** Whether the feature states a place of its own, which one a patch bears does not. */
+/**
+ * Whether the feature states a place of its own, which one a patch bears does not.
+ * @category Lookups
+ */
 export const isPlaced = (feature) => feature.horizontal !== undefined && feature.vertical !== undefined;
+/**
+ * Whether the object is a feature or a patch, as its type says.
+ * @category Lookups
+ */
 export const isRollFeature = (obj) => {
     return 'type' in obj && isFeatureType(obj.type);
 };
+/**
+ * Whether the feature is a patch.
+ * @category Lookups
+ */
 export const isPatch = (feature) => feature.type === 'Patch';
-/** The features a feature bears: a patch those stated as parts of it, any other feature none. */
+/**
+ * The features a feature bears: a patch those stated as parts of it, any other feature none.
+ * @category Lookups
+ */
 export const featuresBorneBy = (feature) => isPatch(feature) ? feature.features ?? [] : [];
-/** The feature together with everything it bears, as deep as a patch on a patch goes. */
+/**
+ * The feature together with everything it bears, as deep as a patch on a patch goes.
+ * @category Lookups
+ */
 export const withBorneFeatures = (feature) => [feature, ...featuresBorneBy(feature).flatMap(withBorneFeatures)];

package/lib/model/FeatureSource.d.ts

@@ -6,10 +6,19 @@ import { WithNote } from "../shared/utils.js";
  * What a copy's features were read from. The kinds run from the paper
  * itself, through files in which the roll has already been read into
  * notes and commands, to a sound recording of the copy being played.
+ * @category Vocabulary
  */
 export declare const sourceKinds: readonly ['roll', 'scan', 'analysis', 'reading', 'emulation', 'recording'];
+/**
+ * A kind of source a copy's features can be read from, from the paper
+ * itself to a sound recording of the copy being played.
+ * @category Format types
+ */
 export type SourceKind = typeof sourceKinds[number];
-/** How each kind of source is referred to in prose. */
+/**
+ * How each kind of source is referred to in prose.
+ * @category Vocabulary
+ */
 export declare const sourceLabels: Record<SourceKind, string>;
 /**
  * Whether a source of this kind gives positions that were measured. A
@@ -17,12 +26,14 @@ export declare const sourceLabels: Record<SourceKind, string>;
  * emulation and a recording give the reading somebody else made: the
  * roll has been turned into notes and commands already, and turning
  * those back into chains of holes reconstructs them.
+ * @category Lookups
  */
 export declare const isMeasured: (kind: SourceKind) => boolean;
 /**
  * Whether a source of this kind bears witness to the paper. Punch
  * diameter, hole separation, punching pattern, marks and writings can
  * be observed on the roll and on an image of it, and on nothing else.
+ * @category Lookups
  */
 export declare const bearsPhysicalEvidence: (kind: SourceKind) => boolean;
 export type { Software } from "./Agent.js";
@@ -30,6 +41,7 @@ export type { Software } from "./Agent.js";
  * An instrument a copy was played on to be recorded. How it was
  * regulated, where that is known, is its condition.
  * @see crm:E22 Human-Made Object
+ * @category Format types
  */
 export interface Instrument extends Named {
     /**
@@ -47,6 +59,7 @@ export interface Instrument extends Named {
  * `reservationsAbout`, which works out what a copy cannot vouch for
  * from what it states here.
  * @see crm:E7 Activity
+ * @category Format types
  */
 export interface FeatureSource extends WithNote {
     /**

package/lib/model/FeatureSource.js

@@ -2,6 +2,7 @@
  * What a copy's features were read from. The kinds run from the paper
  * itself, through files in which the roll has already been read into
  * notes and commands, to a sound recording of the copy being played.
+ * @category Vocabulary
  */
 export const sourceKinds = [
     'roll',
@@ -11,7 +12,10 @@ export const sourceKinds = [
     'emulation',
     'recording'
 ];
-/** How each kind of source is referred to in prose. */
+/**
+ * How each kind of source is referred to in prose.
+ * @category Vocabulary
+ */
 export const sourceLabels = {
     roll: 'the roll itself',
     scan: 'a scan of the roll',
@@ -28,11 +32,13 @@ const physical = ['roll', 'scan'];
  * emulation and a recording give the reading somebody else made: the
  * roll has been turned into notes and commands already, and turning
  * those back into chains of holes reconstructs them.
+ * @category Lookups
  */
 export const isMeasured = (kind) => measured.includes(kind);
 /**
  * Whether a source of this kind bears witness to the paper. Punch
  * diameter, hole separation, punching pattern, marks and writings can
  * be observed on the roll and on an image of it, and on nothing else.
+ * @category Lookups
  */
 export const bearsPhysicalEvidence = (kind) => physical.includes(kind);

package/lib/model/Perforator.d.ts

@@ -10,6 +10,7 @@ import { WithId, WithType } from "../shared/utils.js";
  * runs along the roll, and is another thing than the hole separation,
  * which is the distance across the roll from one track to the next.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface ChainPitch extends Measure<'mm'> {
     /**
@@ -35,6 +36,7 @@ export interface ChainPitch extends Measure<'mm'> {
  * with a whole number of steps, so its lengths fall on a comb of this
  * spacing.
  * @see crm:E54 Dimension
+ * @category Format types
  */
 export interface Advance extends Measure<'mm'> {
     /**
@@ -57,6 +59,7 @@ export interface Advance extends Measure<'mm'> {
  * perforations show it. No time is stated: how long a machine kept a
  * setting is for a comparison across rolls to find out.
  * @see crm:E3 Condition State
+ * @category Format types
  */
 export interface PerforatorSetting extends ConditionState<'setting'> {
     /**
@@ -81,6 +84,7 @@ export interface PerforatorSetting extends ConditionState<'setting'> {
  * own. `ontology/types.ttl` defines them, and a test holds this list
  * against it.
  * @see crm:E55 Type
+ * @category Vocabulary
  */
 export declare const drives: readonly [{
     readonly id: 'https://w3id.org/reo/type/drive/ram-head';
@@ -89,10 +93,15 @@ export declare const drives: readonly [{
     readonly id: 'https://w3id.org/reo/type/drive/asynchronous';
     readonly name: 'asynchronous';
 }];
+/**
+ * The IRI of a drive the type vocabulary declares.
+ * @category Format types
+ */
 export type DriveId = typeof drives[number]['id'];
 /**
  * A drive, named by its IRI alone.
  * @see crm:E55 Type
+ * @category Format types
  */
 export interface Drive {
     /** The IRI the type vocabulary gives the drive. */
@@ -103,6 +112,7 @@ export interface Drive {
  * alone. Whether it is the one another copy was punched on is left to a
  * statement of identity made about it elsewhere, which its id allows.
  * @see crm:E22 Human-Made Object
+ * @category Format types
  */
 export interface Perforator extends WithType<'Perforator'>, WithId {
     /**

package/lib/model/Perforator.js

@@ -4,6 +4,7 @@
  * own. `ontology/types.ttl` defines them, and a test holds this list
  * against it.
  * @see crm:E55 Type
+ * @category Vocabulary
  */
 export const drives = [
     { id: 'https://w3id.org/reo/type/drive/ram-head', name: 'ram head' },

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 {};