@thi.ng/date 2.8.10 → 3.0.0

package/README.md

@@ -71,7 +71,7 @@ For Node.js REPL:
 const date = await import("@thi.ng/date");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.43 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.53 KB
 
 ## Dependencies
 
@@ -404,6 +404,7 @@ The following preset formatters are available:
 - `FMT_HHmmss` - `"21:42:07"`
 - `FMT_HHmmss_ALT` - `"214207"`
 - `FMT_hms` - `"9:42:07 PM"`
+- `FMT_mmss` - `"42:07"`
 - `FMT_yyyy` - `"2020"` (4 digit year)
 - `FMT_MM` - `"12"` (2 digit month)
 - `FMT_ww` - `"52"` (2 digit week)
@@ -424,28 +425,50 @@ defFormat([FMT_yyyyMMdd, " @ ", FMT_HHmmss])();
 
 ### Timecodes
 
-For timebased media applications, the higher-order `defTimecode()` can be used
-to create a formatter for a given FPS (frames / second, in [1..1000] range),
-e.g. `HH:mm:ss:ff`. The returned function takes a single arg (time in
-milliseconds) and returns formatted string.
+For timebased media applications, the configurable higher-order `defTimecode()`
+can be used to create a formatter for a given FPS (frames per second, in
+[1..1000] range), e.g. `HH:mm:ss:ff`. The returned function takes a single arg
+(time in milliseconds) and returns a formatted string.
 
