linked-rolls 0.70.0 → 0.71.0

package/lib/collation/statistics.js

@@ -9,7 +9,10 @@ import { quantity } from "../model/Quantity.js";
  * stood out; a median and a median absolute deviation leave them out of
  * account.
  */
-/** The middle of a sample, the mean of the two middle values where it has an even number of them. */
+/**
+ * The middle of a sample, the mean of the two middle values where it has an even number of them.
+ * @internal
+ */
 export const medianOf = (values) => {
     if (values.length === 0)
         return undefined;
@@ -21,7 +24,10 @@ export const medianOf = (values) => {
 };
 /** What the median absolute deviation must be multiplied by to estimate the standard deviation of a normal sample. */
 const MAD_TO_SIGMA = 1.4826;
-/** Where the sample sits and how far it scatters, or nothing for an empty sample. */
+/**
+ * Where the sample sits and how far it scatters, or nothing for an empty sample.
+ * @internal
+ */
 export const spreadOf = (values) => {
     const median = medianOf(values);
     if (median === undefined)
@@ -33,7 +39,10 @@ export const spreadOf = (values) => {
         sigma: quantity(MAD_TO_SIGMA * (medianOf(deviations) ?? 0))
     };
 };
-/** How far the value lies from the centre of the spread, in units of its scatter. */
+/**
+ * How far the value lies from the centre of the spread, in units of its scatter.
+ * @internal
+ */
 export const standardise = (value, spread) => (value - spread.median) / spread.sigma;
 /** The complementary error function, after Press et al., whose fractional error stays below 1.2e-7. */
 const erfc = (x) => {
@@ -44,9 +53,15 @@ const erfc = (x) => {
             t * (-0.82215223 + t * 0.17087277)))))))));
     return x >= 0 ? tail : 2 - tail;
 };
-/** The share of a normal sample lying below `z` standard deviations. */
+/**
+ * The share of a normal sample lying below `z` standard deviations.
+ * @internal
+ */
 export const normalBelow = (z) => erfc(-z / Math.SQRT2) / 2;
