@nixxie-cms/fields-duration 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+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/README.md

@@ -0,0 +1,22 @@
+# @nixxie-cms/fields-duration
+
+A duration field for Nixxie CMS. Stores a whole number of **seconds** on the core `integer`
+field, with optional `min`/`max` bounds enforced via validation hooks.
+
+```ts
+import { duration } from '@nixxie-cms/fields-duration'
+
+fields: {
+  runtime: duration({
+    min: 60,          // at least one minute
+    max: 4 * 3600,    // at most four hours
+    validation: { isRequired: true },
+  }),
+}
+```
+
+Also exports dependency-free helpers:
+
+- `formatDuration(seconds)` → `"1h 30m 5s"` (omits zero units, `"0s"` for 0)
+- `parseDuration(input)` → seconds or `null`; accepts `"90"`, `"90s"`, `"1h 30m"`,
+  `"1:30:05"` and ISO-8601 (`"PT1H30M5S"`)

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,35 @@
+import type { IntegerFieldConfig } from '@nixxie-cms/core/fields';
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types';
+/**
+ * Format a duration in seconds as `"1h 30m 5s"`. Zero units are omitted (`3600` → `"1h"`),
+ * zero itself is `"0s"`, and negative durations get a leading `-`. Hours are not rolled up
+ * into days (`90000` → `"25h"`). Fractional input is rounded; non-finite input yields `''`.
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Parse a human-entered duration into whole seconds. Dependency-free; accepts:
+ * - plain seconds: `"90"`
+ * - unit tokens: `"90s"`, `"1h 30m"`, `"2d 4h"` (units `d`, `h`, `m`, `s`, case-insensitive)
+ * - colon notation: `"1:30:05"` (h:mm:ss) or `"1:30"` (m:ss)
+ * - ISO-8601 durations: `"PT1H30M5S"`, `"P1DT12H"` (day/time components only)
+ *
+ * Fractional values are rounded to the nearest second. Returns `null` when unparseable.
+ */
+export declare function parseDuration(input: string): number | null;
+export type DurationFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<IntegerFieldConfig<CollectionTypeInfo>, 'validation'> & {
+    /** Smallest allowed duration, in seconds. */
+    min?: number;
+    /** Largest allowed duration, in seconds. */
+    max?: number;
+    validation?: {
+        /** Reject saving when no value is present. */
+        isRequired?: boolean;
+    };
+};
+/**
+ * A duration field storing a whole number of SECONDS. Built on the core `integer` field with
+ * optional `min`/`max` bounds enforced via a validate hook. Use `formatDuration` /
+ * `parseDuration` to convert to and from human-readable forms.
+ */
+export declare function duration<CollectionTypeInfo extends BaseCollectionTypeInfo>(config?: DurationFieldConfig<CollectionTypeInfo>): FieldTypeFunc<CollectionTypeInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAMnF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAatD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiD1D;AAED,MAAM,MAAM,mBAAmB,CAAC,kBAAkB,SAAS,sBAAsB,IAAI,IAAI,CACvF,kBAAkB,CAAC,kBAAkB,CAAC,EACtC,YAAY,CACb,GAAG;IACF,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE;QACX,8CAA8C;QAC9C,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;CACF,CAAA;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,kBAAkB,SAAS,sBAAsB,EACxE,MAAM,GAAE,mBAAmB,CAAC,kBAAkB,CAAM,GACnD,aAAa,CAAC,kBAAkB,CAAC,CA+BnC"}

package/dist/nixxie-cms-fields-duration.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1maWVsZHMtZHVyYXRpb24uY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/nixxie-cms-fields-duration.cjs.js