-The timecode considers days too, but only includes them in the result if the day
-part is non-zero. The 4 separators between each field can be customized via 2nd
-arg (default: all `:`).
+The timecode considers days too, but by default only includes them in the result
+if the day part is non-zero. The 4 separators between each field can be
+customized via the `sep`
+[option](https://docs.thi.ng/umbrella/date/interfaces/TimecodeOpts). The minute
+and second parts are the only ones which will always be present. The visibility
+of others can be configured. Depending on FPS, the frame part will be between
+2-4 digits (zero-padded).
 
 ```ts
 import { defTimecode, DAY, HOUR, MINUTE, SECOND } from "@thi.ng/date";
 
-const a = defTimecode(30);
-a(1*HOUR + 2*MINUTE + 3*SECOND + 4*1000/30)
-// "01:02:03:04"
+// use 30 fps w/ default options
+const fmt = defTimecode(30);
 
-a(DAY);
-// "01:00:00:00:00"
+// day part omitted by default if zero
+console.log(
+    fmt(HOUR + 2*MINUTE + 3*SECOND + 4*SECOND/30)
+);
+// 01:02:03:04
 
-const b = defTimecode(30, ["d ", "h ", "' ", '" ']);
-b(DAY + HOUR + 2*MINUTE + 3*SECOND + 999)
-// "01d 01h 02' 03" 29"
+// ...but shown if needed
+console.log(fmt(DAY));
+// 01:00:00:00:00
+
+// use custom seperators
+const fmt2 = defTimecode(30, { sep: ["d ", "h ", "' ", '" '] });
+
+console.log(
+    fmt2(DAY + 2*HOUR + 3*MINUTE + 4*SECOND + 999)
+);
+// 01d 02h 03' 04" 29
+
+// only use `min:sec`
+const fmt3 = defTimecode(30, { hour: false, frames: false });
+
+console.log(
+    fmt3(12 * MINUTE + 34 * SECOND)
+);
+// 12:34
 ```
 
 ### Locales
@@ -492,9 +515,10 @@ fmt(dateTime());
 // Saturday 19 September 2020
 ```
 
-Use [`withLocale()`](https://docs.thi.ng/umbrella/date/functions/withLocale.html)
-to only temporarily set a locale and execute a function with it, then
-automatically restoring the currently active locale.
+Use
+[`withLocale()`](https://docs.thi.ng/umbrella/date/functions/withLocale.html) to
+only temporarily set a locale and execute a function with it, then automatically
+restoring the currently active locale.
 
 ```ts
 import { dateTime, withLocale, FR_LONG } from "@thi.ng/date";

package/datetime.d.ts

@@ -118,5 +118,5 @@ export declare const ensureDateTime: (x: MaybeDate, prec?: Precision) => DateTim
  *
  * @param x -
  */
-export declare const maybeIsDate: (x: any) => x is string | number | DateTime | Date;
+export declare const maybeIsDate: (x: any) => x is string | number | Date | DateTime;
 //# sourceMappingURL=datetime.d.ts.map

package/format.d.ts

@@ -65,6 +65,8 @@ export declare const FMT_HHmm: Formatter;
 /**
  * Format preset, e.g. `5:08 PM`
  */
+export declare const FMT_hmm: Formatter;
+/** @deprecated renamed to {@link FMT_hmm} */
 export declare const FMT_hm: Formatter;
 /**
  * Format preset, e.g. `17:08:01`
@@ -78,6 +80,10 @@ export declare const FMT_HHmmss_ALT: Formatter;
  * Format preset, e.g. `5:08:01 PM`
  */
 export declare const FMT_hms: Formatter;
+/**
+ * Format preset, 2-digit minute and second only (mm:ss)
+ */
+export declare const FMT_mmss: Formatter;
 /**
  * Format preset, e.g. `20200919-170801`
  */

package/format.js

@@ -169,10 +169,12 @@ const FMT_MMMdyyyy = defFormat(["MMM", " ", "d", " ", "yyyy"]);
 const FMT_dMyyyy = defFormat(["d", "/DM", "M", "/MY", "yyyy"]);
 const FMT_dMMMyyyy = defFormat(["d", "/DM", "MMM", " ", "yyyy"]);
 const FMT_HHmm = defFormat(["HH", "/HM", "mm"]);
-const FMT_hm = defFormat(["h", "/HM", "mm", " ", "A"]);
+const FMT_hmm = defFormat(["h", "/HM", "mm", " ", "A"]);
+const FMT_hm = FMT_hmm;
 const FMT_HHmmss = defFormat(["HH", "/HM", "mm", "/MS", "ss"]);
 const FMT_HHmmss_ALT = defFormat(["HH", "mm", "ss"]);
 const FMT_hms = defFormat(["h", "/HM", "mm", "/MS", "ss", " ", "A"]);
+const FMT_mmss = defFormat(["mm", "/MS", "ss"]);
 const FMT_yyyyMMdd_HHmmss = defFormat(
   ["yyyy", "MM", "dd", "-", "HH", "mm", "ss"]
 );
@@ -258,8 +260,10 @@ export {
   FMT_dMyyyy,
   FMT_dd,
   FMT_hm,
+  FMT_hmm,
   FMT_hms,
   FMT_mm,
+  FMT_mmss,
   FMT_ss,
   FMT_ww,
   FMT_yyyy,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/date",
-	"version": "2.8.10",
+	"version": "3.0.0",
 	"description": "Datetime types, relative dates, math, iterators, composable formatters, locales",
 	"type": "module",
 	"module": "./index.js",
@@ -40,12 +40,12 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.26",
-		"@thi.ng/checks": "^3.10.0",
-		"@thi.ng/strings": "^3.12.8"
+		"@thi.ng/api": "^8.12.27",
+		"@thi.ng/checks": "^3.10.1",
+		"@thi.ng/strings": "^3.12.9"
 	},
 	"devDependencies": {
-		"esbuild": "^0.28.0",
+		"esbuild": "^0.28.1",
 		"typedoc": "^0.28.19",
 		"typescript": "^6.0.3"
 	},
@@ -135,5 +135,5 @@
 	"thi.ng": {
 		"year": 2020
 	},
-	"gitHead": "c47c56420bcae2e0477d252a497be44f08ca185a"
+	"gitHead": "febee81fd8b59e5e330a6e6521a2667ed5401a3d"
 }

package/timecode.d.ts