-/** The share of a normal sample lying further than `z` standard deviations from its centre, on either side. */
+/**
+ * The share of a normal sample lying further than `z` standard deviations from its centre, on either side.
+ * @internal
+ */
 export const normalBeyond = (z) => erfc(z / Math.SQRT2);
 const horner = (coefficients, x) => coefficients.reduce((total, coefficient) => total * x + coefficient, 0);
 const CENTRAL_NUMERATOR = [
@@ -74,6 +89,7 @@ const tailQuantile = (share) => {
  * How many standard deviations out the given share of a normal sample
  * lies below, after Acklam's rational approximation, whose relative
  * error stays below 1.15e-9. The inverse of `normalBelow`.
+ * @internal
  */
 export const normalQuantile = (share) => {
     if (share <= 0)
@@ -92,9 +108,13 @@ export const normalQuantile = (share) => {
  * How much heavier the tails of a standardised sample are than a normal
  * sample's. Zero for a normal shape, positive where more of the sample
  * lies far out than the curve allows.
+ * @internal
  */
 export const excessKurtosisOf = (standardised) => standardised.reduce((total, z) => total + z ** 4, 0) / standardised.length - 3;
-/** What the sample puts beyond the given distance, against what a normal sample would. */
+/**
+ * What the sample puts beyond the given distance, against what a normal sample would.
+ * @internal
+ */
 export const tailOf = (standardised, beyond) => ({
     beyond,
     observed: standardised.filter(z => Math.abs(z) > beyond).length,
@@ -104,6 +124,7 @@ export const tailOf = (standardised, beyond) => ({
  * The sample counted into bins of the given width, laid out on
  * multiples of that width so that two histograms of one width share
  * their bounds. Nothing for an empty sample or a width of nothing.
+ * @internal
  */
 export const histogramOf = (values, binWidth) => {
     if (values.length === 0 || binWidth <= 0)

package/lib/collation/substitution.d.ts

@@ -8,11 +8,13 @@ export type { Operation, Spelling } from "../systems/TrackerBar.js";
  * nothing for a word no bar here knows or one without a counterpart in
  * another scale. The bars share their words where they share a scale,
  * as the Licensee does the T-100's, so the first that reads it answers.
+ * @category Systems and emulation
  */
 export declare const operationOf: (expressionType: string) => Operation | undefined;
 /**
  * A latched function of the older version and the held command of the
  * newer one that stands for it.
+ * @category Collation and alignment
  */
 export interface Substitution {
     /** The command that turned the function on, and the one that cancelled it. */
@@ -30,6 +32,7 @@ export interface Substitution {
  * command. The T-98 punches a hold as a chain of round holes on a
  * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
  * by hole shows a run where the paper shows one command.
+ * @category Collation and alignment
  */
 export declare const defaultChainGap: import("../index.js").Quantity<"mm">;
 /**
@@ -42,6 +45,7 @@ export declare const defaultChainGap: import("../index.js").Quantity<"mm">;
  * the green bar, so drawing it as a perforation is out of the question,
  * but an edit still has to be shown somewhere, and the lane the green
  * scale gives the same function is where it belongs.
+ * @internal
  */
 export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expression) => Track | undefined;
 /**
@@ -54,5 +58,6 @@ export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expressio
  * reported and the editor is left to say what happened. Nothing is
  * invented either: both sides are perforations somebody punched, and all
  * this asserts is which stands for which.
+ * @category Collation and alignment
  */
 export declare const substitutionsBetween: (own: readonly AnySymbol[], inherited: readonly AnySymbol[], locate: Locate, tolerance?: CollationTolerance, chainGap?: Millimeters) => Substitution[];

package/lib/collation/substitution.js

@@ -6,6 +6,7 @@ import { trackerBars } from "../systems/index.js";
  * nothing for a word no bar here knows or one without a counterpart in
  * another scale. The bars share their words where they share a scale,
  * as the Licensee does the T-100's, so the first that reads it answers.
+ * @category Systems and emulation
  */
 export const operationOf = (expressionType) => {
     for (const bar of trackerBars) {
@@ -20,6 +21,7 @@ export const operationOf = (expressionType) => {
  * command. The T-98 punches a hold as a chain of round holes on a
  * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
  * by hole shows a run where the paper shows one command.
+ * @category Collation and alignment
  */
 export const defaultChainGap = mm(3);
 const isExpression = (symbol) => symbol.type === 'expression';
@@ -35,6 +37,7 @@ const functionKey = (symbol, operation) => operation.sided ? `${operation.operat
  * the green bar, so drawing it as a perforation is out of the question,
  * but an edit still has to be shown somewhere, and the lane the green
  * scale gives the same function is where it belongs.
+ * @internal
  */
 export const positionOfSameFunction = (bar, symbol) => {
     const wanted = operationOf(symbol.expressionType);
@@ -132,6 +135,7 @@ const theOnly = (items) => items.length === 1 ? items[0] : undefined;
  * reported and the editor is left to say what happened. Nothing is
  * invented either: both sides are perforations somebody punched, and all
  * this asserts is which stands for which.
+ * @category Collation and alignment
  */
 export const substitutionsBetween = (own, inherited, locate, tolerance = defaultCollationTolerance, chainGap = defaultChainGap) => {
     const latched = latchedIn(inherited, locate);

package/lib/emulation/Emulation.d.ts

@@ -4,6 +4,10 @@ import { Version } from "../model/Version.js";
 import { AnyPerformedRollFeature, EmulatedCurve, NegotiatedEvent, ReproducingSystem } from "../systems/ReproducingSystem.js";
 import { Millimeters } from "../model/Quantity.js";
 import { Edition } from "../model/Edition.js";
+/**
+ * Which part of a version `emulate` plays, and where its clock starts.
+ * @category Systems and emulation
+ */
 export type EmulationScope = {
     /** Only notes whose onset lies within this span of the roll are played. */
     range?: [Millimeters, Millimeters];
@@ -15,15 +19,20 @@ export type EmulationScope = {
  * left as they were. The edition supplies the copies, whose measurements
  * decide how far before or after its reference a command goes, and a
  * punch diameter, or a millimetre, where no copy agrees with a statement.
+ * @category Systems and emulation
  */
 export declare const withPlacementsApplied: (edition: Edition, events: readonly NegotiatedEvent[]) => NegotiatedEvent[];
 /**
  * The commands of a version as the bar performs them, in order of place,
  * within the scope and with the placements applied. A note plays only
  * where its onset falls in the range; expressions play throughout.
+ * @category Systems and emulation
  */
 export declare const negotiatedEventsOf: (edition: Edition, version: Readonly<Version>, bar: TrackerBar, { range }?: Pick<EmulationScope, 'range'>) => NegotiatedEvent[];
-/** A version performed: what was negotiated, and what the system made of it. */
+/**
+ * A version performed: what was negotiated, and what the system made of it.
+ * @category Systems and emulation
+ */
 export interface Emulated {
     /** The id of the version performed. */
     readonly source: string;
@@ -35,18 +44,21 @@ export interface Emulated {
 /**
  * Performs a version on a reproducing system: the symbols are negotiated
  * into placed events and the system plays them. Nothing given is changed.
+ * @category Systems and emulation
  */
 export declare const emulate: <Options extends object>(system: ReproducingSystem<Options>, version: Readonly<Version>, edition: Edition, options?: Options, { range, skipToFirstNote }?: EmulationScope) => Emulated;
 /**
  * The performed events as a MIDI file, in which every note and pedal step
  * is labelled with the symbol it performs. The file names the system, the
  * version and the options it was played with.
+ * @category Systems and emulation
  */
 export declare const midiOf: (events: readonly AnyPerformedRollFeature[], systemName: string, options: object, source?: string) => MidiFile;
 /**
  * A version of the edition, performed and kept: `emulate` and `midiOf`
  * with the result held on the object between the two calls. Prefer the
  * functions where nothing needs holding.
+ * @category Systems and emulation
  */
 export declare class Emulation<Options extends object> {
     readonly system: ReproducingSystem<Options>;
@@ -58,7 +70,10 @@ export declare class Emulation<Options extends object> {
     constructor(system: ReproducingSystem<Options>, options?: Options);
     /** Moves the negotiated events to where their statements put them; see `withPlacementsApplied`. */
     applyConstraints(edition: Edition): void;
+    /** Performs the version, keeps what came of it, and returns the performed events; see `emulate`. */
     emulateVersion(version: Version, edition: Edition, scope?: EmulationScope): AnyPerformedRollFeature[];
+    /** The performed events that sound or follow from the symbol with the id. */
     findEventsPerforming(id: string): AnyPerformedRollFeature[];
+    /** The performed events as a MIDI file; see `midiOf`. */
     asMIDI(): MidiFile;
 }

package/lib/emulation/Emulation.js

@@ -151,6 +151,7 @@ const earliestOf = (times) => times.length === 0 ? seconds(0) : times.reduce((so
  * left as they were. The edition supplies the copies, whose measurements
  * decide how far before or after its reference a command goes, and a
  * punch diameter, or a millimetre, where no copy agrees with a statement.
+ * @category Systems and emulation
  */
 export const withPlacementsApplied = (edition, events) => {
     const gap = meanPunchDiameterOf(edition) ?? mm(1);
@@ -168,6 +169,7 @@ export const withPlacementsApplied = (edition, events) => {
  * The commands of a version as the bar performs them, in order of place,
  * within the scope and with the placements applied. A note plays only
  * where its onset falls in the range; expressions play throughout.
+ * @category Systems and emulation
  */
 export const negotiatedEventsOf = (edition, version, bar, { range } = {}) => {
     const inScope = (event) => !range || event.type !== 'note' || (event.horizontal.from > range[0] && event.horizontal.from < range[1]);
@@ -180,6 +182,7 @@ export const negotiatedEventsOf = (edition, version, bar, { range } = {}) => {
 /**
  * Performs a version on a reproducing system: the symbols are negotiated
  * into placed events and the system plays them. Nothing given is changed.
+ * @category Systems and emulation
  */
 export const emulate = (system, version, edition, options = system.defaultOptions, { range, skipToFirstNote = false } = {}) => {
     const negotiated = negotiatedEventsOf(edition, version, system.trackerBar, { range });
@@ -202,6 +205,7 @@ export const emulate = (system, version, edition, options = system.defaultOption
  * The performed events as a MIDI file, in which every note and pedal step
  * is labelled with the symbol it performs. The file names the system, the
  * version and the options it was played with.
+ * @category Systems and emulation
  */
 export const midiOf = (events, systemName, options, source) => {
     const TICKS_PER_SECOND = 1000;
@@ -262,6 +266,8 @@ export const midiOf = (events, systemName, options, source) => {
             midi.push(controller(controllerOf(event), event.value, labelled ? deltaTime : 0));
         }
     }
+    // a standard MIDI file ends every track with this event
+    midi.push({ type: 'meta', subtype: 'endOfTrack', deltaTime: 0 });
     return {
         header: {
             ticksPerBeat: TICKS_PER_SECOND,
@@ -275,6 +281,7 @@ export const midiOf = (events, systemName, options, source) => {
  * A version of the edition, performed and kept: `emulate` and `midiOf`
  * with the result held on the object between the two calls. Prefer the
  * functions where nothing needs holding.
+ * @category Systems and emulation
  */
 export class Emulation {
     constructor(system, options = system.defaultOptions) {
@@ -322,6 +329,7 @@ export class Emulation {
     applyConstraints(edition) {
         this.negotiatedEvents = withPlacementsApplied(edition, this.negotiatedEvents);
     }
+    /** Performs the version, keeps what came of it, and returns the performed events; see `emulate`. */
     emulateVersion(version, edition, scope = {}) {
         const emulated = emulate(this.system, version, edition, this.options, scope);
         this.source = emulated.source;
@@ -330,9 +338,11 @@ export class Emulation {
         this.midiEvents = [...emulated.events];
         return this.midiEvents;
     }
+    /** The performed events that sound or follow from the symbol with the id. */
     findEventsPerforming(id) {
         return this.midiEvents.filter(event => event.performs.id === id);
     }
+    /** The performed events as a MIDI file; see `midiOf`. */
     asMIDI() {
         return midiOf(this.midiEvents, this.system.name, this.options, this.source);
     }

package/lib/emulation/negotiation.d.ts

@@ -10,5 +10,6 @@ import { Edition } from "../model/Edition.js";
  * transfer between systems leaves behind: a red `ForzandoOn` a
  * green version still inherits cannot be performed on a green
  * machine, and an edit has yet to say what took its place.
+ * @category Systems and emulation
  */
 export declare const negotiatedEventOf: (edition: Edition, symbol: Note | Expression, bar: TrackerBar) => NegotiatedEvent | null;

package/lib/emulation/negotiation.js

@@ -7,6 +7,7 @@ import { placeOf } from "../analysis/text.js";
  * transfer between systems leaves behind: a red `ForzandoOn` a
  * green version still inherits cannot be performed on a green
  * machine, and an edit has yet to say what took its place.
+ * @category Systems and emulation
  */
 export const negotiatedEventOf = (edition, symbol, bar) => {
     const horizontal = placeOf(edition, symbol);

package/lib/index.d.ts

@@ -1,11 +1,41 @@
 /**
+ * Digital editions of piano rolls: reading an edition and writing it out
+ * as JSON-LD, finding what it holds, changing it through operations on
+ * an immer draft, reading copies from scans and analysis files,
+ * collating them into versions, and working out what the edition can
+ * and cannot vouch for. The reproducing systems that play a version are
+ * entry points of their own, so that the emulator they need is loaded
+ * only where it is wanted.
+ *
  * The public interface of the library. Everything else under lib/ is its
  * implementation and may change in any release: the in-place helpers the
  * operations are built from, the date conversions of the serialisation,
- * and the general utilities.
+ * and the general utilities. So may the exports tagged `@internal`,
+ * which the API reference leaves out.
+ *
+ * @module linked-rolls
+ *
+ * @categoryDescription Format types
+ * The types of an edition. They are documented field by field, with the
+ * ontology terms each field maps to, in the
+ * [format reference](https://pfefferniels.github.io/linked-rolls/); they
+ * are listed here so that the signatures can link to them.
+ *
+ * @categoryDescription Units
+ * A quantity is a plain number at runtime; its unit lives in its type, so
+ * that a length in millimetres cannot be passed where one in pixels is
+ * wanted. The constructors make a number into a quantity.
  */
 export type { WithId, WithNote, WithType } from './shared/utils.js';
 export * from './model/Quantity.js';
+/**
+ * A number in a unit, the unit carried in the type alone: at runtime it
+ * is the plain number it was made from. A number becomes a quantity only
+ * through a constructor such as `mm` or `track`, and a quantity in one
+ * unit cannot stand in for one in another.
+ * @category Units
+ */
+export type { Quantity } from './model/Quantity.js';
 export * from './model/Agent.js';
 export * from './model/Assumption.js';
 export * from './model/ConditionState.js';
@@ -41,7 +71,8 @@ export * from './emulation/negotiation.js';
 export * from './collation/scatter.js';
 export * from './ops/index.js';
 export * from './emulation/Emulation.js';
-export * from './validate.js';
+/** @category Reading and writing */
+export { validate, type ValidateEdition } from './validate.js';
 export * from './analysis/constraints.js';
 export * from './collation/substitution.js';
 export * from './io/context.js';

package/lib/index.js

@@ -34,7 +34,8 @@ export * from './emulation/negotiation.js';
 export * from './collation/scatter.js';
 export * from './ops/index.js';
 export * from './emulation/Emulation.js';
-export * from './validate.js';
+/** @category Reading and writing */
+export { validate } from './validate.js';
 export * from './analysis/constraints.js';
 export * from './collation/substitution.js';
 export * from './io/context.js';

package/lib/io/asJsonLd.d.ts

@@ -5,4 +5,14 @@ import { Edition } from "../model/Edition.js";
  */
 export declare const derivedKeys: ReadonlySet<string>;
 export declare const exportDate: (date: Date) => string;
+/**
+ * Writes the edition as a JSON-LD document in the terms of the Roll
+ * Edition Ontology. Each copy's features and tears go back to the
+ * copy's own places, as they were read, with the alignment beside them,
+ * and every version carries the context of its own reproducing system.
+ * A reference the edition holds possible, unlikely or false is quoted
+ * rather than stated, so that a reader of the RDF does not take it for
+ * a fact. The edition given is not changed.
+ * @category Reading and writing
+ */
 export declare const asJsonLd: (edition: Edition) => any;

package/lib/io/asJsonLd.js

@@ -160,6 +160,16 @@ const withDoubtedReferencesQuoted = (value, quoted) => {
 const atOwnPlacesAll = (edition) => edition.copies.some(copy => copy.measurements.alignment)
     ? { ...edition, copies: edition.copies.map(atOwnPlaces) }
     : edition;
+/**
+ * Writes the edition as a JSON-LD document in the terms of the Roll
+ * Edition Ontology. Each copy's features and tears go back to the
+ * copy's own places, as they were read, with the alignment beside them,
+ * and every version carries the context of its own reproducing system.
+ * A reference the edition holds possible, unlikely or false is quoted
+ * rather than stated, so that a reader of the RDF does not take it for
+ * a fact. The edition given is not changed.
+ * @category Reading and writing
+ */
 export const asJsonLd = (edition) => {
     const quoted = [];
     const node = withDoubtedReferencesQuoted(withSystemContexts(withCreations(withChanges(asJsonLdEntity(atOwnPlacesAll(edition))))), quoted);

package/lib/io/context.d.ts

@@ -1,12 +1,26 @@
+/**
+ * The JSON-LD context of the format, which an exported edition names by
+ * its address, `https://w3id.org/reo/context.jsonld`: it maps the keys of
+ * the document onto the Roll Edition Ontology, CIDOC CRM, LRMoo and
+ * CRMinf.
+ * @category Reading and writing
+ */
 export { default as jsonLdContext } from '../spec/context.json';
-/** The context of the Welte-Mignon T-100, added to a version coded for it. */
+/**
+ * The context of the Welte-Mignon T-100, added to a version coded for it.
+ * @category Reading and writing
+ */
 export { default as welteT100JsonLdContext } from '../spec/welte-t100.context.json';
 /**
  * The context of the Welte-Mignon Licensee. Its expression terms are
  * the T-100's, the two systems differing in the tracker scale rather
  * than in the coding, so it reads them out of the T-100's vocabulary
  * rather than minting a second set of IRIs for the same commands.
+ * @category Reading and writing
  */
 export { default as welteLicenseeJsonLdContext } from '../spec/welte-licensee.context.json';
-/** The context of the Welte-Mignon T-98, added to an edition of a green roll. */
+/**
+ * The context of the Welte-Mignon T-98, added to an edition of a green roll.
+ * @category Reading and writing
+ */
 export { default as welteT98JsonLdContext } from '../spec/welte-t98.context.json';

package/lib/io/context.js

@@ -1,12 +1,26 @@
+/**
+ * The JSON-LD context of the format, which an exported edition names by
+ * its address, `https://w3id.org/reo/context.jsonld`: it maps the keys of
+ * the document onto the Roll Edition Ontology, CIDOC CRM, LRMoo and
+ * CRMinf.
+ * @category Reading and writing
+ */
 export { default as jsonLdContext } from '../spec/context.json' with { type: 'json' };
-/** The context of the Welte-Mignon T-100, added to a version coded for it. */
+/**
+ * The context of the Welte-Mignon T-100, added to a version coded for it.
+ * @category Reading and writing
+ */
 export { default as welteT100JsonLdContext } from '../spec/welte-t100.context.json' with { type: 'json' };
 /**
  * The context of the Welte-Mignon Licensee. Its expression terms are
  * the T-100's, the two systems differing in the tracker scale rather
  * than in the coding, so it reads them out of the T-100's vocabulary
  * rather than minting a second set of IRIs for the same commands.
+ * @category Reading and writing
  */
 export { default as welteLicenseeJsonLdContext } from '../spec/welte-licensee.context.json' with { type: 'json' };
-/** The context of the Welte-Mignon T-98, added to an edition of a green roll. */
+/**
+ * The context of the Welte-Mignon T-98, added to an edition of a green roll.
+ * @category Reading and writing
+ */
 export { default as welteT98JsonLdContext } from '../spec/welte-t98.context.json' with { type: 'json' };

package/lib/io/importJsonLd.d.ts

@@ -5,6 +5,7 @@ type Json = any;
  * Reads an edition. A document holds each copy's features and tears at
  * the copy's own places, as they were read; the edition holds them on
  * its axis, which is where the copy's alignment carries them.
+ * @category Reading and writing
  */
 export declare const importJsonLd: (json: Json) => Edition;
 export {};

package/lib/io/importJsonLd.js

@@ -133,6 +133,7 @@ const withQuotedStatementsInPlace = (edition) => {
  * Reads an edition. A document holds each copy's features and tears at
  * the copy's own places, as they were read; the edition holds them on
  * its axis, which is where the copy's alignment carries them.
+ * @category Reading and writing
  */
 export const importJsonLd = (json) => {
     const { '@context': context, ...document } = withoutEmptyCreations(withPlainCopyIds(migrate(withQuotedStatementsInPlace(json))));

package/lib/io/migrate.d.ts

@@ -13,5 +13,13 @@
 type Json = any;
 /** A copy's id without the `copy/` that documents of earlier releases put before it. */
 export declare const plainCopyId: (id: string) => string;
+/**
+ * Brings the JSON of an edition written by an earlier release of the
+ * format up to the current shape. A document that is current already
+ * passes through unchanged, and one may be migrated any number of
+ * times. `importJsonLd` migrates what it reads, so this is needed only
+ * to look at an old document as JSON.
+ * @category Reading and writing
+ */
 export declare const migrate: (edition: Json) => Json;
 export {};

package/lib/io/migrate.js

@@ -677,4 +677,12 @@ const withReferenceCopy = (edition) => {
         : edition;
 };
 const editionSteps = [withoutFormatVersion, withoutTempoAdjustment, withoutEditionType, withSystems, withEditors, withDerivationTolerance, withReferenceCopy];
+/**
+ * Brings the JSON of an edition written by an earlier release of the
+ * format up to the current shape. A document that is current already
+ * passes through unchanged, and one may be migrated any number of
+ * times. `importJsonLd` migrates what it reads, so this is needed only
+ * to look at an old document as JSON.
+ * @category Reading and writing
+ */
 export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/lookup/lookup.d.ts

@@ -10,17 +10,40 @@ import { NestedFeature } from "../model/Feature.js";
 import { AnySymbol } from "../model/Symbol.js";
 import { Version } from "../model/Version.js";
 import { Modification, ProductionEvent, RollCopy } from "../model/RollCopy.js";
+/**
+ * The version with the id, where the edition holds one.
+ * @category Lookups
+ */
 export declare const versionIn: (edition: Pick<Edition, 'versions'>, id: string) => Readonly<Version> | undefined;
+/**
+ * The copy with the id, where the edition holds one.
+ * @category Lookups
+ */
 export declare const copyIn: (edition: Pick<Edition, 'copies'>, id: string) => Readonly<RollCopy> | undefined;
-/** A symbol any version inserts. */
+/**
+ * A symbol any version inserts.
+ * @category Lookups
+ */
 export declare const symbolIn: (edition: Pick<Edition, 'versions'>, id: string) => Readonly<AnySymbol> | undefined;
-/** The symbols under the ids, leaving out an id that names none. */
+/**
+ * The symbols under the ids, leaving out an id that names none.
+ * @category Lookups
+ */
 export declare const symbolsIn: (edition: Pick<Edition, 'versions'>, ids: readonly string[]) => Readonly<AnySymbol>[];
-/** A feature or a patch on any copy, one a patch bears included. */
+/**
+ * A feature or a patch on any copy, one a patch bears included.
+ * @category Lookups
+ */
 export declare const featureIn: (edition: Pick<Edition, 'copies'>, id: string) => Readonly<NestedFeature> | undefined;
-/** The features and patches under the ids, leaving out an id that names none. */
+/**
+ * The features and patches under the ids, leaving out an id that names none.
+ * @category Lookups
+ */
 export declare const featuresIn: (edition: Pick<Edition, 'copies'>, ids: readonly string[]) => Readonly<NestedFeature>[];
-/** The copy a feature sits on, a patch and everything it bears included. */
+/**
+ * The copy a feature sits on, a patch and everything it bears included.
+ * @category Lookups
+ */
 export declare const copyOfFeature: (edition: Pick<Edition, 'copies'>, featureId: string) => Readonly<RollCopy> | undefined;
 /**
  * The act a copy states a feature in: the production event that
@@ -28,5 +51,6 @@ export declare const copyOfFeature: (edition: Pick<Edition, 'copies'>, featureId
  * a patch bears came onto the copy with the patch, so the act is
  * the one that glued the patch on. Two features stand in one act
  * where this returns the very same object.
+ * @category Lookups
  */
 export declare const actOf: (edition: Pick<Edition, 'copies'>, featureId: string) => Readonly<ProductionEvent | Modification> | undefined;

package/lib/lookup/lookup.js

@@ -10,17 +10,40 @@ const symbolsById = perState((edition) => byIdIn(edition.versions.flatMap(insert
 const featuresOnCopies = (edition) => edition.copies.flatMap(copy => featuresOf(copy).flatMap(withBorneFeatures).map(feature => ({ feature, copy })));
 const featuresById = perState((edition) => new Map(featuresOnCopies(edition).map(({ feature }) => [feature.id, feature])));
 const copiesByFeature = perState((edition) => new Map(featuresOnCopies(edition).map(({ feature, copy }) => [feature.id, copy])));
+/**
+ * The version with the id, where the edition holds one.
+ * @category Lookups
+ */
 export const versionIn = (edition, id) => versionsById(edition).get(id);
+/**
+ * The copy with the id, where the edition holds one.
+ * @category Lookups
+ */
 export const copyIn = (edition, id) => copiesById(edition).get(id);
-/** A symbol any version inserts. */
+/**
+ * A symbol any version inserts.
+ * @category Lookups
+ */
 export const symbolIn = (edition, id) => symbolsById(edition).get(id);
-/** The symbols under the ids, leaving out an id that names none. */
+/**
+ * The symbols under the ids, leaving out an id that names none.
+ * @category Lookups
+ */
 export const symbolsIn = (edition, ids) => ids.flatMap(id => symbolIn(edition, id) ?? []);
-/** A feature or a patch on any copy, one a patch bears included. */
+/**
+ * A feature or a patch on any copy, one a patch bears included.
+ * @category Lookups
+ */
 export const featureIn = (edition, id) => featuresById(edition).get(id);
-/** The features and patches under the ids, leaving out an id that names none. */
+/**
+ * The features and patches under the ids, leaving out an id that names none.
+ * @category Lookups
+ */
 export const featuresIn = (edition, ids) => ids.flatMap(id => featureIn(edition, id) ?? []);
-/** The copy a feature sits on, a patch and everything it bears included. */
+/**
+ * The copy a feature sits on, a patch and everything it bears included.
+ * @category Lookups
+ */
 export const copyOfFeature = (edition, featureId) => copiesByFeature(edition).get(featureId);
 /**
  * The act a copy states a feature in: the production event that
@@ -28,6 +51,7 @@ export const copyOfFeature = (edition, featureId) => copiesByFeature(edition).ge
  * a patch bears came onto the copy with the patch, so the act is
  * the one that glued the patch on. Two features stand in one act
  * where this returns the very same object.
+ * @category Lookups
  */
 export const actOf = (edition, featureId) => {
     const copy = copyOfFeature(edition, featureId);

package/lib/lookup/paths.d.ts

@@ -3,11 +3,31 @@
  * paths an operation can follow into a draft of it.
  */
 import { Edition } from "../model/Edition.js";
+/**
+ * Where something stands in an edition: the keys and indices that lead
+ * to it, as `pathIn` gives them and the operations on beliefs take
+ * them.
+ * @category Lookups
+ */
 export type Path = (string | number)[];
+/**
+ * What stands at the path in an edition or a draft of one, or nothing
+ * where the path leads nowhere.
+ * @category Lookups
+ */
 export declare const getAt: <T>(path: Path, obj: unknown) => T | undefined;
-/** 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 declare const pathIn: (edition: Edition, id: string) => Path | undefined;
-/** 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 declare const idsIn: (edition: Edition) => Iterable<string>;
-/** Where the edition references the id. */
+/**
+ * Where the edition references the id.
+ * @category Lookups
+ */
 export declare const linksTo: (edition: Edition, id: string) => Path[];