@@ -0,0 +1,133 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fields = require('@nixxie-cms/core/fields');
+
+const SECONDS_PER_MINUTE = 60;
+const SECONDS_PER_HOUR = 3600;
+const SECONDS_PER_DAY = 86400;
+
+/**
+ * Format a duration in seconds as `"1h 30m 5s"`. Zero units are omitted (`3600` → `"1h"`),
+ * zero itself is `"0s"`, and negative durations get a leading `-`. Hours are not rolled up
+ * into days (`90000` → `"25h"`). Fractional input is rounded; non-finite input yields `''`.
+ */
+function formatDuration(seconds) {
+  if (!Number.isFinite(seconds)) return '';
+  const sign = seconds < 0 ? '-' : '';
+  const total = Math.round(Math.abs(seconds));
+  const h = Math.floor(total / SECONDS_PER_HOUR);
+  const m = Math.floor(total % SECONDS_PER_HOUR / SECONDS_PER_MINUTE);
+  const s = total % SECONDS_PER_MINUTE;
+  const parts = [];
+  if (h > 0) parts.push(`${h}h`);
+  if (m > 0) parts.push(`${m}m`);
+  if (s > 0) parts.push(`${s}s`);
+  if (parts.length === 0) return '0s';
+  return sign + parts.join(' ');
+}
+
+/**
+ * Parse a human-entered duration into whole seconds. Dependency-free; accepts:
+ * - plain seconds: `"90"`
+ * - unit tokens: `"90s"`, `"1h 30m"`, `"2d 4h"` (units `d`, `h`, `m`, `s`, case-insensitive)
+ * - colon notation: `"1:30:05"` (h:mm:ss) or `"1:30"` (m:ss)
+ * - ISO-8601 durations: `"PT1H30M5S"`, `"P1DT12H"` (day/time components only)
+ *
+ * Fractional values are rounded to the nearest second. Returns `null` when unparseable.
+ */
+function parseDuration(input) {
+  const s = input.trim();
+  if (s === '') return null;
+
+  // Plain number of seconds, e.g. "90" or "90.5".
+  if (/^\d+(?:\.\d+)?$/.test(s)) return Math.round(parseFloat(s));
+
+  // ISO-8601 duration, limited to day/time components (P1DT2H3M4S). Years/months/weeks have
+  // no fixed length in seconds, so they are deliberately not supported.
+  const iso = /^P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i.exec(s);
+  if (iso) {
+    const [, d, h, m, sec] = iso;
+    // Bare "P"/"PT" matches the regex but carries no components — reject it.
+    if (d === undefined && h === undefined && m === undefined && sec === undefined) return null;
+    return Math.round(parseFloat(d !== null && d !== void 0 ? d : '0') * SECONDS_PER_DAY + parseFloat(h !== null && h !== void 0 ? h : '0') * SECONDS_PER_HOUR + parseFloat(m !== null && m !== void 0 ? m : '0') * SECONDS_PER_MINUTE + parseFloat(sec !== null && sec !== void 0 ? sec : '0'));
+  }
+
+  // Colon notation: "1:30:05" (h:mm:ss) or "1:30" (m:ss).
+  const colon = /^(\d+):([0-5]?\d)(?::([0-5]?\d))?$/.exec(s);
+  if (colon) {
+    const [, a, b, c] = colon;
+    return c !== undefined ? parseInt(a, 10) * SECONDS_PER_HOUR + parseInt(b, 10) * SECONDS_PER_MINUTE + parseInt(c, 10) : parseInt(a, 10) * SECONDS_PER_MINUTE + parseInt(b, 10);
+  }
+
+  // Unit tokens: "1h 30m 5s", "90s", "2d4h" — one or more value/unit pairs.
+  if (/^(?:\s*\d+(?:\.\d+)?\s*[dhms]\s*)+$/i.test(s)) {
+    const multipliers = {
+      d: SECONDS_PER_DAY,
+      h: SECONDS_PER_HOUR,
+      m: SECONDS_PER_MINUTE,
+      s: 1
+    };
+    let total = 0;
+    const token = /(\d+(?:\.\d+)?)\s*([dhms])/gi;
+    let match;
+    while (match = token.exec(s)) {
+      total += parseFloat(match[1]) * multipliers[match[2].toLowerCase()];
+    }
+    return Math.round(total);
+  }
+  return null;
+}
+/**
+ * A duration field storing a whole number of SECONDS. Built on the core `integer` field with
+ * optional `min`/`max` bounds enforced via a validate hook. Use `formatDuration` /
+ * `parseDuration` to convert to and from human-readable forms.
+ */
+function duration(config = {}) {
+  const {
+    min,
+    max,
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  const userValidate = hooks === null || hooks === void 0 ? void 0 : hooks.validate;
+  return fields.integer({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'Duration in seconds',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      validate: async args => {
+        var _userValidate;
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args);else await (userValidate === null || userValidate === void 0 || (_userValidate = userValidate[args.operation]) === null || _userValidate === void 0 ? void 0 : _userValidate.call(userValidate, args));
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value !== 'number') return;
+        if (min !== undefined && value < min) {
+          addValidationError(`${fieldKey} must be at least ${min} seconds (${formatDuration(min)})`);
+        }
+        if (max !== undefined && value > max) {
+          addValidationError(`${fieldKey} must be at most ${max} seconds (${formatDuration(max)})`);
+        }
+      }
+    }
+  });
+}
+
+exports.duration = duration;
+exports.formatDuration = formatDuration;
+exports.parseDuration = parseDuration;

