@ehmpathy/uni-time 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Uladzimir Kasacheuski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/domain/UniDateTime.d.ts

@@ -0,0 +1,38 @@
+import { AsOfGlossary } from 'domain-glossaries';
+import { PickOne } from 'type-fns';
+declare const castInputToDate: (input: string | Date | PickOne<{
+    /**
+     * milliseconds since epoch
+     */
+    mse: number;
+    /**
+     * a date
+     */
+    date: Date;
+}>) => Date;
+/**
+ * a universally unambiguous datetime serialized as a string; yyyy-MM-ddThh:mm:ssZ
+ */
+export type UniDateTime = AsOfGlossary<string, 'uni-time'>;
+export declare const asUniDateTime: (input: Parameters<typeof castInputToDate>[0]) => UniDateTime;
+/**
+ * a universally unambiguous date serialized as a string; yyyy-MM-dd
+ */
+export type UniDate = AsOfGlossary<string, 'uni-time'>;
+export declare const asUniDate: (input: Parameters<typeof castInputToDate>[0]) => UniDate;
+/**
+ * a universally unambiguous month serialized as a string; yyyy-MM
+ */
+export type UniMonth = AsOfGlossary<string, 'uni-time'>;
+/**
+ * a universally unambiguous date range
+ *
+ * note
+ * - since is inclusive (i.e., you've had freedom _since_ you gained it)
+ * - until is exclusive (i.e., you have money _until_ you run out)
+ */
+export type UniDateRange = AsOfGlossary<{
+    since: UniDate;
+    until: UniDate;
+}, 'uni-time', false>;
+export {};

package/dist/domain/UniDateTime.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asUniDate = exports.asUniDateTime = void 0;
+const error_fns_1 = require("@ehmpathy/error-fns");
+const date_fns_1 = require("date-fns");
+const castInputToDate = (input) => {
+    if (input instanceof Date)
+        return input;
+    if (typeof input === 'string')
+        return new Date(input);
+    if (input.date)
+        return input.date;
+    if (input.mse)
+        return new Date(input.mse);
+    throw new error_fns_1.UnexpectedCodePathError('could not parse date from input', {
+        input,
+    });
+};
+const asUniDateTime = (input) => castInputToDate(input).toISOString();
+exports.asUniDateTime = asUniDateTime;
+const asUniDate = (input) => (0, date_fns_1.format)(castInputToDate(input), 'yyyy-MM-dd');
+exports.asUniDate = asUniDate;
+//# sourceMappingURL=UniDateTime.js.map

package/dist/domain/UniDateTime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UniDateTime.js","sourceRoot":"","sources":["../../src/domain/UniDateTime.ts"],"names":[],"mappings":";;;AAAA,mDAA8D;AAC9D,uCAAkC;AAIlC,MAAM,eAAe,GAAG,CACtB,KAaM,EACN,EAAE;IACF,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IAClC,IAAI,KAAK,CAAC,GAAG;QAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,IAAI,mCAAuB,CAAC,iCAAiC,EAAE;QACnE,KAAK;KACN,CAAC,CAAC;AACL,CAAC,CAAC;AAMK,MAAM,aAAa,GAAG,CAC3B,KAA4C,EAC/B,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,WAAW,EAAiB,CAAC;AAFzD,QAAA,aAAa,iBAE4C;AAM/D,MAAM,SAAS,GAAG,CACvB,KAA4C,EACnC,EAAE,CAAC,IAAA,iBAAM,EAAC,eAAe,CAAC,KAAK,CAAC,EAAE,YAAY,CAAY,CAAC;AAFzD,QAAA,SAAS,aAEgD"}

package/dist/domain/UniDuration.d.ts

@@ -0,0 +1,10 @@
+import { AsOfGlossary } from 'domain-glossaries';
+import { PickOne } from 'type-fns';
+export type UniDuration = AsOfGlossary<PickOne<{
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}>, 'uni-time', false>;
+export declare const toMilliseconds: (duration: UniDuration) => number;

