@pvorona/duration 0.0.1 → 0.1.0

package/README.md

@@ -1,11 +1,178 @@
-# duration
+# @pvorona/duration
 
-This library was generated with [Nx](https://nx.dev).
+An immutable duration type with unit conversions, comparisons, and basic arithmetic.
 
-## Building
+## Install
 
-Run `nx build duration` to build the library.
+```bash
+npm i @pvorona/duration
+```
 
-## Running unit tests
+## Usage
 
-Run `nx test duration` to execute the unit tests via [Vitest](https://vitest.dev/).
+### Create and convert
+
+```ts
+import { minutes } from '@pvorona/duration';
+
+const d = minutes(5);
+d.toSeconds(); // 300
+d.toMilliSeconds(); // 300_000
+```
+
+### Compare
+
+```ts
+import { milliSeconds, seconds } from '@pvorona/duration';
+
+const a = seconds(1);
+const b = milliSeconds(900);
+
+a.greaterThan(b); // true
+a.compare(b); // 1
+```
+
+### Arithmetic
+
+```ts
+import { add, milliSeconds, seconds } from '@pvorona/duration';
+
+const total = add(seconds(1), milliSeconds(500));
+total.toMilliSeconds(); // 1500
+```
+
+### Between dates
+
+```ts
+import { since } from '@pvorona/duration';
+
+const startedAt = new Date(Date.now() - 2_000);
+const elapsed = since(startedAt);
+elapsed.toSeconds(); // ~2
+```
+
+## API
+
+### `const enum TimeUnit`
+
+Time units supported by `duration(value, unit)` and `d.to(unit)`.
+
+```ts
+export const enum TimeUnit {
+  MilliSecond,
+  Second,
+  Minute,
+  Hour,
+  Day,
+  Week,
+  Month,
+  Year,
+}
+```
+
+Notes:
+
+- `Month` is treated as **30 days**
+- `Year` is treated as **365.25 days**
+
+Example:
+
+```ts
+import { duration, TimeUnit } from '@pvorona/duration';
+
+duration(2, TimeUnit.Hour).toMinutes(); // 120
+```
+
+### `type Duration`
+
+An opaque, immutable duration value.
+
+#### Properties
+
+- **`isFinite: boolean`**: `true` unless the duration is infinite
+- **`isInfinite: boolean`**: `true` for `infinite`
+- **`isInstant: boolean`**: `true` for zero duration (`instant`)
+
+#### Conversions
+
+- **`to(unit: TimeUnit): number`**: convert to an arbitrary unit
+- **`toMilliSeconds(): number`**
+- **`toSeconds(): number`**
+- **`toMinutes(): number`**
+- **`toHours(): number`**
+- **`toDays(): number`**
+- **`toWeeks(): number`**
+- **`toMonths(): number`** (30-day months)
+- **`toYears(): number`** (365.25-day years)
+
+#### Comparisons
+
+- **`equals(other: Duration): boolean`**
+- **`lessThan(other: Duration): boolean`**
+- **`lessThanOrEqual(other: Duration): boolean`**
+- **`greaterThan(other: Duration): boolean`**
+- **`greaterThanOrEqual(other: Duration): boolean`**
+- **`compare(other: Duration): -1 | 0 | 1`**
+
+Example (properties + conversion + comparison):
+
+```ts
+import { milliSeconds, seconds, type Duration } from '@pvorona/duration';
+
+function isShort(d: Duration) {
+  return d.isFinite && d.toSeconds() < 5;
+}
+
+const a = seconds(1);
+const b = milliSeconds(900);
+
+isShort(a); // true
+a.greaterThan(b); // true
+```
+
+### Function API
+
+#### Constructors
+
+- `duration(value: number, unit: TimeUnit): Duration`
+- `milliSeconds(value: number): Duration`
+- `seconds(value: number): Duration`
+- `minutes(value: number): Duration`
+- `hours(value: number): Duration`
+- `days(value: number): Duration`
+- `weeks(value: number): Duration`
+- `months(value: number): Duration`
+- `years(value: number): Duration`
+
+#### Date helpers
+
+- `between(start: Date, end: Date): Duration`
+- `since(start: Date): Duration`
+
+#### Arithmetic helpers
+
+- `add(a: Duration, b: Duration): Duration`
+- `subtract(a: Duration, b: Duration): Duration`
+- `multiply(a: Duration, b: number): Duration`
+- `divide(a: Duration, b: number): Duration`
+
+#### Constants
+
+- `instant: Duration`
+- `infinite: Duration`
+
+#### Guards / equality
+
+- `isDuration(value: unknown): value is Duration`
+- `isEqual(a: Duration, b: Duration): boolean`
+
+Example:
+
+```ts
+import { isDuration, seconds } from '@pvorona/duration';
+
+const maybe: unknown = seconds(1);
+if (isDuration(maybe)) {
+  maybe.toMilliSeconds(); // ok, narrowed
+}
+```

package/dist/index.js

@@ -1,8 +1,6 @@
-function i(t) {
-  return t !== null && typeof t == "object";
-}
-var f = /* @__PURE__ */ ((t) => (t[t.MilliSecond = 0] = "MilliSecond", t[t.Second = 1] = "Second", t[t.Minute = 2] = "Minute", t[t.Hour = 3] = "Hour", t[t.Day = 4] = "Day", t[t.Week = 5] = "Week", t[t.Month = 6] = "Month", t[t.Year = 7] = "Year", t))(f || {});
-const e = /* @__PURE__ */ Symbol("milliSeconds"), u = {
+import { isObject as i } from "@pvorona/assert";
+var c = /* @__PURE__ */ ((t) => (t[t.MilliSecond = 0] = "MilliSecond", t[t.Second = 1] = "Second", t[t.Minute = 2] = "Minute", t[t.Hour = 3] = "Hour", t[t.Day = 4] = "Day", t[t.Week = 5] = "Week", t[t.Month = 6] = "Month", t[t.Year = 7] = "Year", t))(c || {});
+const n = /* @__PURE__ */ Symbol("milliSeconds"), o = {
   0: 1,
   1: 1e3,
   2: 60 * 1e3,
@@ -21,12 +19,12 @@ const e = /* @__PURE__ */ Symbol("milliSeconds"), u = {
     365.25 * 24 * 60 * 60 * 1e3
   )
 }, a = {
-  [e]: 0,
+  [n]: 0,
   isFinite: !1,
   isInfinite: !1,
   isInstant: !1,
   to(t) {
-    return this[e] / u[t];
+    return this[n] / o[t];
   },
   toMilliSeconds() {
     return this.to(
@@ -77,112 +75,131 @@ const e = /* @__PURE__ */ Symbol("milliSeconds"), u = {
     );
   },
   equals(t) {
-    return this[e] === t[e];
+    return this[n] === t[n];
   },
   lessThan(t) {
-    return this[e] < t[e];
+    return this[n] < t[n];
   },
   lessThanOrEqual(t) {
-    return this[e] <= t[e];
+    return this[n] <= t[n];
   },
   greaterThan(t) {
-    return this[e] > t[e];
+    return this[n] > t[n];
   },
   greaterThanOrEqual(t) {
-    return this[e] >= t[e];
+    return this[n] >= t[n];
   },
   compare(t) {
     return this.lessThan(t) ? -1 : this.greaterThan(t) ? 1 : 0;
   }
 };
-function s(t, r) {
-  const o = Object.create(a);
-  return o[e] = t * u[r], o.isFinite = t !== 1 / 0, o.isInfinite = t === 1 / 0, o.isInstant = t === 0, Object.freeze(o);
+function f(t, r) {
+  const s = Object.create(a);
+  return s[n] = t * o[r], s.isFinite = t !== 1 / 0, s.isInfinite = t === 1 / 0, s.isInstant = t === 0, Object.freeze(s);
 }
-const n = Object.freeze({
-  of(t, r) {
-    return s(t, r);
-  },
-  ofMilliSeconds(t) {
-    return n.of(
-      t,
-      0
-      /* MilliSecond */
-    );
-  },
-  ofSeconds(t) {
-    return n.of(
-      t,
-      1
-      /* Second */
-    );
-  },
-  ofMinutes(t) {
-    return n.of(
-      t,
-      2
-      /* Minute */
-    );
-  },
-  ofHours(t) {
-    return n.of(
-      t,
-      3
-      /* Hour */
-    );
-  },
-  ofDays(t) {
-    return n.of(
-      t,
-      4
-      /* Day */
-    );
-  },
-  ofWeeks(t) {
-    return n.of(
-      t,
-      5
-      /* Week */
-    );
-  },
-  ofMonths(t) {
-    return n.of(
-      t,
-      6
-      /* Month */
-    );
-  },
-  ofYears(t) {
-    return n.of(
-      t,
-      7
-      /* Year */
-    );
-  },
-  between: (t, r) => n.of(
-    r.getTime() - t.getTime(),
-    0
-    /* MilliSecond */
-  ),
-  since: (t) => n.between(t, /* @__PURE__ */ new Date()),
-  add: (t, r) => n.ofMilliSeconds(t[e] + r[e]),
-  subtract: (t, r) => n.ofMilliSeconds(t[e] - r[e]),
-  multiply: (t, r) => n.ofMilliSeconds(t[e] * r),
-  divide: (t, r) => n.ofMilliSeconds(t[e] / r),
-  ofInfinite: s(
-    1 / 0,
-    0
-    /* MilliSecond */
-  ),
-  ofInstant: s(
-    0,
+function e(t, r) {
+  return f(t, r);
+}
+function u(t) {
+  return e(
+    t,
     0
     /* MilliSecond */
-  ),
-  isDuration: (t) => i(t) && e in t,
-  isEqual: (t, r) => t[e] === r[e]
-});
+  );
+}
+function d(t) {
+  return e(
+    t,
+    1
+    /* Second */
+  );
+}
+function I(t) {
+  return e(
+    t,
+    2
+    /* Minute */
+  );
+}
+function S(t) {
+  return e(
+    t,
+    3
+    /* Hour */
+  );
+}
+function y(t) {
+  return e(
+    t,
+    4
+    /* Day */
+  );
+}
+function M(t) {
+  return e(
+    t,
+    5
+    /* Week */
+  );
+}
+function D(t) {
+  return e(
+    t,
+    6
+    /* Month */
+  );
+}
+function O(t) {
+  return e(
+    t,
+    7
+    /* Year */
+  );
+}
+function h(t, r) {
+  return u(r.getTime() - t.getTime());
+}
+function b(t) {
+  return h(t, /* @__PURE__ */ new Date());
+}
+function g(t, r) {
+  return u(t[n] + r[n]);
+}
+function E(t, r) {
+  return u(t[n] - r[n]);
+}
+function k(t, r) {
+  return u(t[n] * r);
+}
+function p(t, r) {
+  return u(t[n] / r);
+}
+const q = u(1 / 0), N = u(0);
+function j(t) {
+  return i(t) && n in t;
+}
+function w(t, r) {
+  return t[n] === r[n];
+}
 export {
-  n as Duration,
-  f as TimeUnit
+  c as TimeUnit,
+  g as add,
+  h as between,
+  y as days,
+  p as divide,
+  e as duration,
+  S as hours,
+  q as infinite,
+  N as instant,
+  j as isDuration,
+  w as isEqual,
+  u as milliSeconds,
+  I as minutes,
+  D as months,
+  k as multiply,
+  d as seconds,
+  b as since,
+  E as subtract,
+  M as weeks,
+  O as years
 };

package/dist/lib/duration.d.ts

@@ -8,9 +8,9 @@ export declare const enum TimeUnit {
     Month = 6,
     Year = 7
 }
-declare const milliSeconds: unique symbol;
+declare const millisecondsTag: unique symbol;
 export type Duration = {
-    readonly [milliSeconds]: number;
+    readonly [millisecondsTag]: number;
     readonly isFinite: boolean;
     readonly isInfinite: boolean;
     readonly isInstant: boolean;
@@ -30,26 +30,24 @@ export type Duration = {
     greaterThanOrEqual(other: Duration): boolean;
     compare(other: Duration): -1 | 0 | 1;
 };
-export declare const Duration: Readonly<{
-    of(value: number, unit: TimeUnit): Duration;
-    ofMilliSeconds(value: number): Duration;
-    ofSeconds(value: number): Duration;
-    ofMinutes(value: number): Duration;
-    ofHours(value: number): Duration;
-    ofDays(value: number): Duration;
-    ofWeeks(value: number): Duration;
-    ofMonths(value: number): Duration;
-    ofYears(value: number): Duration;
-    between: (start: Date, end: Date) => Duration;
-    since: (start: Date) => Duration;
-    add: (a: Duration, b: Duration) => Duration;
-    subtract: (a: Duration, b: Duration) => Duration;
-    multiply: (a: Duration, b: number) => Duration;
-    divide: (a: Duration, b: number) => Duration;
-    ofInfinite: Duration;
-    ofInstant: Duration;
-    isDuration: (value: unknown) => value is Duration;
-    isEqual: (a: Duration, b: Duration) => boolean;
-}>;
+export declare function duration(value: number, unit: TimeUnit): Duration;
+export declare function milliSeconds(value: number): Duration;
+export declare function seconds(value: number): Duration;
+export declare function minutes(value: number): Duration;
+export declare function hours(value: number): Duration;
+export declare function days(value: number): Duration;
+export declare function weeks(value: number): Duration;
+export declare function months(value: number): Duration;
+export declare function years(value: number): Duration;
+export declare function between(start: Date, end: Date): Duration;
+export declare function since(start: Date): Duration;
+export declare function add(a: Duration, b: Duration): Duration;
+export declare function subtract(a: Duration, b: Duration): Duration;
+export declare function multiply(a: Duration, b: number): Duration;
+export declare function divide(a: Duration, b: number): Duration;
+export declare const infinite: Duration;
+export declare const instant: Duration;
+export declare function isDuration(value: unknown): value is Duration;
+export declare function isEqual(a: Duration, b: Duration): boolean;
 export {};
 //# sourceMappingURL=duration.d.ts.map

package/dist/lib/duration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/lib/duration.ts"],"names":[],"mappings":"AAMA,0BAAkB,QAAQ;IACxB,WAAW,IAAA;IACX,MAAM,IAAA;IACN,MAAM,IAAA;IACN,IAAI,IAAA;IACJ,GAAG,IAAA;IACH,IAAI,IAAA;IACJ,KAAK,IAAA;IACL,IAAI,IAAA;CACL;AAED,QAAA,MAAM,YAAY,eAAyB,CAAC;AAE5C,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,cAAc,IAAI,MAAM,CAAC;IACzB,SAAS,IAAI,MAAM,CAAC;IACpB,SAAS,IAAI,MAAM,CAAC;IACpB,OAAO,IAAI,MAAM,CAAC;IAClB,MAAM,IAAI,MAAM,CAAC;IACjB,OAAO,IAAI,MAAM,CAAC;IAClB,QAAQ,IAAI,MAAM,CAAC;IACnB,OAAO,IAAI,MAAM,CAAC;IAElB,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IACnC,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1C,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IACtC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7C,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACtC,CAAC;AAoFF,eAAO,MAAM,QAAQ;cACT,MAAM,QAAQ,QAAQ,GAAG,QAAQ;0BAGrB,MAAM,GAAG,QAAQ;qBAGtB,MAAM,GAAG,QAAQ;qBAGjB,MAAM,GAAG,QAAQ;mBAGnB,MAAM,GAAG,QAAQ;kBAGlB,MAAM,GAAG,QAAQ;mBAGhB,MAAM,GAAG,QAAQ;oBAGhB,MAAM,GAAG,QAAQ;mBAGlB,MAAM,GAAG,QAAQ;qBAGf,IAAI,OAAO,IAAI,KAAG,QAAQ;mBAG5B,IAAI,KAAG,QAAQ;aAGrB,QAAQ,KAAK,QAAQ,KAAG,QAAQ;kBAG3B,QAAQ,KAAK,QAAQ,KAAG,QAAQ;kBAGhC,QAAQ,KAAK,MAAM,KAAG,QAAQ;gBAGhC,QAAQ,KAAK,MAAM,KAAG,QAAQ;;;wBAStB,OAAO,KAAG,KAAK,IAAI,QAAQ;iBAGlC,QAAQ,KAAK,QAAQ,KAAG,OAAO;EAG5C,CAAC"}
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/lib/duration.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pvorona/duration",
-  "version": "0.0.1",
+  "version": "0.1.0",
+  "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,10 +19,10 @@
     "dist",
     "!**/*.tsbuildinfo"
   ],
-  "nx": {
-    "name": "duration"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@pvorona/assert": "^0.0.1"
+    "@pvorona/assert": "~0.0.2"
   }
 }