linked-rolls 0.69.0 → 0.71.0

package/lib/lookup/paths.js

@@ -1,4 +1,9 @@
 import { perState } from "./perState.js";
+/**
+ * What stands at the path in an edition or a draft of one, or nothing
+ * where the path leads nowhere.
+ * @category Lookups
+ */
 export const getAt = (path, obj) => {
     let node = obj;
     for (const key of path) {
@@ -69,12 +74,21 @@ const placesIn = perState((edition) => {
     traverse(edition, null);
     return { paths, links };
 });
-/** Where the entity with the id stands in the edition, or nothing where it holds none. */
+/**
+ * Where the entity with the id stands in the edition, or nothing where it holds none.
+ * @category Lookups
+ */
 export const pathIn = (edition, id) => {
     const trail = placesIn(edition).paths.get(id);
     return trail === undefined ? undefined : laidOut(trail);
 };
-/** Every id the edition gives an entity of its own, references left out. */
+/**
+ * Every id the edition gives an entity of its own, references left out.
+ * @category Lookups
+ */
 export const idsIn = (edition) => placesIn(edition).paths.keys();
-/** Where the edition references the id. */
+/**
+ * Where the edition references the id.
+ * @category Lookups
+ */
 export const linksTo = (edition, id) => (placesIn(edition).links.get(id) ?? []).map(laidOut);

package/lib/model/Agent.d.ts

@@ -1,6 +1,7 @@
 import { WithId } from "../shared/utils.js";
 /**
  * Something with a name and, where one exists, an authority record.
+ * @category Format types
  */
 export interface Named {
     /**
@@ -16,21 +17,38 @@ export interface Named {
      */
     sameAs: string[];
 }
+/**
+ * The parts an editor may take in the editorial work.
+ * @category Vocabulary
+ */
 export declare const editorialRoles: readonly ['editor', 'transcription', 'collation', 'encoding', 'commentary', 'proofreading'];
 /**
  * The part an editor took in the editorial work.
+ * @category Format types
  */
 export type EditorialRole = typeof editorialRoles[number];
-declare const nonEditorialRoles: readonly ['pianist', 'publisher'];
+/**
+ * The roles an agent may play in the context of the edition besides the
+ * editorial ones.
+ * @category Vocabulary
+ */
+export declare const nonEditorialRoles: readonly ['pianist', 'publisher'];
 /**
  * The role an agent plays in the context of the edition.
+ * @category Format types
  */
 export type AgentRole = EditorialRole | typeof nonEditorialRoles[number];
+/**
+ * Every role an agent may play in the context of the edition, those
+ * that are not editorial first.
+ * @category Vocabulary
+ */
 export declare const agentRoles: readonly AgentRole[];
 /**
  * A person or a group: a pianist, an editor, a publisher,
  * a manufacturer, a library.
  * @see crm:E39 Actor
+ * @category Format types
  */
 export interface Agent extends Named, Partial<WithId> {
     /**
@@ -41,10 +59,12 @@ export interface Agent extends Named, Partial<WithId> {
 }
 /**
  * An agent that is a person.
+ * @category Format types
  */
 export type Person = Agent;
 /**
  * A person who took part in preparing the edition.
+ * @category Format types
  */
 export interface Editor extends Person {
     /**
@@ -53,6 +73,10 @@ export interface Editor extends Person {
      */
     role: EditorialRole;
 }
+/**
+ * An activity that may name the person who carried it out.
+ * @category Format types
+ */
 export type WithActor = {
     /**
      * The person who carried out this activity.
@@ -63,6 +87,7 @@ export type WithActor = {
 /**
  * A place, e.g. a recording location, publishing location, etc.
  * @see crm:E53 Place
+ * @category Format types
  */
 export interface Place extends Named {
 }
@@ -76,6 +101,7 @@ export interface Place extends Named {
  * vocabulary does not have is given by name, which is then all there is
  * to go on.
  * @see crm:E55 Type
+ * @category Format types
  */
 export type Concept = (WithId & Partial<Named>) | (Named & Partial<WithId>);
 /**
@@ -83,6 +109,7 @@ export type Concept = (WithId & Partial<Named>) | (Named & Partial<WithId>);
  * read a recording into notes, the emulator that wrote a MIDI file, the
  * program that found the holes on a scan or aligned two copies.
  * @see crmdig:D14 Software
+ * @category Format types
  */
 export interface Software {
     /**
@@ -95,4 +122,3 @@ export interface Software {
      */
     version?: string;
 }
-export {};

package/lib/model/Agent.js

@@ -1,3 +1,7 @@
+/**
+ * The parts an editor may take in the editorial work.
+ * @category Vocabulary
+ */
 export const editorialRoles = [
     'editor',
     'transcription',
@@ -6,5 +10,15 @@ export const editorialRoles = [
     'commentary',
     'proofreading'
 ];
-const nonEditorialRoles = ['pianist', 'publisher'];
+/**
+ * The roles an agent may play in the context of the edition besides the
+ * editorial ones.
+ * @category Vocabulary
+ */
+export const nonEditorialRoles = ['pianist', 'publisher'];
+/**
+ * Every role an agent may play in the context of the edition, those
+ * that are not editorial first.
+ * @category Vocabulary
+ */
 export const agentRoles = [...nonEditorialRoles, ...editorialRoles];

package/lib/model/Assumption.d.ts

@@ -1,9 +1,15 @@
 import { WithNote, WithId } from "../shared/utils.js";
 import { Concept, Person, Software, WithActor } from "./Agent.js";
+/**
+ * The certainties a belief may be held with, from the most certain to
+ * the least.
+ * @category Vocabulary
+ */
 export declare const certainties: readonly ['true', 'likely', 'possible', 'unlikely', 'false'];
 /**
  * Certainty levels for beliefs, ranging from 'true' to 'false'
  * and some values in between.
+ * @category Format types
  */
 export type Certainty = typeof certainties[number];
 /**
@@ -11,14 +17,19 @@ export type Certainty = typeof certainties[number];
  * the edition is read as RDF. One held possible, unlikely or false is
  * only quoted, so that a reader who leaves the beliefs aside does not
  * take a doubted statement for the edition's own.
+ * @category Assumptions and beliefs
  */
 export declare const isAsserted: (certainty: Certainty) => boolean;
-/** The certainty a statement is held with. One that carries no belief is stated plainly, and so held true. */
+/**
+ * The certainty a statement is held with. One that carries no belief is stated plainly, and so held true.
+ * @category Assumptions and beliefs
+ */
 export declare const certaintyOf: (assumption: Readonly<Assumption>) => Certainty;
 /**
  * An argumentation provides reasons for a belief and
  * may be associated with a person carrying out that argumentation.
  * @see crminf:I1 Argumentation
+ * @category Format types
  */
 export interface Argumentation<T extends string = 'simpleArgumentation'> extends WithActor, WithNote {
     type: T;
@@ -29,6 +40,7 @@ export interface Argumentation<T extends string = 'simpleArgumentation'> extends
  * as an instruction to add or remove a perforation or as the dating
  * of the roll.
  * @see crminf:I16 Meaning Comprehension
+ * @category Format types
  */
 export interface MeaningComprehension extends Argumentation<'meaningComprehension'> {
     /**
@@ -41,6 +53,7 @@ export interface MeaningComprehension extends Argumentation<'meaningComprehensio
 /**
  * An inference draws a conclusion from given premises.
  * @see crminf:I5 Inference Making
+ * @category Format types
  */
 export interface Inference extends Argumentation<'inference'> {
     /**
@@ -64,6 +77,19 @@ export interface Inference extends Argumentation<'inference'> {
      * @see crm:P16 used specific object
      */
     used?: string[];
+    /**
+     * The rules the inference draws its conclusion by, by IRI: a
+     * regularity of how the rolls were edited, such as that the same
+     * addition at the same place is not made twice independently, a
+     * default, such as that copies were not made from two exemplars, or
+     * a method, such as how the tolerance of a collation is found. The
+     * rules are stated once where they are published, and each
+     * inference names those it follows, so that a reader can see what
+     * a conclusion rests on besides its premises, and which conclusions
+     * rest on a rule.
+     * @see crminf:J3 applied
+     */
+    applies?: string[];
 }
 /**
  * A belief adoption takes over someone else's belief without checking it:
@@ -76,6 +102,7 @@ export interface Inference extends Argumentation<'inference'> {
  * The editor's own beliefs need no adoption, wherever they are
  * published: an inference names them directly (see `Inference`).
  * @see crminf:I7 Belief Adoption
+ * @category Format types
  */
 export interface BeliefAdoption extends Argumentation<'beliefAdoption'> {
     /**
@@ -108,6 +135,7 @@ export interface BeliefAdoption extends Argumentation<'beliefAdoption'> {
  * later found wanting can be told from the rest. Naming software makes
  * it a digital measurement event in the sense of CRMdig.
  * @see crmsci:S21 Measurement
+ * @category Format types
  */
 export interface Measurement extends Argumentation<'measurement'> {
     /**
@@ -139,6 +167,7 @@ export interface Measurement extends Argumentation<'measurement'> {
  * An argumentation can be either a plain argumentation, a
  * meaning comprehension, an inference, a belief adoption or a
  * measurement.
+ * @category Format types
  */
 export type AnyArgumentation = MeaningComprehension | Inference | BeliefAdoption | Measurement | Argumentation;
 /**
@@ -146,6 +175,7 @@ export type AnyArgumentation = MeaningComprehension | Inference | BeliefAdoption
  * a statement) with a certainty. It comes into existence through
  * argumentations (reasons).
  * @see crminf:I2 Belief
+ * @category Format types
  */
 export interface Belief extends WithId {
     type: 'belief';
@@ -165,6 +195,7 @@ export interface Belief extends WithId {
  * `@annotation` element from JSON-LD-star. Any property in the edition
  * can be annotated with a belief to express uncertainty or provide
  * justification for the stated value.
+ * @category Format types
  */
 export interface Assumption {
     /**
@@ -184,6 +215,7 @@ export interface Assumption {
  * A value assumption wraps a literal value, e.g. a string, a number, a date, with an optional annotation.
  * Used for properties where the value itself may be uncertain,
  * e.g. dates.
+ * @category Format types
  */
 export interface ValueAssumption<ValueT> extends Assumption {
     /**
@@ -194,20 +226,24 @@ export interface ValueAssumption<ValueT> extends Assumption {
 /**
  * A reference assumption wraps a reference (by `@id`) with an optional annotation.
  * Used when pointing to another entity whose association may be uncertain.
+ * @category Format types
  */
 export type ReferenceAssumption = Assumption & WithId;
 /**
  * An object assumption wraps a complex object with an optional annotation.
  * Used for structured values (e.g. persons, conditions) whose properties
  * may be uncertain.
+ * @category Format types
  */
 export type ObjectAssumption<O extends object> = Assumption & O;
 /**
  * An actor assignment associates a person with an action.
  * It is an object assumption so that the attribution can be
  * annotated with a belief about its certainty.
+ * @category Format types
  */
 export type ActorAssignment = ObjectAssumption<Person>;
+/** @inline */
 interface DateWithin {
     /**
      * The day the event falls within.
@@ -216,6 +252,7 @@ interface DateWithin {
      */
     within: Date;
 }
+/** @inline */
 interface DateAfter {
     /**
      * The earliest day the event can have happened on: it did not
@@ -232,6 +269,7 @@ interface DateAfter {
      */
     before?: Date;
 }
+/** @inline */
 interface DateBefore {
     /**
      * The earliest day the event can have happened on: it did not
@@ -253,6 +291,7 @@ interface DateBefore {
  * lies between. A bound nobody can give is left out, so `after` alone
  * says "not before".
  * @see crm:E52 Time-Span
+ * @category Format types
  */
 export type TimeSpan = DateWithin | DateAfter | DateBefore;
 /**
@@ -261,25 +300,75 @@ export type TimeSpan = DateWithin | DateAfter | DateBefore;
  * day it falls `within`, or the bounds it lies between. A bound nobody
  * can give is left out, so `after` alone says "not before".
  * @see crm:E52 Time-Span
+ * @category Format types
  */
 export type DateAssignment = Assumption & TimeSpan;
+/**
+ * The value the assumption holds, without the belief about it.
+ * @category Assumptions and beliefs
+ */
 export declare function valueOf<ValueT>(assumption: ValueAssumption<ValueT>): ValueT;
+/**
+ * The values the assumptions hold, in their order.
+ * @category Assumptions and beliefs
+ */
 export declare function valuesOf<ValueT>(assumptions: ValueAssumption<ValueT>[]): ValueT[];
+/**
+ * The id of the entity the reference points to.
+ * @category Lookups
+ */
 export declare function idOf(assumption: ReferenceAssumption): string;
+/**
+ * The ids of the entities the references point to, in their order.
+ * @category Lookups
+ */
 export declare function idsOf(assumptions: ReferenceAssumption[]): string[];
+/**
+ * The value stated plainly: an assumption that carries no belief, and
+ * so is held true.
+ * @category Assumptions and beliefs
+ */
 export declare function assignValue<ValueT>(value: ValueT): ValueAssumption<ValueT>;
+/**
+ * A reference to the entity with the id, stated plainly: an assumption
+ * that carries no belief, and so is held true.
+ * @category Assumptions and beliefs
+ */
 export declare function assignReference(id: string): ReferenceAssumption;
+/**
+ * The object stated plainly: an assumption that carries no belief, and
+ * so is held true. The object given is copied rather than changed.
+ * @category Assumptions and beliefs
+ */
 export declare function assignObject<O extends object>(obj: O): ObjectAssumption<O>;
-/** A date the edition states: the day the event falls within. */
+/**
+ * A date the edition states: the day the event falls within.
+ * @category Assumptions and beliefs
+ */
 export declare const assignDate: (within: Date) => DateAssignment;
-/** A date the edition can only bound from below, as in "not before 1924". */
+/**
+ * A date the edition can only bound from below, as in "not before 1924".
+ * @category Assumptions and beliefs
+ */
 export declare const notBefore: (after: Date) => DateAssignment;
-/** A date the edition can only bound from above. */
+/**
+ * A date the edition can only bound from above.
+ * @category Assumptions and beliefs
+ */
 export declare const notAfter: (before: Date) => DateAssignment;
-/** The day the event falls within, where the edition states one. */
+/**
+ * The day the event falls within, where the edition states one.
+ * @category Assumptions and beliefs
+ */
 export declare const dateOf: (assignment: DateAssignment) => Date | undefined;
-/** The earliest the event can have happened, as far as the edition states it. */
+/**
+ * The earliest the event can have happened, as far as the edition states it.
+ * @category Assumptions and beliefs
+ */
 export declare const earliestOf: (assignment: DateAssignment) => Date | undefined;
-/** The latest the event can have happened, as far as the edition states it. */
+/**
+ * The latest the event can have happened, as far as the edition states it.
+ * @category Assumptions and beliefs
+ */
 export declare const latestOf: (assignment: DateAssignment) => Date | undefined;
 export {};

package/lib/model/Assumption.js

@@ -1,3 +1,8 @@
+/**
+ * The certainties a belief may be held with, from the most certain to
+ * the least.
+ * @category Vocabulary
+ */
 export const certainties = [
     'true',
     'likely',
@@ -10,46 +15,99 @@ export const certainties = [
  * the edition is read as RDF. One held possible, unlikely or false is
  * only quoted, so that a reader who leaves the beliefs aside does not
  * take a doubted statement for the edition's own.
+ * @category Assumptions and beliefs
  */
 export const isAsserted = (certainty) => certainty === 'true' || certainty === 'likely';
-/** The certainty a statement is held with. One that carries no belief is stated plainly, and so held true. */
+/**
+ * The certainty a statement is held with. One that carries no belief is stated plainly, and so held true.
+ * @category Assumptions and beliefs
+ */
 export const certaintyOf = (assumption) => assumption['@annotation']?.belief.certainty ?? 'true';
+/**
+ * The value the assumption holds, without the belief about it.
+ * @category Assumptions and beliefs
+ */
 export function valueOf(assumption) {
     return assumption['@value'];
 }
+/**
+ * The values the assumptions hold, in their order.
+ * @category Assumptions and beliefs
+ */
 export function valuesOf(assumptions) {
     return assumptions.map(a => a['@value']);
 }
+/**
+ * The id of the entity the reference points to.
+ * @category Lookups
+ */
 export function idOf(assumption) {
     return assumption.id;
 }
+/**
+ * The ids of the entities the references point to, in their order.
+ * @category Lookups
+ */
 export function idsOf(assumptions) {
     return assumptions.map(a => a.id);
 }
+/**
+ * The value stated plainly: an assumption that carries no belief, and
+ * so is held true.
+ * @category Assumptions and beliefs
+ */
 export function assignValue(value) {
     return {
         '@value': value
     };
 }
+/**
+ * A reference to the entity with the id, stated plainly: an assumption
+ * that carries no belief, and so is held true.
+ * @category Assumptions and beliefs
+ */
 export function assignReference(id) {
     return {
         id
     };
 }
+/**
+ * The object stated plainly: an assumption that carries no belief, and
+ * so is held true. The object given is copied rather than changed.
+ * @category Assumptions and beliefs
+ */
 export function assignObject(obj) {
     return {
         ...obj
     };
 }
-/** A date the edition states: the day the event falls within. */
+/**
+ * A date the edition states: the day the event falls within.
+ * @category Assumptions and beliefs
+ */
 export const assignDate = (within) => ({ within });
-/** A date the edition can only bound from below, as in "not before 1924". */
+/**
+ * A date the edition can only bound from below, as in "not before 1924".
+ * @category Assumptions and beliefs
+ */
 export const notBefore = (after) => ({ after });
-/** A date the edition can only bound from above. */
+/**
+ * A date the edition can only bound from above.
+ * @category Assumptions and beliefs
+ */
 export const notAfter = (before) => ({ before });
-/** The day the event falls within, where the edition states one. */
+/**
+ * The day the event falls within, where the edition states one.
+ * @category Assumptions and beliefs
+ */
 export const dateOf = (assignment) => 'within' in assignment ? assignment.within : undefined;
-/** The earliest the event can have happened, as far as the edition states it. */
+/**
+ * The earliest the event can have happened, as far as the edition states it.
+ * @category Assumptions and beliefs
+ */
 export const earliestOf = (assignment) => 'within' in assignment ? assignment.within : assignment.after;
-/** The latest the event can have happened, as far as the edition states it. */
+/**
+ * The latest the event can have happened, as far as the edition states it.
+ * @category Assumptions and beliefs
+ */
 export const latestOf = (assignment) => 'within' in assignment ? assignment.within : assignment.before;

package/lib/model/ConditionState.d.ts

@@ -3,6 +3,7 @@
  * of a feature on the roll (e.g. a damaged
  * or unsuccessful perforation).
  * @see crm:E3 Condition State
+ * @category Format types
  */
 export interface ConditionState<T extends string> {
     /**

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 {
     /**
@@ -146,7 +150,7 @@ export interface Edition {
      * best, since its places are what notes and readers cite. Left out,
      * it is the first copy with features that is not aligned
      * (`referenceCopyOf`).
-     * Not exported to RDF.
+     * @see reo:referenceCopy
      */
     referenceCopy?: string;
     /**
@@ -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);