package/dist/domain/UniDuration.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMilliseconds = void 0;
+const error_fns_1 = require("@ehmpathy/error-fns");
+const toMilliseconds = (duration) => {
+    if (duration.days)
+        return duration.days * 24 * 60 * 60 * 1000;
+    if (duration.hours)
+        return duration.hours * 60 * 60 * 1000;
+    if (duration.minutes)
+        return duration.minutes * 60 * 1000;
+    if (duration.seconds)
+        return duration.seconds * 1000;
+    if (duration.milliseconds)
+        return duration.milliseconds;
+    throw new error_fns_1.UnexpectedCodePathError('unsupported duration unit to convert to milliseconds', { duration });
+};
+exports.toMilliseconds = toMilliseconds;
+//# sourceMappingURL=UniDuration.js.map

package/dist/domain/UniDuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UniDuration.js","sourceRoot":"","sources":["../../src/domain/UniDuration.ts"],"names":[],"mappings":";;;AAAA,mDAA8D;AAgBvD,MAAM,cAAc,GAAG,CAAC,QAAqB,EAAU,EAAE;IAC9D,IAAI,QAAQ,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC9D,IAAI,QAAQ,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC,KAAK,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC3D,IAAI,QAAQ,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC,OAAO,GAAG,EAAE,GAAG,IAAI,CAAC;IAC1D,IAAI,QAAQ,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;IACrD,IAAI,QAAQ,CAAC,YAAY;QAAE,OAAO,QAAQ,CAAC,YAAY,CAAC;IACxD,MAAM,IAAI,mCAAuB,CAC/B,sDAAsD,EACtD,EAAE,QAAQ,EAAE,CACb,CAAC;AACJ,CAAC,CAAC;AAVW,QAAA,cAAc,kBAUzB"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './domain/UniDateTime';
+export * from './domain/UniDuration';
+export * from './utils/sleep';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./domain/UniDateTime"), exports);
+__exportStar(require("./domain/UniDuration"), exports);
+__exportStar(require("./utils/sleep"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,uDAAqC;AACrC,gDAA8B"}

package/dist/utils/sleep.d.ts

@@ -0,0 +1,2 @@
+import { UniDuration } from '../domain/UniDuration';
+export declare const sleep: (ms: number | UniDuration) => Promise<void>;

package/dist/utils/sleep.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = void 0;
+const UniDuration_1 = require("../domain/UniDuration");
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, typeof ms === 'number' ? ms : (0, UniDuration_1.toMilliseconds)(ms)));
+exports.sleep = sleep;
+//# sourceMappingURL=sleep.js.map

