linked-rolls 0.1.1 → 0.3.0

package/lib/RollCopy.d.ts

@@ -6,6 +6,7 @@ import { AnyFeature } from "./Feature";
 import { ObjectAssumption, ValueAssumption } from "./Assumption";
 import { WithId, WithType } from "./utils";
 import { ActorAssignment } from "./Edit";
+import { Agent, Concept } from "./Edition";
 /**
  * This condition state is used to describe the roll's
  * paper shrinkage or stretching. It might be calculated
@@ -16,6 +17,7 @@ export interface PaperStretch extends ConditionState<'paper-stretch'> {
     /**
      * The stretch factor, e.g. 1.02 means the paper has
      * stretched by 2% compared to its original dimensions.
+     * @see rdf:value
      */
     factor: number;
 }
@@ -53,11 +55,17 @@ export declare const applyStretch: (paperStretch: ObjectAssumption<PaperStretch>
  * A date value wrapped as an assumption, so that the date
  * can be annotated with a belief about its certainty and source.
  */
-export type DateAssignment = ValueAssumption<Date>;
+export type DateAssignment = ValueAssumption<Date> & {
+    /**
+     * The datatype of the value. Written on export so that
+     * RDF reads the value as a date rather than a string.
+     */
+    '@type'?: 'xsd:date';
+};
 /**
- * Describes the production of a roll copy, including the
- * manufacturing company, the roll system, and the paper used.
- * @see lrm:F33 Reproduction Event
+ * Describes the production of a roll copy: the manufacturer,
+ * the paper used, and the date.
+ * @see lrmoo:F32 Item Production Event
  */
 export interface ProductionEvent {
     /**
@@ -65,20 +73,15 @@ export interface ProductionEvent {
      * (e.g. "M. Welte & Söhne").
      * @see crm:P14 carried out by
      */
-    company: string;
-    /**
-     * The roll system used for production
-     * (e.g. "Welte-Mignon T100", "Welte-Mignon T98").
-     */
-    system: string;
+    company?: Agent;
     /**
-     * The paper type used for the roll copy.
-     * @see P126:employed
+     * The paper the roll copy was cut on.
+     * @see crm:P126 employed
      */
-    paper: string;
+    paper?: Concept;
     /**
      * The date of production, if known.
-     * @see crm:P4 has time-span
+     * @see dcterms:date
      */
     date?: DateAssignment;
 }
@@ -89,7 +92,15 @@ export interface ProductionEvent {
  * @see crm:E79 Part Addition, crm:E80 Part Removal
  */
 export type Modification = Partial<{
+    /**
+     * Who carried out the modification.
+     * @see crm:P14 carried out by
+     */
     actor: ActorAssignment;
+    /**
+     * When the modification took place.
+     * @see dcterms:date
+     */
     date: DateAssignment;
 }> & ({
     type: 'Addition';
@@ -112,6 +123,7 @@ export type Modification = Partial<{
      * Sometimes however, we may see traces of features
      * that have been removed, e.g. through bright spots on
      * the roll.
+     * @see crm:P21 had general purpose
      */
     purpose: 'delabeling';
 });
@@ -120,66 +132,78 @@ export type Modification = Partial<{
  * Each roll copy has its own set of features, measurements,
  * conditions, and modifications. Multiple copies of the same
  * roll may exist across different archives or collections.
- * @see crm:E22 Human-Made Object
+ * @see lrmoo:F5 Item
  */
 export interface RollCopy extends WithType<'RollCopy'>, WithId {
     /**
      * A list of operations that have been applied to this copy's features
      * (e.g. 'shifted', 'stretched') to normalize measurements
-     * for comparison with other copies.
+     * for comparison with other copies. Not exported to RDF.
      */
     ops: Array<'shifted' | 'stretched'>;
     /**
      * Physical measurements of this roll copy, including
      * dimensions, punch diameter, hole separation, margins,
      * shift corrections, and information about the measuring software.
+     * @see crm:P39i was measured by
      */
     measurements: Partial<{
         /**
          * The physical dimensions of the roll.
+         * @see reo:dimensions
          */
         dimensions: {
             /**
              * The width of the roll in the given unit.
+             * @see reo:width
              */
             width: number;
             /**
              * The total height (length) of the roll in the given unit.
+             * @see reo:height
              */
             height: number;
             /**
              * The unit of measurement (e.g. 'mm').
+             * @see crm:P91 has unit
              */
             unit: string;
         };
         /**
          * The average diameter of punched holes.
+         * @see reo:punchDiameter
          */
         punchDiameter: {
             /**
              * The measured punch diameter value.
+             * @see crm:P90 has value
              */
             value: number;
             /**
              * The unit of measurement (e.g. 'mm').
+             * @see crm:P91 has unit
              */
             unit: string;
         };
         /**
          * The distance between adjacent tracker bar holes.
+         * @see reo:holeSeparation
          */
         holeSeparation: {
             /**
              * The measured hole separation value.
+             * @see crm:P90 has value
              */
             value: number;
             /**
              * The unit of measurement (e.g. 'px', 'mm').
+             * @see crm:P91 has unit
              */
             unit: string;
         };
         /**
          * The margins on the treble and bass sides of the roll.
+         * Not exported to RDF.
          */
         margins: {
             /**
@@ -195,57 +219,65 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
              */
             unit: string;
         };
+        /**
+         * The shift applied to align this copy with the others.
+         * Not exported to RDF.
+         */
         shift: Shift;
         /**
          * Relates this copy's scan to the tracker bar: how the scanning
          * software's hole numbering was shifted onto the bar, and where
-         * the track grid sits in the image.
+         * the track grid sits in the image. Not exported to RDF.
          */
         trackCalibration: TrackCalibration;
         /**
          * Information about the software used to take the measurements.
+         * @see crmdig:L23 used software or firmware
          */
         measuredBy: {
             /**
              * The name of the measurement software.
+             * @see rdfs:label
              */
             software: string;
             /**
              * The version of the measurement software.
+             * @see owl:versionInfo
              */
             version: string;
             /**
              * The date on which the measurements were taken.
              * @format date
+             * @see dcterms:date
              */
             date: Date;
         };
     }>;
     /**
      * The production event that created this roll copy.
-     * @see lrm:R28i was produced by
+     * @see lrmoo:R28i was produced by
      */
     production?: ProductionEvent;
     /**
      * Condition assessments of this roll copy (e.g. paper stretch,
      * general wear). Each condition is an assumption annotatable
      * with a belief.
+     * @see crm:P44 has condition
      */
     conditions: RollConditionAssignment[];
     /**
-     * The current physical location or archive where this copy is held.
-     * @see crm:P55 has current location
+     * The institution or person holding this copy.
+     * @see crm:P50 has current keeper
      */
-    location: string;
+    keeper: Agent;
     /**
-     * Provides a reconstructed version of the roll,
-     * with shift, stretch and emendations already
-     * taken into account. This property will not be
-     * exported in the final JSON.
+     * The physical features found on this copy, with shift
+     * and stretch already applied when `ops` says so.
+     * @see crm:P56 bears feature
      */
     features: AnyFeature[];
     /**
-     * @see crm:P31 was modified by
+     * @see crm:P31i was modified by
      */
     modifications: Modification[];
     /**

package/lib/RollCopy.js

@@ -226,7 +226,7 @@ export function readFromStanfordAton(atonString, { trackShift, bar = welteT100,
         id: v4(),
         ops: [],
         conditions: [],
-        location: '',
+        keeper: { name: '', sameAs: [] },
         modifications: [],
         ...((scan ?? stanford) && { scan: scan ?? stanford?.scan }),
         measurements: {
@@ -302,7 +302,7 @@ export function readFromSpencerMIDI(midiBuffer, placeAt = atConstantSpeed(SPENCE
         id: v4(),
         ops: [],
         conditions: [],
-        location: '',
+        keeper: { name: '', sameAs: [] },
         measurements: {},
         modifications: [],
         features

package/lib/Symbol.d.ts

@@ -1,9 +1,10 @@
-import { ReferenceAssumption, ValueAssumption } from "./Assumption";
+import { ReferenceAssumption } from "./Assumption";
 import { WithId } from "./utils";
 /**
  * A symbol is an abstract musical or textual entity carried by one or more
  * physical features on the roll. Symbols are the result of interpreting
  * the physical features (holes, writings, etc.) on the roll copies.
+ * @see crm:E90 Symbolic Object
  */
 export interface Symbol<T extends string> extends WithId {
     type: T;
@@ -22,69 +23,84 @@ export declare const isSymbol: (object: any) => object is AnySymbol;
  * A perforation is a symbol that is typically encoded as a single punched
  * hole or a group of punched holes in the physical carrier.
  * However, it might also have different physical appearences.
- * @see reo:C5 Perforation
+ * @see reo:Perforation
  */
 export interface Perforation<T extends string> extends Symbol<T> {
     /**
      * In piano rolls, perforations are often aligned with other
      * perforations, e.g. a "crescendo off" might be logically
-     * aligned to the start of a note perforation.
-     * @see reo:P3 aligned with
+     * aligned to the start of a note perforation. This points
+     * to the perforation by its `@id`.
+     * @see reo:alignedWith
      */
-    alignedWith?: ValueAssumption<string>;
+    alignedWith?: ReferenceAssumption;
+    /**
+     * The perforation this one forms a pair with, e.g. a "forzando on"
+     * with its "forzando off". Any two perforations may be paired.
+     * The distance between the two is fixed: whatever displaces the
+     * one displaces the other. The relation is symmetric and is stated
+     * on one side only. This points to the perforation by its `@id`.
+     * @see reo:pairedWith
+     */
+    pairedWith?: ReferenceAssumption;
 }
+type Pairable = WithId & {
+    pairedWith?: ReferenceAssumption;
+};
+/**
+ * The pairs among the given perforations, each once and in the order
+ * the pairing is stated. A pair whose partner is absent is left out.
+ */
+export declare const pairsAmong: <S extends Pairable>(perforations: 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:P6 Note
+ * @see reo:Note
  */
 export interface Note extends Perforation<'note'> {
     /**
      * The MIDI pitch number of the note (e.g. 60 for middle C).
-     * @see reo:P5 has pitch
+     * @see reo:pitch
      */
     pitch: number;
 }
 /**
  * The scope of an expression perforation, indicating whether it
  * applies to the bass or treble register of the piano.
- * @see reo:P6 has scope
+ * @see reo:scope
  */
 export type ExpressionScope = 'bass' | 'treble';
-/**
- * The type of expression encoded by a perforation on the roll,
- * e.g. "crescendo on", "crescendo off", etc. on Welte T-100
- * rolls.
- * @see crm:P2 has type
- */
-export type ExpressionType = 'SustainPedalOn' | 'SustainPedalOff' | 'SoftPedalOn' | 'SoftPedalOff' | 'MezzoforteOff' | 'MezzoforteOn' | 'SlowCrescendoOn' | 'SlowCrescendoOff' | 'ForzandoOn' | 'ForzandoOff' | 'MotorOff' | 'MotorOn' | 'Rewind' | 'ElectricCutOff';
 /**
  * An expression symbol, representing a perforation on the roll
  * that governs dynamics, pedaling, or mechanical functions of the
  * reproducing piano. Each expression has a scope (bass or treble)
  * and a specific expression type.
- * @see reo:C7 Expression
+ * @see reo:Expression
  */
 export interface Expression extends Perforation<'expression'> {
     /**
      * Whether this expression applies to the bass or treble register.
-     * @see reo:P6 has scope
+     * @see reo:scope
      */
     scope: ExpressionScope;
     /**
-     * The specific type of expression (e.g. sustain pedal, forzando, etc.).
+     * The command the perforation gives, named as the reproducing
+     * system of the roll names it: "SustainPedalOn", "ForzandoOff"
+     * and so on for the Welte-Mignon T-100. The tracker bar of the
+     * system lists the values it reads.
      * @see crm:P2 has type
      */
-    expressionType: ExpressionType;
+    expressionType: string;
 }
 /**
  * A textual symbol, e.g. a label or annotation found on the roll.
  * @see crm:E33 Linguistic Object
  */
 export interface Text extends Symbol<'text'> {
+    type: 'text';
     /**
      * The text content of the symbol.
-     * @see crm:P3 has note
+     * @see crm:P190 has symbolic content
      */
     text: string;
 }
@@ -93,3 +109,4 @@ export interface Text extends Symbol<'text'> {
  * Notes and expressions are perforations; texts are carried by writings.
  */
 export type AnySymbol = Note | Expression | Text;
+export {};

package/lib/Symbol.js

@@ -1,4 +1,16 @@
+import { idOf } from "./Assumption";
 export const isSymbol = (object) => {
     return ('type' in object
         && (object.type === 'note' || object.type === 'expression' || object.type === 'text'));
 };
+/**
+ * The pairs among the given perforations, each once and in the order
+ * the pairing is stated. A pair whose partner is absent is left out.
+ */
+export const pairsAmong = (perforations) => {
+    const byId = new Map(perforations.map(p => [p.id, p]));
+    return perforations
+        .filter((p) => p.pairedWith !== undefined)
+        .map((p) => [p, byId.get(idOf(p.pairedWith))])
+        .filter((pair) => pair[1] !== undefined);
+};

package/lib/TrackerBar.d.ts

@@ -1,3 +1,4 @@
+import type { Concept } from "./Edition";
 import { Expression, Note } from "./Symbol";
 /**
  * What a tracker bar position does: sound a note, or operate one of
@@ -27,6 +28,12 @@ export type TrackMeaning = NoteMeaning | ExpressionMeaning;
  * ask the tracker bar rather than repeat the boundaries.
  */
 export interface TrackerBar {
+    /**
+     * Names the reproducing system in the type vocabulary:
+     * the system is `https://w3id.org/reo/type/system/<id>` and its
+     * expression types live under `https://w3id.org/reo/type/<id>/`.
+     */
+    readonly id: string;
     readonly name: string;
     /** Width of the roll the bar reads, in mm. */
     readonly width: number;
@@ -34,6 +41,8 @@ export interface TrackerBar {
     readonly trackCount: number;
     /** The blocks of positions, from the bass edge upwards. */
     readonly areas: readonly TrackArea[];
+    /** The expression types the bar reads, each a term of the system. */
+    readonly expressionTypes: readonly string[];
     /**
      * The position carrying the rewind perforation, which runs at
      * the very end of a roll and is the usual landmark for calibrating
@@ -45,6 +54,15 @@ export interface TrackerBar {
     /** `undefined` for a position the bar does not read. */
     roleOf(track: number): TrackRole | undefined;
 }
+/** The roll system a tracker bar belongs to, as the roll metadata states it. */
+export declare const systemOf: (bar: TrackerBar) => Concept;
+/** The identifier of a system the type vocabulary knows, from its concept. */
+export declare const systemIdOf: (system: Concept | undefined) => string | undefined;
+/**
+ * The commands of the Welte-Mignon T-100, as its tracker bar reads them.
+ */
+export declare const welteT100ExpressionTypes: readonly ["SustainPedalOn", "SustainPedalOff", "SoftPedalOn", "SoftPedalOff", "MezzoforteOff", "MezzoforteOn", "SlowCrescendoOn", "SlowCrescendoOff", "ForzandoOn", "ForzandoOff", "MotorOff", "MotorOn", "Rewind", "ElectricCutOff"];
+export type WelteT100ExpressionType = typeof welteT100ExpressionTypes[number];
 /**
  * Welte-Mignon T-100 ("red Welte"), cf. Hagmann, pp. 75 and 178.
  *

package/lib/TrackerBar.js

@@ -1,3 +1,8 @@
+const SYSTEM_IRI = 'https://w3id.org/reo/type/system/';
+/** The roll system a tracker bar belongs to, as the roll metadata states it. */
+export const systemOf = (bar) => ({ id: SYSTEM_IRI + bar.id, name: bar.name, sameAs: [] });
+/** The identifier of a system the type vocabulary knows, from its concept. */
+export const systemIdOf = (system) => system?.id?.startsWith(SYSTEM_IRI) ? system.id.slice(SYSTEM_IRI.length) : undefined;
 const areasOf = ({ notes, trackCount }) => [
     { role: 'bass-expression', from: 1, to: notes.from - 1 },
     { role: 'note', from: notes.from, to: notes.to },
@@ -28,15 +33,36 @@ const describe = (spec) => {
         throw new Error(`${spec.name} declares no rewind track`);
     }
     return {
+        id: spec.id,
         name: spec.name,
         width: spec.width,
         trackCount: spec.trackCount,
         areas,
+        expressionTypes: [...new Set(spec.expressions.values())],
         rewindTrack,
         meaningOf,
         roleOf
     };
 };
+/**
+ * The commands of the Welte-Mignon T-100, as its tracker bar reads them.
+ */
+export const welteT100ExpressionTypes = [
+    'SustainPedalOn',
+    'SustainPedalOff',
+    'SoftPedalOn',
+    'SoftPedalOff',
+    'MezzoforteOff',
+    'MezzoforteOn',
+    'SlowCrescendoOn',
+    'SlowCrescendoOff',
+    'ForzandoOn',
+    'ForzandoOff',
+    'MotorOff',
+    'MotorOn',
+    'Rewind',
+    'ElectricCutOff'
+];
 /**
  * Welte-Mignon T-100 ("red Welte"), cf. Hagmann, pp. 75 and 178.
  *
@@ -45,6 +71,7 @@ const describe = (spec) => {
  * treble above it, in mirrored order.
  */
 export const welteT100 = describe({
+    id: 'welte-t100',
     name: 'Welte-Mignon T100',
     width: 328,
     trackCount: 100,

package/lib/Version.d.ts

@@ -11,31 +11,39 @@ export type VersionType = typeof versionTypes[number];
 /**
  * A motivation provides a reason or rationale for an editorial change.
  * Motivations are defined at the version level and referenced by edits.
- * @see crm:E73 Information Object
+ * @see crm:E33 Linguistic Object
  */
 export type Motivation = WithType<'motivation'> & WithId & WithNote;
 /**
  * A version is defined by the sum of edits applied
  * to the version it is based on. For simple identification,
  * a siglum is given to each version.
+ * @see lrmoo:F2 Expression
  */
-export interface Version {
-    id: string;
+export interface Version extends WithId, WithType<'Version'> {
     /**
      * A short siglum to identify the version, e.g. "A", "B1", "B2_rev", etc.
+     * @see reo:siglum
      */
     siglum: string;
+    /**
+     * Whether the version served as a master for reproductions
+     * or exists on one copy only.
+     * @see crm:P2 has type
+     */
+    versionType: VersionType;
     /**
      * If no derivation is defined, it is assumed that this version represents the mother roll.
+     * @see lrmoo:R76 is derivative of
      */
     basedOn?: ReferenceAssumption;
     /**
      * The list of edits that, applied to the base version, produce this version.
+     * @see reo:involvedEdit
      */
     edits: Edit[];
     /**
      * A collection of motivations used in this version's edits.
      */
     motivations: Motivation[];
-    type: VersionType;
 }

package/lib/asJsonLd.js

@@ -1,3 +1,4 @@
+import { systemIdOf } from "./TrackerBar";
 export const exportDate = (date) => {
     const year = date.getFullYear();
     const month = String(date.getMonth() + 1).padStart(2, "0");
@@ -32,13 +33,26 @@ const asJsonLdEntity = (obj) => {
             result[key] = value;
         }
     }
+    if ('@value' in obj && obj['@value'] instanceof Date) {
+        result['@type'] = 'xsd:date';
+    }
     return result;
 };
+/**
+ * The context of the roll's reproducing system, which reads the
+ * expression types as that system's terms.
+ */
+const systemContextOf = (edition) => {
+    const system = systemIdOf(edition.roll?.system);
+    return system ? [`https://w3id.org/reo/${system}/context.jsonld`] : [];
+};
 export const asJsonLd = (edition) => {
-    const { base, copies, ...rest } = asJsonLdEntity(edition);
+    // The context is the export's own; one carried in from an import must not override it.
+    const { base, copies, '@context': carried, ...rest } = asJsonLdEntity(edition);
     return {
         '@context': [
-            'https://linked-rolls.org/rollo/1.0/edition.jsonld',
+            'https://w3id.org/reo/context.jsonld',
+            ...systemContextOf(edition),
             {
                 '@base': edition.base
             }

package/lib/context.d.ts

@@ -1 +1,3 @@
 export { default as jsonLdContext } from './spec/context.json';
+/** The context of the Welte-Mignon T-100, added to an edition of a T-100 roll. */
+export { default as welteT100JsonLdContext } from './spec/welte-t100.context.json';

package/lib/context.js

@@ -1 +1,3 @@
 export { default as jsonLdContext } from './spec/context.json';
+/** The context of the Welte-Mignon T-100, added to an edition of a T-100 roll. */
+export { default as welteT100JsonLdContext } from './spec/welte-t100.context.json';

package/lib/importJsonLd.js

@@ -1,3 +1,4 @@
+import { migrate } from "./migrate";
 const isDate = (value) => {
     const datePattern = /^\d{4}-\d{1,2}-\d{1,2}$/;
     return datePattern.test(value);
@@ -14,7 +15,11 @@ const fromJsonLdEntity = (json) => {
         return json;
     }
     let result = json;
-    if ('@type' in json) {
+    if ('@value' in json) {
+        // the datatype of a value object, not a class
+        delete result['@type'];
+    }
+    else if ('@type' in json) {
         result['type'] = json['@type'];
         delete result['@type'];
     }
@@ -49,10 +54,19 @@ const fromJsonLdEntity = (json) => {
     }
     return result;
 };
+// The export prefixes copy identifiers with `copy/`; this is its inverse.
+const withPlainCopyIds = (json) => ({
+    ...json,
+    copies: (json.copies ?? []).map((copy) => ({
+        ...copy,
+        '@id': typeof copy['@id'] === 'string' ? copy['@id'].replace(/^copy\//, '') : copy['@id']
+    }))
+});
 export const importJsonLd = (json) => {
-    const edition = fromJsonLdEntity(json);
-    if (Array.isArray(json['@context'])) {
-        edition.base = json['@context'].find((c) => c['@base'])?.['@base'] || '';
-    }
+    const { '@context': context, ...document } = withPlainCopyIds(migrate(json));
+    const edition = fromJsonLdEntity(document);
+    edition.base = Array.isArray(context)
+        ? context.find((c) => c['@base'])?.['@base'] || ''
+        : '';
     return edition;
 };

package/lib/migrate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Brings the JSON of an edition written by an earlier release of the
+ * format up to the current shape. The shapes are recognised
+ * structurally, so a file that is current already passes through
+ * unchanged, and a file may be migrated any number of times.
+ *
+ * Format 0.1 used the type discriminator of versions and conditions
+ * for their typology, held the keeper and the production metadata as
+ * strings, and named the roll system on each copy. Some 0.1 files
+ * also carry references written as values and two keys the format
+ * had renamed before.
+ */
+type Json = any;
+export declare const migrate: (edition: Json) => Json;
+export {};