package/dist/nixxie-cms-fields-duration.esm.js

@@ -0,0 +1,127 @@
+import { integer } from '@nixxie-cms/core/fields';
+
+const SECONDS_PER_MINUTE = 60;
+const SECONDS_PER_HOUR = 3600;
+const SECONDS_PER_DAY = 86400;
+
+/**
+ * Format a duration in seconds as `"1h 30m 5s"`. Zero units are omitted (`3600` → `"1h"`),
+ * zero itself is `"0s"`, and negative durations get a leading `-`. Hours are not rolled up
+ * into days (`90000` → `"25h"`). Fractional input is rounded; non-finite input yields `''`.
+ */
+function formatDuration(seconds) {
+  if (!Number.isFinite(seconds)) return '';
+  const sign = seconds < 0 ? '-' : '';
+  const total = Math.round(Math.abs(seconds));
+  const h = Math.floor(total / SECONDS_PER_HOUR);
+  const m = Math.floor(total % SECONDS_PER_HOUR / SECONDS_PER_MINUTE);
+  const s = total % SECONDS_PER_MINUTE;
+  const parts = [];
+  if (h > 0) parts.push(`${h}h`);
+  if (m > 0) parts.push(`${m}m`);
+  if (s > 0) parts.push(`${s}s`);
+  if (parts.length === 0) return '0s';
+  return sign + parts.join(' ');
+}
+
+/**
+ * Parse a human-entered duration into whole seconds. Dependency-free; accepts:
+ * - plain seconds: `"90"`
+ * - unit tokens: `"90s"`, `"1h 30m"`, `"2d 4h"` (units `d`, `h`, `m`, `s`, case-insensitive)
+ * - colon notation: `"1:30:05"` (h:mm:ss) or `"1:30"` (m:ss)
+ * - ISO-8601 durations: `"PT1H30M5S"`, `"P1DT12H"` (day/time components only)
+ *
+ * Fractional values are rounded to the nearest second. Returns `null` when unparseable.
+ */
+function parseDuration(input) {
+  const s = input.trim();
+  if (s === '') return null;
+
+  // Plain number of seconds, e.g. "90" or "90.5".
+  if (/^\d+(?:\.\d+)?$/.test(s)) return Math.round(parseFloat(s));
+
+  // ISO-8601 duration, limited to day/time components (P1DT2H3M4S). Years/months/weeks have
+  // no fixed length in seconds, so they are deliberately not supported.
+  const iso = /^P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i.exec(s);
+  if (iso) {
+    const [, d, h, m, sec] = iso;
+    // Bare "P"/"PT" matches the regex but carries no components — reject it.
+    if (d === undefined && h === undefined && m === undefined && sec === undefined) return null;
+    return Math.round(parseFloat(d !== null && d !== void 0 ? d : '0') * SECONDS_PER_DAY + parseFloat(h !== null && h !== void 0 ? h : '0') * SECONDS_PER_HOUR + parseFloat(m !== null && m !== void 0 ? m : '0') * SECONDS_PER_MINUTE + parseFloat(sec !== null && sec !== void 0 ? sec : '0'));
+  }
+
+  // Colon notation: "1:30:05" (h:mm:ss) or "1:30" (m:ss).
+  const colon = /^(\d+):([0-5]?\d)(?::([0-5]?\d))?$/.exec(s);
+  if (colon) {
+    const [, a, b, c] = colon;
+    return c !== undefined ? parseInt(a, 10) * SECONDS_PER_HOUR + parseInt(b, 10) * SECONDS_PER_MINUTE + parseInt(c, 10) : parseInt(a, 10) * SECONDS_PER_MINUTE + parseInt(b, 10);
+  }
+
+  // Unit tokens: "1h 30m 5s", "90s", "2d4h" — one or more value/unit pairs.
+  if (/^(?:\s*\d+(?:\.\d+)?\s*[dhms]\s*)+$/i.test(s)) {
+    const multipliers = {
+      d: SECONDS_PER_DAY,
+      h: SECONDS_PER_HOUR,
+      m: SECONDS_PER_MINUTE,
+      s: 1
+    };
+    let total = 0;
+    const token = /(\d+(?:\.\d+)?)\s*([dhms])/gi;
+    let match;
+    while (match = token.exec(s)) {
+      total += parseFloat(match[1]) * multipliers[match[2].toLowerCase()];
+    }
+    return Math.round(total);
+  }
+  return null;
+}
+/**
+ * A duration field storing a whole number of SECONDS. Built on the core `integer` field with
+ * optional `min`/`max` bounds enforced via a validate hook. Use `formatDuration` /
+ * `parseDuration` to convert to and from human-readable forms.
+ */
+function duration(config = {}) {
+  const {
+    min,
+    max,
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  const userValidate = hooks === null || hooks === void 0 ? void 0 : hooks.validate;
+  return integer({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'Duration in seconds',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      validate: async args => {
+        var _userValidate;
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args);else await (userValidate === null || userValidate === void 0 || (_userValidate = userValidate[args.operation]) === null || _userValidate === void 0 ? void 0 : _userValidate.call(userValidate, args));
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value !== 'number') return;
+        if (min !== undefined && value < min) {
+          addValidationError(`${fieldKey} must be at least ${min} seconds (${formatDuration(min)})`);
+        }
+        if (max !== undefined && value > max) {
+          addValidationError(`${fieldKey} must be at most ${max} seconds (${formatDuration(max)})`);
+        }
+      }
+    }
+  });
+}
+
+export { duration, formatDuration, parseDuration };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/fields-duration",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-fields-duration.cjs.js",
+  "module": "dist/nixxie-cms-fields-duration.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-fields-duration.cjs.js",
+      "module": "./dist/nixxie-cms-fields-duration.esm.js",
+      "default": "./dist/nixxie-cms-fields-duration.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/fields-duration"
+  }
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+import { integer } from '@nixxie-cms/core/fields'
+import type { IntegerFieldConfig } from '@nixxie-cms/core/fields'
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types'
+
+const SECONDS_PER_MINUTE = 60
+const SECONDS_PER_HOUR = 3600
+const SECONDS_PER_DAY = 86400
+
+/**
+ * Format a duration in seconds as `"1h 30m 5s"`. Zero units are omitted (`3600` → `"1h"`),
+ * zero itself is `"0s"`, and negative durations get a leading `-`. Hours are not rolled up
+ * into days (`90000` → `"25h"`). Fractional input is rounded; non-finite input yields `''`.
+ */
+export function formatDuration(seconds: number): string {
+  if (!Number.isFinite(seconds)) return ''
+  const sign = seconds < 0 ? '-' : ''
+  const total = Math.round(Math.abs(seconds))
+  const h = Math.floor(total / SECONDS_PER_HOUR)
+  const m = Math.floor((total % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE)
+  const s = total % SECONDS_PER_MINUTE
+  const parts: string[] = []
+  if (h > 0) parts.push(`${h}h`)
+  if (m > 0) parts.push(`${m}m`)
+  if (s > 0) parts.push(`${s}s`)
+  if (parts.length === 0) return '0s'
+  return sign + parts.join(' ')
+}
+
+/**
+ * Parse a human-entered duration into whole seconds. Dependency-free; accepts:
+ * - plain seconds: `"90"`
+ * - unit tokens: `"90s"`, `"1h 30m"`, `"2d 4h"` (units `d`, `h`, `m`, `s`, case-insensitive)
+ * - colon notation: `"1:30:05"` (h:mm:ss) or `"1:30"` (m:ss)
+ * - ISO-8601 durations: `"PT1H30M5S"`, `"P1DT12H"` (day/time components only)
+ *
+ * Fractional values are rounded to the nearest second. Returns `null` when unparseable.
+ */
+export function parseDuration(input: string): number | null {
+  const s = input.trim()
+  if (s === '') return null
+
+  // Plain number of seconds, e.g. "90" or "90.5".
+  if (/^\d+(?:\.\d+)?$/.test(s)) return Math.round(parseFloat(s))
+
+  // ISO-8601 duration, limited to day/time components (P1DT2H3M4S). Years/months/weeks have
+  // no fixed length in seconds, so they are deliberately not supported.
+  const iso = /^P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i.exec(s)
+  if (iso) {
+    const [, d, h, m, sec] = iso
+    // Bare "P"/"PT" matches the regex but carries no components — reject it.
+    if (d === undefined && h === undefined && m === undefined && sec === undefined) return null
+    return Math.round(
+      parseFloat(d ?? '0') * SECONDS_PER_DAY +
+        parseFloat(h ?? '0') * SECONDS_PER_HOUR +
+        parseFloat(m ?? '0') * SECONDS_PER_MINUTE +
+        parseFloat(sec ?? '0')
+    )
+  }
+
+  // Colon notation: "1:30:05" (h:mm:ss) or "1:30" (m:ss).
+  const colon = /^(\d+):([0-5]?\d)(?::([0-5]?\d))?$/.exec(s)
+  if (colon) {
+    const [, a, b, c] = colon
+    return c !== undefined
+      ? parseInt(a, 10) * SECONDS_PER_HOUR + parseInt(b, 10) * SECONDS_PER_MINUTE + parseInt(c, 10)
+      : parseInt(a, 10) * SECONDS_PER_MINUTE + parseInt(b, 10)
+  }
+
+  // Unit tokens: "1h 30m 5s", "90s", "2d4h" — one or more value/unit pairs.
+  if (/^(?:\s*\d+(?:\.\d+)?\s*[dhms]\s*)+$/i.test(s)) {
+    const multipliers: Record<string, number> = {
+      d: SECONDS_PER_DAY,
+      h: SECONDS_PER_HOUR,
+      m: SECONDS_PER_MINUTE,
+      s: 1,
+    }
+    let total = 0
+    const token = /(\d+(?:\.\d+)?)\s*([dhms])/gi
+    let match: RegExpExecArray | null
+    while ((match = token.exec(s))) {
+      total += parseFloat(match[1]) * multipliers[match[2].toLowerCase()]
+    }
+    return Math.round(total)
+  }
+
+  return null
+}
+
+export type DurationFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<
+  IntegerFieldConfig<CollectionTypeInfo>,
+  'validation'
+> & {
+  /** Smallest allowed duration, in seconds. */
+  min?: number
+  /** Largest allowed duration, in seconds. */
+  max?: number
+  validation?: {
+    /** Reject saving when no value is present. */
+    isRequired?: boolean
+  }
+}
+
+/**
+ * A duration field storing a whole number of SECONDS. Built on the core `integer` field with
+ * optional `min`/`max` bounds enforced via a validate hook. Use `formatDuration` /
+ * `parseDuration` to convert to and from human-readable forms.
+ */
+export function duration<CollectionTypeInfo extends BaseCollectionTypeInfo>(
+  config: DurationFieldConfig<CollectionTypeInfo> = {}
+): FieldTypeFunc<CollectionTypeInfo> {
+  const { min, max, hooks, validation, ...rest } = config
+  const userValidate = hooks?.validate as
+    | ((args: any) => unknown)
+    | { create?: (args: any) => unknown; update?: (args: any) => unknown; delete?: (args: any) => unknown }
+    | undefined
+
+  return integer<CollectionTypeInfo>({
+    ...(rest as IntegerFieldConfig<CollectionTypeInfo>),
+    validation: { isRequired: validation?.isRequired },
+    ui: { description: 'Duration in seconds', ...rest.ui },
+    hooks: {
+      ...hooks,
+      validate: async (args: any) => {
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args)
+        else await userValidate?.[args.operation as 'create' | 'update' | 'delete']?.(args)
+
+        const { resolvedData, fieldKey, addValidationError, operation } = args
+        if (operation === 'delete') return
+        const value = resolvedData[fieldKey]
+        if (typeof value !== 'number') return
+        if (min !== undefined && value < min) {
+          addValidationError(`${fieldKey} must be at least ${min} seconds (${formatDuration(min)})`)
+        }
+        if (max !== undefined && value > max) {
+          addValidationError(`${fieldKey} must be at most ${max} seconds (${formatDuration(max)})`)
+        }
+      },
+    },
+  })
+}