linked-rolls 0.22.0 → 0.23.0

package/lib/Quantity.d.ts

@@ -7,8 +7,12 @@
  * The unit names are the ones the records state in their `unit` field.
  */
 declare const unit: unique symbol;
+/**
+ * The units a record may state. A `Measure` is limited to these, since
+ * they are what the `unit` field is allowed to say.
+ */
 export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min' | 'px/in';
-export type Quantity<U extends Unit> = number & {
+export type Quantity<U extends string> = number & {
     readonly [unit]: U;
 };
 /** A place along the roll, or any length on the paper. */
@@ -24,6 +28,8 @@ export type FeetPerMinute = Quantity<'ft/min'>;
 export type MetersPerMinute = Quantity<'m/min'>;
 /** How finely a scan was read: pixels of the image per inch of paper. */
 export type Resolution = Quantity<'px/in'>;
+/** Names a number in a unit. Partially apply it to make a constructor. */
+export declare const quantity: <U extends string>(value: number) => Quantity<U>;
 export declare const mm: (value: number) => Quantity<"mm">;
 export declare const cm: (value: number) => Quantity<"cm">;
 export declare const px: (value: number) => Quantity<"px">;
@@ -50,19 +56,24 @@ export interface Measure<U extends Unit> {
      */
     unit: U;
 }
-export declare const add: <U extends Unit>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
-export declare const subtract: <U extends Unit>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
-export declare const distance: <U extends Unit>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const add: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const subtract: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const distance: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
 /** A quantity times a plain factor, such as a stretch. */
-export declare const scale: <U extends Unit>(a: Quantity<U>, factor: number) => Quantity<U>;
-export declare const sum: <U extends Unit>(values: readonly Quantity<U>[]) => Quantity<U>;
-export declare const mean: <U extends Unit>(values: readonly Quantity<U>[]) => Quantity<U>;
+export declare const scale: <U extends string>(a: Quantity<U>, factor: number) => Quantity<U>;
+export declare const min: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const max: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+/** The value brought inside the bounds, which must not be the wrong way round. */
+export declare const clamp: <U extends string>(value: Quantity<U>, low: Quantity<NoInfer<U>>, high: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const sum: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U>;
+export declare const mean: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U>;
 /** A place in a scan taken at `dpi` dots per inch, on the paper. */
 export declare const inMillimeters: (place: Pixels, dpi: number) => Millimeters;
 /** A place on the paper, in a scan taken at `dpi` dots per inch. */
 export declare const inPixels: (place: Millimeters, dpi: number) => Pixels;
 export declare const inCentimeters: (length: Millimeters) => Centimeters;
 export declare const inSeconds: (time: Milliseconds) => Seconds;
+export declare const inMilliseconds: (time: Seconds) => Milliseconds;
 /** A speed as a record states it, in feet or metres per minute. */
 export type SpeedMeasure = Measure<'ft/min'> | Measure<'m/min'>;
 /** A speed in metres per minute, whichever unit it was stated in. */

package/lib/Quantity.js

@@ -1,4 +1,5 @@
-const quantity = (value) => value;
+/** Names a number in a unit. Partially apply it to make a constructor. */
+export const quantity = (value) => value;
 export const mm = quantity;
 export const cm = quantity;
 export const px = quantity;
@@ -15,6 +16,12 @@ export const subtract = (a, b) => quantity(a - b);
 export const distance = (a, b) => quantity(Math.abs(a - b));
 /** A quantity times a plain factor, such as a stretch. */
 export const scale = (a, factor) => quantity(a * factor);
+// Math.min and Math.max are declared over plain numbers, so a quantity
+// passed through them comes back without its unit.
+export const min = (a, b) => quantity(Math.min(a, b));
+export const max = (a, b) => quantity(Math.max(a, b));
+/** The value brought inside the bounds, which must not be the wrong way round. */
+export const clamp = (value, low, high) => quantity(Math.min(high, Math.max(low, value)));
 // A list is taken at its element type, so one that mixes units yields a
 // union unit rather than an error; only the binary operations reject a mix.
 export const sum = (values) => quantity(values.reduce((total, value) => total + value, 0));
@@ -25,7 +32,9 @@ export const inMillimeters = (place, dpi) => mm(place / dpi * MM_PER_INCH);
 /** A place on the paper, in a scan taken at `dpi` dots per inch. */
 export const inPixels = (place, dpi) => px(place / MM_PER_INCH * dpi);
 export const inCentimeters = (length) => cm(length / 10);
-export const inSeconds = (time) => seconds(time / 1000);
+const MS_PER_SECOND = 1000;
+export const inSeconds = (time) => seconds(time / MS_PER_SECOND);
+export const inMilliseconds = (time) => milliseconds(time * MS_PER_SECOND);
 const METERS_PER_FOOT = 0.3048;
 /** A speed in metres per minute, whichever unit it was stated in. */
 export const inMetersPerMinute = (speed) => speed.unit === 'm/min' ? speed.value : metersPerMinute(speed.value * METERS_PER_FOOT);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {