linked-rolls 0.70.0 → 0.72.0

package/lib/model/Edit.d.ts

@@ -1,6 +1,10 @@
 import { Assumption } from "./Assumption.js";
 import { AnySymbol } from "./Symbol.js";
 import { WithId } from "../shared/utils.js";
+/**
+ * The types of editorial change an edit may state.
+ * @category Vocabulary
+ */
 export declare const editTypes: readonly ['additional-accent', 'add-redundancy', 'remove-redundancy', 
 /**
  * Carries the text into another reproducing system's coding: a
@@ -13,6 +17,7 @@ export declare const editTypes: readonly ['additional-accent', 'add-redundancy',
  * The type of editorial change applied to a symbol or set of symbols.
  * Classifies the nature of the edit, e.g. whether it corrects an error,
  * adds an accent, shifts a note, or shortens/prolongs a perforation.
+ * @category Format types
  */
 export type EditType = typeof editTypes[number];
 /**
@@ -28,6 +33,7 @@ export type EditType = typeof editTypes[number];
  * the axioms of reo.ttl; which of those dates bounds it closest is for
  * a query to pick.
  * @see reo:Edit
+ * @category Format types
  */
 export interface Edit extends WithId, Assumption {
     type: 'edit';
@@ -53,4 +59,8 @@ export interface Edit extends WithId, Assumption {
      */
     delete?: string[];
 }
+/**
+ * Whether the object is an edit.
+ * @category Lookups
+ */
 export declare const isEdit: (object: any) => object is Edit;

package/lib/model/Edit.js

@@ -1,3 +1,7 @@
+/**
+ * The types of editorial change an edit may state.
+ * @category Vocabulary
+ */
 export const editTypes = [
     'additional-accent',
     'add-redundancy',
@@ -14,6 +18,10 @@ export const editTypes = [
     'shorten',
     'prolong',
 ];
+/**
+ * Whether the object is an edit.
+ * @category Lookups
+ */
 export const isEdit = (object) => {
     return 'type' in object && object.type === 'edit';
 };

package/lib/model/Edition.d.ts

@@ -6,6 +6,7 @@ import { Editor, Person, Place } from "./Agent.js";
  * This type describes the creation of an edition,
  * i.e. the editor, publisher, and publication date.
  * @see lrmoo:F28 Expression Creation
+ * @category Format types
  */
 export interface EditionCreation {
     /**
@@ -33,6 +34,7 @@ export interface EditionCreation {
  * the persons involved in the process (e.g. pianist),
  * the place, and the date of the recording.
  * @see lrmoo:F28 Expression Creation
+ * @category Format types
  */
 export interface RecordingEvent {
     /**
@@ -76,6 +78,7 @@ export interface RecordingEvent {
  * The abstract concept of a roll, identified
  * by its catalogue number.
  * @see lrmoo:F1 Work
+ * @category Format types
  */
 export interface Roll {
     /**
@@ -92,6 +95,7 @@ export interface Roll {
 /**
  * Describes the specific digital edition of a piano roll.
  * @see lrmoo:F2 Expression
+ * @category Format types
  */
 export interface Edition {
     /**
@@ -156,11 +160,18 @@ export interface Edition {
      */
     versions: Version[];
 }
+/**
+ * What an edition states about itself rather than about the copies and
+ * versions of the roll: `base`, `title`, `license`, `version`,
+ * `creation` and the `roll` it edits.
+ * @category Format types
+ */
 export type EditionMetadata = Pick<Edition, 'base' | 'title' | 'license' | 'version' | 'creation' | 'roll'>;
 /**
  * The copy whose millimetres are the edition's axis: the one it names,
  * or where it names none or one it no longer has, the first copy with
  * features that is not aligned, which is how an edition stood before it
  * named one.
+ * @category Lookups
  */
 export declare const referenceCopyOf: (edition: Pick<Edition, 'copies' | 'referenceCopy'>) => RollCopy | undefined;

package/lib/model/Edition.js

@@ -4,6 +4,7 @@ import { featuresOf } from "./RollCopy.js";
  * or where it names none or one it no longer has, the first copy with
  * features that is not aligned, which is how an edition stood before it
  * named one.
+ * @category Lookups
  */
 export const referenceCopyOf = (edition) => edition.copies.find(copy => copy.id === edition.referenceCopy)
     ?? edition.copies.find(copy => !copy.measurements.alignment && featuresOf(copy).length > 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' },