package/dist/utils/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../src/utils/sleep.ts"],"names":[],"mappings":";;;AAAA,uDAAoE;AAE7D,MAAM,KAAK,GAAG,CAAC,EAAwB,EAAiB,EAAE,CAC/D,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CACtB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAA,4BAAc,EAAC,EAAE,CAAC,CAAC,CACtE,CAAC;AAHS,QAAA,KAAK,SAGd"}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@ehmpathy/uni-time",
+  "author": "ehmpathy",
+  "description": "a glossary of universally intuitive time, date, and duration domain literals",
+  "version": "1.0.1",
+  "repository": "ehmpathy/uni-time",
+  "homepage": "https://github.com/ehmpathy/uni-time",
+  "keywords": [
+    "time",
+    "date",
+    "datetime",
+    "UniDate",
+    "UniDateTime",
+    "UniDuration"
+  ],
+  "bugs": "https://github.com/ehmpathy/uni-time/issues",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build:ts": "tsc -p ./tsconfig.build.json",
+    "commit:with-cli": "npx cz",
+    "fix:format:prettier": "prettier --write '**/*.ts' --config ./prettier.config.js",
+    "fix:format": "npm run fix:format:prettier",
+    "fix:lint": "eslint -c ./.eslintrc.js src/**/*.ts --fix",
+    "build:clean": "rm dist/ -rf",
+    "build:compile": "tsc -p ./tsconfig.build.json",
+    "build": "npm run build:clean && npm run build:compile",
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
+    "test:types": "tsc -p ./tsconfig.build.json --noEmit",
+    "test:format:prettier": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js",
+    "test:format": "npm run test:format:prettier",
+    "test:lint:deps": "npx depcheck -c ./depcheckrc.yml",
+    "test:lint:eslint": "eslint -c ./.eslintrc.js src/**/*.ts",
+    "test:lint": "npm run test:lint:eslint && npm run test:lint:deps",
+    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
+    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "test": "npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "prepush": "npm run test && npm run build",
+    "prepublish": "npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "postinstall": "[ -d .git ] && npx husky install || exit 0"
+  },
+  "dependencies": {
+    "@ehmpathy/error-fns": "1.0.2",
+    "date-fns": "3.6.0",
+    "domain-glossaries": "1.0.0",
+    "type-fns": "0.8.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "17.6.7",
+    "@commitlint/config-conventional": "13.1.0",
+    "@trivago/prettier-plugin-sort-imports": "2.0.4",
+    "@tsconfig/node-lts-strictest": "18.12.1",
+    "@types/jest": "29.2.4",
+    "@typescript-eslint/eslint-plugin": "7.8.0",
+    "@typescript-eslint/parser": "7.8.0",
+    "core-js": "3.26.1",
+    "cz-conventional-changelog": "3.3.0",
+    "declapract": "^0.11.2",
+    "declapract-typescript-ehmpathy": "^0.31.6",
+    "depcheck": "1.4.3",
+    "eslint": "8.56.0",
+    "eslint-config-airbnb-typescript": "18.0.0",
+    "eslint-config-prettier": "8.5.0",
+    "eslint-plugin-import": "2.26.0",
+    "eslint-plugin-prettier": "4.2.1",
+    "husky": "8.0.3",
+    "jest": "29.3.1",
+    "prettier": "2.8.1",
+    "ts-jest": "29.1.3",
+    "ts-node": "10.9.2",
+    "typescript": "5.4.5"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "license": "MIT"
+}

package/readme.md

@@ -0,0 +1,75 @@
+# uni-time
+
+![test](https://github.com/ehmpathy/uni-time/workflows/test/badge.svg)
+![publish](https://github.com/ehmpathy/uni-time/workflows/publish/badge.svg)
+
+A glossary of intuitive, universally unambiguous time, date, and duration domain literals.
+
+# purpose
+
+declare a universally unambiguous serialization format for dates, times, and datetime
+- `UniDate` = `yyyy-MM-dd`
+- `UniTime` = `hh:mm:ss.sss`
+- `UniDateTime` = `yyyy-MM-ddThh:mm:ss.sssZ`
+
+declare a universally intuitive interface for durations
+- `UniDuration`
+
+usecases
+- clarify the format a date string should be in (`const since: UniDate = '2013-12-15`)
+- cast date to universal format (`const birthday: UniDate = toUniDate(new Date())`)
+- narrow type of strings with runtime validation (`if (!isUniDate(since)) throw new Error('wrong format')`)
+
+
+# install
+
+```sh
+npm install uni-time
+```
+
+# use
+
+## Time, Date, DateTime
+
+### declare that a date or datetime must be in the universal format
+
+```ts
+const noon: UniTime;
+const birthday: UniDate;
+const occurredAt: UniDateTime;
+```
+
+
+### assure that a date or datetime is in the universal format
+
+```ts
+const noon: UniTime = isUniTime.assure('12:00:00.000')
+const birthday: UniDate = isUniDate.assure('2013-12-15')
+const occurredAt: UniDateTime = isUniDateTime.assure('2013-12-15T07:21:13.555Z')
+```
+
+
+### cast a date or datetime into the universal format
+
+```ts
+const birthday: UniDate = asUniDate(new Date())
+const occurredAt: UniDateTime = asUniDateTime(new Date())
+```
+
+
+## Duration
+
+### declare a duration intuitively
+```ts
+const duration: UniDuration = { minutes: 7 }
+```
+
+### serialize to milliseconds
+```ts
+const durationInMs = toMilliseconds({ minutes: 7 })
+```
+
+### sleep
+```ts
+await sleep({ minutes: 7 })
+```