@@ -1,37 +1,78 @@
 /**
- * Returns a time formatter for given FPS (frames / second, in `[1,1000]`
+ * Options for {@link defTimecode}.
+ */
+export interface TimecodeOpts {
+    /**
+     * Timecode part separators in the following order: day, hour, minute,
+     * second. By default uses `:` for all.
+     */
+    sep: ArrayLike<string>;
+    /**
+     * If true (default: false), the day timecode part will always be included
+     * in output. If false, only if the value is non-zero.
+     */
+    day: boolean;
+    /**
+     * If true (default), the hour timecode part will always be included in
+     * output. If false, only if the value is non-zero (or if day is used).
+     */
+    hour: boolean;
+    /**
+     * If true (default), frame timecode part will be included.
+     */
+    frame: boolean;
+}
+/**
+ * Returns a time formatter for given `fps` (frames per second, in `[1,1000]`
  * range), e.g. `HH:mm:ss:ff`. The returned function takes a single arg (time in
- * milliseconds) and returns formatted string.
+ * milliseconds) and returns a formatted string.
  *
  * @remarks
- * The timecode considers days too, but only includes them in the result if the
- * day part is non-zero. The 4 separators between each field can be customized
- * via 2nd arg (default: all `:`).
+ * The timecode considers days too, but by default only includes them in the
+ * result if the day part is non-zero. The 4 separators between each field can
+ * be customized via the {@link TimecodeOpts.sep} option.
+ *
+ * The minute and second parts are the only ones which will always be present.
+ * The visibility of others can be configured.
+ *
+ * Depending on FPS, the frame part will be between 2-4 digits (zero-padded).
  *
  * @example
  * ```ts tangle:../export/timecode.ts
  * import { defTimecode, DAY, HOUR, MINUTE, SECOND } from "@thi.ng/date";
  *
+ * // use 30 fps w/ default options
  * const fmt = defTimecode(30);
  *
+ * // day part omitted by default if zero
  * console.log(
- *   fmt(HOUR + 2*MINUTE + 3*SECOND + 4*1000/30)
+ *   fmt(HOUR + 2*MINUTE + 3*SECOND + 4*SECOND/30)
  * );
- * // "01:02:03:04"
+ * // 01:02:03:04
  *
+ * // ...but shown if needed
  * console.log(fmt(DAY));
- * // "01:00:00:00:00"
+ * // 01:00:00:00:00
+ *
+ * // use custom seperators
+ * const fmt2 = defTimecode(30, { sep: ["d ", "h ", "' ", '" '] });
+ *
+ * console.log(
+ *   fmt2(DAY + 2*HOUR + 3*MINUTE + 4*SECOND + 999)
+ * );
+ * // 01d 02h 03' 04" 29
  *
- * const fmt2 = defTimecode(30, ["d ", "h ", "' ", '" ']);
+ * // only use `min:sec`
+ * const fmt3 = defTimecode(30, { hour: false, frames: false });
  *
  * console.log(
- *   fmt2(DAY + HOUR + 2 * MINUTE + 3 * SECOND + 999)
+ *   fmt3(12 * MINUTE + 34 * SECOND)
  * );
- * // "01d 01h 02' 03" 29"
+ * // 12:34
  * ```
  *
  * @param fps -
- * @param sep -
+ * @param opts -
  */
-export declare const defTimecode: (fps: number, sep?: ArrayLike<string>) => (t: number) => string;
+export declare const defTimecode: (fps: number, opts?: Partial<TimecodeOpts>) => (t: number) => string;
 //# sourceMappingURL=timecode.d.ts.map

package/timecode.js

@@ -1,20 +1,23 @@
-import { Z2 } from "@thi.ng/strings/pad-left";
+import { Z2, Z3, Z4 } from "@thi.ng/strings/pad-left";
 import { decomposeDuration } from "./duration.js";
-const defTimecode = (fps, sep = "::::") => {
+const defTimecode = (fps, opts = {}) => {
+  const {
+    sep = "::::",
+    day = false,
+    hour = true,
+    frame: useFrame = true
+  } = opts;
   const frame = 1e3 / fps;
+  const $sep = (x) => sep[x] ?? ":";
+  const fmtFrame = fps < 100 ? Z2 : fps < 1e3 ? Z3 : Z4;
   return (t) => {
     const [_, __, d, h, m, s, ms] = decomposeDuration(t);
-    const parts = [
-      Z2(h),
-      sep[1],
-      Z2(m),
-      sep[2],
-      Z2(s),
-      sep[3],
-      Z2(ms / frame | 0)
-    ];
-    d > 0 && parts.unshift(Z2(d), sep[0]);
-    return parts.join("");
+    let parts = "";
+    if (d || day) parts += Z2(d) + $sep(0);
+    if (h || d || day || hour) parts += Z2(h) + $sep(1);
+    parts += Z2(m) + $sep(2) + Z2(s);
+    if (useFrame) parts += $sep(3) + fmtFrame(ms / frame | 0);
+    return parts;
   };
 };
 export {