@agoric/time 0.3.3-other-dev-8f8782b.0 → 0.3.3-other-dev-fbe72e7.0.fbe72e7

package/index.js

@@ -1,2 +1,4 @@
 export * from './src/timeMath.js';
 export * from './src/typeGuards.js';
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-index.js';

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@agoric/time",
-  "version": "0.3.3-other-dev-8f8782b.0+8f8782b",
+  "version": "0.3.3-other-dev-fbe72e7.0.fbe72e7",
   "description": "Timestamps, time math, timer service API definition",
   "type": "module",
   "main": "index.js",
+  "types": "index.js",
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^20.9 || ^22.11"
   },
   "scripts": {
     "build": "exit 0",
     "test": "ava",
     "test:xs": "exit 0",
-    "lint": "run-s --continue-on-error lint:*",
-    "lint:types": "tsc -p jsconfig.json",
-    "lint:eslint": "eslint .",
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'",
+    "lint:types": "yarn run -T tsc",
+    "lint:eslint": "yarn run -T eslint .",
     "lint-fix": "yarn lint:eslint --fix"
   },
   "repository": {
@@ -30,14 +31,23 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-other-dev-8f8782b.0+8f8782b",
-    "@agoric/store": "0.9.3-other-dev-8f8782b.0+8f8782b",
-    "@endo/nat": "4.1.27"
+    "@agoric/store": "0.9.3-other-dev-fbe72e7.0.fbe72e7",
+    "@endo/errors": "^1.2.13",
+    "@endo/nat": "^5.1.3",
+    "@endo/patterns": "^1.7.0"
   },
   "devDependencies": {
-    "@endo/far": "0.2.18",
-    "@endo/init": "0.5.56",
-    "ava": "^5.2.0"
+    "@endo/far": "^1.1.14",
+    "@endo/init": "^1.1.12",
+    "ava": "^5.3.0"
+  },
+  "ava": {
+    "require": [
+      "@endo/init/debug.js"
+    ],
+    "files": [
+      "test/**/*.test.*"
+    ]
   },
   "files": [
     "*.js",
@@ -47,5 +57,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8f8782bc52393e9d4fc82523ecf31cab429b11b3"
+  "typeCoverage": {
+    "atLeast": 88.75
+  },
+  "gitHead": "fbe72e72107f9997f788674e668c660d92ec4492"
 }

package/src/timeMath.js

@@ -1,16 +1,10 @@
-import { mustMatch } from '@agoric/store';
 import { Nat } from '@endo/nat';
+import { Fail, q } from '@endo/errors';
+import { mustMatch } from '@agoric/store';
 import { RelativeTimeRecordShape, TimestampRecordShape } from './typeGuards.js';
 
