@sapphire/duration 1.1.0-next.e3fa75f.0 → 1.1.0-next.edd1210.0

package/README.md

@@ -18,7 +18,10 @@
 -   [Features](#features)
 -   [Installation](#installation)
 -   [Usage](#usage)
-    -   [Basic Usage](#basic-usage)
+    -   [Human Readable Milliseconds](#human-readable-milliseconds)
+    -   [Parsing a Duration](#parsing-a-duration)
+    -   [Serializing a Duration](#serializing-a-duration)
+    -   [Localizing with Durations](#localizing-with-durations)
 -   [Buy us some doughnuts](#buy-us-some-doughnuts)
 -   [Contributors ✨](#contributors-%E2%9C%A8)
 
@@ -37,6 +40,143 @@ You can use the following command to install this package, or replace `npm insta
 npm install @sapphire/duration
 ```
 
+## Usage
+
+**Note:** While this section uses `require`, the imports match 1:1 with ESM imports. For example `const { Duration } = require('@sapphire/duration')` equals `import { Duration } from '@sapphire/duration'`.
+
+### Human Readable Milliseconds
+
+Milliseconds are often hard for humans to quickly parse, so it's nice to use
+named enum members to make it easier to read.
+
+```typescript
+// Import the Time enum
+const { Time } = require('@sapphire/duration');
+
+setTimeout(() => {
+	// Do something in half a second
+}, Time.Second / 2 /* 500 */);
+
+setTimeout(() => {
+	// Do something in 6 hours
+}, Time.Hour * 6 /* 21600000 */);
+
+setTimeout(() => {
+	// Do something in 1 day
+}, Time.Day /* 86400000 */);
+```
+
+### Parsing a Duration
+
+```typescript
+// Import the Duration class
+const { Duration } = require('@sapphire/duration');
+
+// Create a Duration from a string
+new Duration('1d3h15m3s').offset; // 98103000
+new Duration('1 day, 3h & 15m, some extra characters, and another 3 seconds').offset; // 98103000
+
+// The date from now after the specified duration
+new Duration('1d3h15m3s').fromNow;
+
+// Or use a specific date
+new Duration('1d3h15m3s').dateFrom(new Date('2020-01-01T00:00:00.000Z'));
+```
+
+<details>
+	<summary>
+		<b>Show all available tokens</b>
+	</summary>
+
+```typescript
+new Duration('1 nanosecond').offset; // 0.000001
+new Duration('2 nanoseconds').offset; // 0.000002
+new Duration('1 ns').offset; // 0.000001
+
+new Duration('1 millisecond').offset; // 1
+new Duration('2 milliseconds').offset; // 2
+new Duration('1 ms').offset; // 1
+
+new Duration('1 second').offset; // 1000
+new Duration('2 seconds').offset; // 2000
+new Duration('1 sec').offset; // 1000
+new Duration('2 secs').offset; // 2000
+new Duration('1 s').offset; // 1000
+
+new Duration('1 minute').offset; // 60000
+new Duration('2 minutes').offset; // 120000
+new Duration('1 min').offset; // 60000
+new Duration('2 mins').offset; // 120000
+new Duration('1 m').offset; // 60000
+
+new Duration('1 hour').offset; // 3600000
+new Duration('2 hours').offset; // 7200000
+new Duration('1 hr').offset; // 3600000
+new Duration('2 hrs').offset; // 7200000
+new Duration('1 h').offset; // 3600000
+
+new Duration('1 day').offset; // 86400000
+new Duration('2 days').offset; // 172800000
+new Duration('1 d').offset; // 86400000
+
+new Duration('1 week').offset; // 604800000
+new Duration('2 weeks').offset; // 1209600000
+new Duration('1 wk').offset; // 604800000
+new Duration('2 wks').offset; // 1209600000
+new Duration('1 w').offset; // 604800000
+
+new Duration('1 month').offset; // 2629800000
+new Duration('2 months').offset; // 5259600000
+new Duration('1 b').offset; // 2629800000
+new Duration('2 mo').offset; // 5259600000
+
+new Duration('1 year').offset; // 31557600000
+new Duration('2 years').offset; // 63115200000
+new Duration('1 yr').offset; // 31557600000
+new Duration('2 yrs').offset; // 63115200000
+new Duration('1 y').offset; // 31557600000
+```
+
+</details>
+
+### Serializing a Duration
+
+```typescript
+// Import the DurationFormatter class
+const { DurationFormatter } = require('@sapphire/duration');
+
+const formatter = new DurationFormatter();
+
+// Serialize a duration
+formatter.format(98103000); // 1 day 3 hours 15 minutes 3 seconds
+formatter.format(-98103000); // -1 day 3 hours 15 minutes 3 seconds
+
+// Serialize a duration with specified precision
+formatter.format(98103000, 2); // 1 day 3 hours
+```
+
+### Localizing with Durations
+
+```typescript
+// Import the DurationFormatter class
+const { DurationFormatter, TimeTypes } = require('@sapphire/duration');
+
+// Create custom unit names
+const units = {
+	[TimeTypes.Year]: {
+		1: 'año',
+		DEFAULT: 'años'
+	}
+};
+
+// Create a formatter the custom units
+const formatter = new DurationFormatter(units);
+
+// Serialize a duration
+formatter.format(31557600000); // 1 año
+formatter.format(63115200000); // 2 años
+```
+
 ## Buy us some doughnuts
 
 Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!
@@ -109,6 +249,12 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://enes.ovh/"><img src="https://avatars.githubusercontent.com/u/61084101?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Enes Genç</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=enxg" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/muchnameless"><img src="https://avatars.githubusercontent.com/u/12682826?v=4?s=100" width="100px;" alt=""/><br /><sub><b>muchnameless</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=muchnameless" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/r-priyam"><img src="https://avatars.githubusercontent.com/u/50884372?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Priyam</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=r-priyam" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/legendhimslef"><img src="https://avatars.githubusercontent.com/u/69213593?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Voxelli</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=legendhimslef" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/CitTheDev"><img src="https://avatars.githubusercontent.com/u/94020875?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Cit The Dev</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=CitTheDev" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://www.goestav.com/"><img src="https://avatars.githubusercontent.com/u/27970303?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Goestav</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=goestav" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/didinele"><img src="https://avatars.githubusercontent.com/u/27137376?v=4?s=100" width="100px;" alt=""/><br /><sub><b>DD</b></sub></a><br /><a href="https://github.com/sapphiredev/utilities/commits?author=didinele" title="Code">💻</a></td>
   </tr>
 </table>
 

package/dist/index.global.js

@@ -187,9 +187,8 @@ var SapphireDuration = (function (exports) {
   exports.Time = Time;
   exports.TimeTypes = TimeTypes;
 
-  Object.defineProperty(exports, '__esModule', { value: true });
-
   return exports;
 
 })({});
+//# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.global.js.map

package/dist/index.js

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -187,4 +185,5 @@ exports.Duration = Duration;
 exports.DurationFormatter = DurationFormatter;
 exports.Time = Time;
 exports.TimeTypes = TimeTypes;
+//# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -178,4 +178,5 @@ function addUnit(time, unit, separator) {
 __name(addUnit, "addUnit");
 
 export { DEFAULT_SEPARATORS, DEFAULT_UNITS, Duration, DurationFormatter, Time, TimeTypes };
+//# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sapphire/duration",
-  "version": "1.1.0-next.e3fa75f.0",
+  "version": "1.1.0-next.edd1210.0",
   "description": "A time duration utility library for JavaScript.",
   "author": "@sapphire",
   "license": "MIT",
@@ -57,12 +57,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@favware/cliff-jumper": "^1.8.8",
-    "@vitest/coverage-c8": "^0.23.4",
-    "tsup": "^6.2.3",
-    "typedoc": "^0.23.15",
-    "typedoc-json-parser": "^5.0.1",
-    "typescript": "^4.8.4",
-    "vitest": "^0.23.4"
+    "@favware/cliff-jumper": "^1.9.0",
+    "@vitest/coverage-c8": "^0.25.2",
+    "tsup": "^6.5.0",
+    "typedoc": "^0.23.21",
+    "typedoc-json-parser": "^7.0.1",
+    "typescript": "^4.9.3",
+    "vitest": "^0.25.2"
   }
 }