-const { Fail, quote: q } = assert;
 /**
- * @typedef {import('./types').TimerBrand} TimerBrand
- * @typedef {import('./types').Timestamp} Timestamp
- * @typedef {import('./types').RelativeTime} RelativeTime
- * @typedef {import('./types').RelativeTimeValue} RelativeTimeValue
- * @typedef {import('./types').TimestampValue} TimestampValue
- * @typedef {import('./types').TimeMathType} TimeMathType
- *
+ * @import {RelativeTime, RelativeTimeValue, TimerBrand, TimeMathType, Timestamp, TimestampRecord, TimestampValue} from './types.js';
  */
 
 /**
@@ -200,7 +194,7 @@ const modRelRel = (rel, step) =>
  * @param {Timestamp | RelativeTime} right
  * @param {bigint} v1
  * @param {bigint} v2
- * @returns {RankComparison}
+ * @returns {import('@endo/marshal').RankComparison}
  */
 const compareValues = (left, right, v1, v2) => {
   sharedTimerBrand(left, right);
@@ -253,7 +247,9 @@ export const TimeMath = harden({
   relValue,
   coerceTimestampRecord,
   coerceRelativeTimeRecord,
+  // @ts-expect-error xxx dynamic typing
   addAbsRel,
+  // @ts-expect-error xxx dynamic typing
   addRelRel,
   subtractAbsAbs,
   clampedSubtractAbsAbs,

package/src/typeGuards.js

@@ -1,20 +1,36 @@
-import { M } from '@agoric/store';
+import { M } from '@endo/patterns';
+
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ * @import {TimestampRecord, TimestampValue, RelativeTimeValue, RelativeTimeRecord} from './types.js';
+ */
 
 export const TimerBrandShape = M.remotable('TimerBrand');
+
+/** @type {TypedPattern<bigint>} */
 export const TimestampValueShape = M.nat();
+
+/** @type {TypedPattern<bigint>} */
 export const RelativeTimeValueShape = M.nat(); // Should we allow negatives?
 
-export const TimestampRecordShape = harden({
+/** @type {TypedPattern<TimestampRecord>} */
+export const TimestampRecordShape = {
   timerBrand: TimerBrandShape,
   absValue: TimestampValueShape,
-});
+};
+harden(TimestampRecordShape);
 
-export const RelativeTimeRecordShape = harden({
+/** @type {TypedPattern<RelativeTimeRecord>} */
+export const RelativeTimeRecordShape = {
   timerBrand: TimerBrandShape,
   relValue: RelativeTimeValueShape,
-});
+};
+harden(RelativeTimeRecordShape);
 
+/** @type {TypedPattern<TimestampRecord | TimestampValue>} */
 export const TimestampShape = M.or(TimestampRecordShape, TimestampValueShape);
+
+/** @type {TypedPattern<RelativeTimeRecord | RelativeTimeValue>} */
 export const RelativeTimeShape = M.or(
   RelativeTimeRecordShape,
   RelativeTimeValueShape,

package/src/types-index.d.ts

@@ -0,0 +1 @@
+export type * from './types.js';

package/src/types-index.js

@@ -0,0 +1,2 @@
+// Empty JS file to correspond with types.d.ts
+export {};

package/src/{types.d.ts → types.ts}

@@ -1,22 +1,19 @@
-/* eslint-disable no-use-before-define, no-undef */
-import type { ERef } from '@endo/eventual-send';
+import type { ERef, RemotableBrand } from '@endo/eventual-send';
 
-import type { RankComparison } from '@agoric/store';
-
-/// <reference types="@agoric/notifier/src/types.js"/>
+import type { RankComparison, RemotableObject } from '@endo/marshal';
 
 // These aren't in the global runtime environment. They are just types that are
 // meant to be globally accessible as a side-effect of importing this module.
 /**
  * The TimerBrand is a unique object that represents the kind of Time
- * used in Timestamp/RelativeTime records. Time from different sources
- * is not comparable.
+ * used in Timestamp/RelativeTime records. Times from different sources
+ * are not comparable.
  *
  * Do not call `isMyTimerService(myTimerService)` on an untrusted
  * brand, because that will leak your closely-held timer authority. If
  * the goal is to check the suitability of a client-provided
  * Timestamp, use coerceTimestampRecord() or add/subtract it to a
- * known-good Timestamp, or extact its brand and === against
+ * known-good Timestamp, or extract its brand and === against
  * `timerService.getTimerBrand()`.
  *
  * TODO Not all Timestamps are labeled with the TimerBrand (in much
@@ -29,7 +26,7 @@ import type { RankComparison } from '@agoric/store';
  * See https://github.com/Agoric/agoric-sdk/issues/5798
  * and https://github.com/Agoric/agoric-sdk/pull/5821
  */
-export type TimerBrand = {
+export type TimerBrand = RemotableObject & {
   isMyTimerService: (timer: TimerService) => ERef<boolean>;
   isMyClock: (clock: Clock) => ERef<boolean>;
 };
@@ -53,11 +50,21 @@ export type TimestampValue = bigint;
  */
 export type RelativeTimeValue = bigint;
 
+/**
+ * The canonical representation of a typed absolute time. It bundles the brand
+ * with the time, as represented by a TimerService, which might represent time
+ * since the epoch, or blockheight on a particular chain.
+ */
 export type TimestampRecord = {
   timerBrand: TimerBrand;
   absValue: bigint;
 };
 
+/**
+ * The canonical representation of a typed relative time. It bundles the brand
+ * with an elapsed time, as represented by a TimerService, which might represent
+ * time since the epoch, or blockheight on a particular chain.
+ */
 export type RelativeTimeRecord = {
   timerBrand: TimerBrand;
   relValue: bigint;
@@ -88,7 +95,8 @@ export type RelativeTime = RelativeTimeRecord | RelativeTimeValue;
 /**
  * A CancelToken is an arbitrary marker object, passed in with
  * each API call that creates a wakeup or repeater, and passed to
- * cancel() to cancel them all.
+ * cancel() to cancel them all. Multiple wakeups can rely on the same
+ * CancelToken so they can be cancelled collectively.
  */
 export type CancelToken = object;
 
@@ -97,7 +105,7 @@ export type CancelToken = object;
  * schedule a single wake() call, create a repeater that will allow scheduling
  * of events at regular intervals, or remove scheduled calls.
  */
-export interface TimerService {
+export interface TimerServiceCommon {
   /**
    * Retrieve the latest timestamp
    */
@@ -111,7 +119,7 @@ export interface TimerService {
     cancelToken?: CancelToken,
   ) => TimestampRecord;
   /**
-   * Create and return a promise that will resolve after the absolte
+   * Create and return a promise that will resolve after the absolute
    * time has passed.
    */
   wakeAt: (
@@ -157,7 +165,7 @@ export interface TimerService {
     delay: RelativeTime,
     interval: RelativeTime,
     cancelToken?: CancelToken,
-  ) => Notifier<TimestampRecord>;
+  ) => import('@agoric/notifier').Notifier<TimestampRecord>;
   /**
    * Cancel a previously-established wakeup or repeater.
    */
@@ -171,7 +179,16 @@ export interface TimerService {
    */
   getTimerBrand: () => TimerBrand;
 }
+// XXX copied from Remotable helper return type
+export type TimerService = TimerServiceCommon &
+  RemotableObject<'TimerService'> &
+  RemotableBrand<object, TimerServiceCommon>;
 
+/**
+ * Read-only access to a TimeService's current time. This allows reading the
+ * current time (e.g. to see if a deadline has passed) without the ability to
+ * schedule events.
+ */
 export interface Clock {
   /**
    * Retrieve the latest timestamp
@@ -183,6 +200,11 @@ export interface Clock {
   getTimerBrand: () => TimerBrand;
 }
 
+/**
+ * The interface that must be implemented by objects which are to be invoked at
+ * scheduled times. Used by `TimerService.repeatAfter()`,
+ * `TimerService.setWakeup()`, and `TimerRepeater.schedule()`.
+ */
 export interface TimerWaker {
   /**
    * The timestamp passed to `wake()` is the time that the call was scheduled
@@ -191,6 +213,12 @@ export interface TimerWaker {
   wake: (timestamp: TimestampRecord) => void;
 }
 
+/**
+ * Provides the ability to schedule wake() calls repeatedly at a regular
+ * interval, or to disable all future use of this TimerRepeater. Created by the
+ * deprecated makeRepeater(), new code should use repeatAfter(), which doesn't
+ * have a control object and doesn't require a second schedule step
+ */
 export interface TimerRepeater {
   /**
    * Returns the time scheduled for
@@ -206,6 +234,26 @@ export interface TimerRepeater {
   disable: () => void;
 }
 
+/**
+ * TimeMath supports simple arithmetic on typed Time values, enforcing that
+ * values are combined in type-compatible ways. You can add 3 minutes to 3pm,
+ * or 5 minutes to a half hour, but it makes no sense to add 3pm and 5pm.
+ * Subtracting two Timestamps does produce a useful difference.
+ *
+ * The brands prevent you from accidentally combining time values from different
+ * TimerServices. Some chains track time in blocks, others follow wall clock
+ * time, some do both. Every local computer has its own unique notion of wall
+ * clock time. Even when these clocks are talking about the same thing (UTC),
+ * they can all drift in different ways. Using the correct brands lets you be
+ * precise about which particular source of time you mean, preventing confusion
+ * or attacks when the clocks diverge. Thus it is an error to e.g. use a time
+ * you got from chain A to schedule an event on chain B.
+ *
+ * The basic types are `RelativeTimeRecord` (durations) and `TimestampRecord`. The numeric
+ * values can be extracted from the typed values, but it's usually better to
+ * maintain values as their canonical typed form so these operations can be
+ * applied.
+ */
 export type TimeMathType = {
   /**
    * Validates that the operand represents a `Timestamp` and returns the bigint
@@ -240,17 +288,19 @@ export type TimeMathType = {
   ) => RelativeTimeRecord;
   /**
    * An absolute time + a relative time gives a new absolute time.
-   *
-   * @template {Timestamp} T
    */
-  addAbsRel: (abs: T, rel: RelativeTime) => T;
+  addAbsRel: <T extends Timestamp>(
+    abs: T,
+    rel: RelativeTime,
+  ) => T extends TimestampRecord ? TimestampRecord : TimestampValue;
   /**
    * A relative time (i.e., a duration) + another relative time
    * gives a new relative time.
-   *
-   * @template {RelativeTime} T
    */
-  addRelRel: (rel1: T, rel2: T) => T;
+  addRelRel: <T extends RelativeTime>(
+    rel1: T,
+    rel2: T,
+  ) => T extends RelativeTimeRecord ? RelativeTimeRecord : RelativeTimeValue;
   /**
    * The difference between two absolute times is a relative time. If abs1 > abs2
    * the difference would be negative, so this method throws instead.

package/CHANGELOG.md

@@ -1,45 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-### [0.3.3-u11.0](https://github.com/Agoric/agoric-sdk/compare/@agoric/time@0.3.2...@agoric/time@0.3.3-u11.0) (2023-08-24)
-
-**Note:** Version bump only for package @agoric/time
-
-
-
-
-
-### [0.3.2](https://github.com/Agoric/agoric-sdk/compare/@agoric/time@0.3.1...@agoric/time@0.3.2) (2023-06-02)
-
-**Note:** Version bump only for package @agoric/time
-
-
-
-
-
-### [0.3.1](https://github.com/Agoric/agoric-sdk/compare/@agoric/time@0.3.0...@agoric/time@0.3.1) (2023-05-24)
-
-**Note:** Version bump only for package @agoric/time
-
-
-
-
-
-## 0.3.0 (2023-05-19)
-
-
-### Features
-
-* **auction:** add an auctioneer to manage vault liquidation ([#7000](https://github.com/Agoric/agoric-sdk/issues/7000)) ([398b70f](https://github.com/Agoric/agoric-sdk/commit/398b70f7e028f957afc1582f0ee31eb2574c94d0)), closes [#6992](https://github.com/Agoric/agoric-sdk/issues/6992) [#7047](https://github.com/Agoric/agoric-sdk/issues/7047) [#7074](https://github.com/Agoric/agoric-sdk/issues/7074)
-* create new @agoric/time package ([a61a3fb](https://github.com/Agoric/agoric-sdk/commit/a61a3fbb7a5ccfe07c715a310baa88ada8e572b2)), closes [#6003](https://github.com/Agoric/agoric-sdk/issues/6003)
-
-
-### Bug Fixes
-
-* **time:** TimerService now returns branded TimestampRecord ([9137e9c](https://github.com/Agoric/agoric-sdk/commit/9137e9cab6f459c876b1a2ad8e681be7224749ce)), closes [#6003](https://github.com/Agoric/agoric-sdk/issues/6003)
-* clean up types ([6f53f19](https://github.com/Agoric/agoric-sdk/commit/6f53f1915ce21e65fefc2fff900b7d4b947be6b1))
-* move timer files to new package ([c105bde](https://github.com/Agoric/agoric-sdk/commit/c105bdefff2527a90b3c6b9d80d0462944dd51c3))
-* TimerBrand has isMyTimerService(), not isMyTimer() ([9f4e867](https://github.com/Agoric/agoric-sdk/commit/9f4e8670694504ebbd451c8840f900a1a24b902f))
-* **time:** fix the code/test to work in its new home ([504d333](https://github.com/Agoric/agoric-sdk/commit/504d3335cf632cc50e079fb27a82db604318bd4a))