# timelong > 时间长度转换工具 Latest version **2.1.0** (published 2026-09-14) · MIT license · 24 weekly downloads ## Install ```sh npm install timelong pnpm add timelong yarn add timelong bun add timelong ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.1.0 | | Published | 2026-09-14 | | First published | 2021-07-22 | | Weekly downloads | 24 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=18 | | Dependencies | 0 | | Unpacked size | 23.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | folgerfan | | Maintainers | folger_fan | | Keywords | time, duration, parse, convert, timespan, milliseconds, typescript, zero-dependency | ## Links - npm: https://www.npmjs.com/package/timelong - Repository: https://cnb.cool/folger/timelong - npm.io page: https://npm.io/package/timelong ## Alternatives - [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads - [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads - [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads - [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads - [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads ## Recent versions - 2.1.0 (latest) — 2026-09-14 - 2.0.0 — 2026-05-15 - 1.6.0 — 2026-04-09 - 1.5.6 — 2025-06-24 - 1.5.5 — 2025-06-24 - 1.5.4 — 2025-06-24 - 1.4.0 — 2021-07-23 - 1.3.1 — 2021-07-23 - 1.3.0 — 2021-07-23 - 1.2.1 — 2021-07-23 - 1.2.0 — 2021-07-23 - 1.1.0 — 2021-07-22 ## README 简体中文 | [English](https://cnb.cool/folger/timelong/-/blob/main/README.en.md) ![badge](https://img.shields.io/npm/v/timelong.svg) ![badge](https://img.shields.io/badge/types-included-blue) # 简介 将`1h2m3s4ms`这种格式的字符串转为指定单位的时长 ``` timelong.ms1h2m3s4ms => 3723004 (ms) timelong.s1h2m3s4ms => 3723.004 (s) ``` 零依赖，无运行时开销（除首次属性访问的解析），支持 TypeScript 编译期校验。 # 使用 ```typescript import timelong from "timelong"; console.log(timelong.ms1d); ``` 属性名第一段是单位： | 单位 | 含义 | | ---- | ---- | | w | 星期 | | d | 天 | | h | 小时 | | m | 分钟 | | s | 秒 | | ms | 毫秒 | 后面是具体的时间长度，数字后面跟的具体单位： 1d4m 表示1天4分钟。 如`timelong.m1d4m`会换算成具体分钟数`24*60+4=1444` 也可以用中文，但不能中英文混用 中文单位有： 星期、周、天、日、小时、时、分钟、分、秒、毫秒 例如： ``` timelong.时1天 ``` # 注意事项 **1. 单位必须按 `w d h m s ms` 的顺序书写** 时长部分允许缺省部分单位，但不能颠倒顺序、也不能重复。顺序错误会返回 `undefined`： ```typescript timelong.ms1h30m; // ✅ 5400000 timelong.ms30m1h; // ❌ undefined（顺序错误） timelong.ms1d2d; // ❌ undefined（单位重复） ``` **2. 无法解析时返回 `undefined`，不抛错** 为符合 JS 对象语义，拼错单位的属性访问返回 `undefined` 而非抛错（v2 的破坏性变更）。 若需要拼错时立即报错，使用 `parseStrict`，或在调用点做校验： ```typescript import timelong, { parse, parseStrict } from "timelong"; // 直接访问：拼错返回 undefined（注意 undefined 参与运算会变成 NaN） timelong.ms1xyz; // undefined // 运行时解析动态字符串 parse("1h30m"); // 5400000 parse("abc"); // undefined parseStrict("abc"); // 抛 TypeError // 代理上也挂了同样的方法 timelong.parse("1h30m"); // 5400000 ``` **3. 非 `ms` 单位返回浮点数** 换算除不尽时会引入浮点误差，比较时建议用容差或统一换算到 `ms`： ```typescript timelong.s1ms; // 0.001 timelong.m1ms; // 1.6666666666666667e-5 ``` ## 运行时解析 除属性访问外，也可以解析变量或配置中的字符串： ```typescript import { parse, parseStrict } from "timelong"; parse("1d4m"); // 86640000 parse("1天"); // 86400000 parseStrict("1d4m"); // 86640000 ``` `parse` 返回毫秒数，无法解析时返回 `undefined`；`parseStrict` 在无法解析时抛出 `TypeError`。 # 背景 代码中经常会有定义时长的常量，例如： ``` // axios默认超时时间 export const AXIOS_TIMEOUT_DEFAULT = 5000; // ms ``` 简单的还好，还有稍微需要计算的需要在脑袋里过一遍，例如： ``` export const TASK_TIMEOUT_PERIOD = 20 * 60 * 1000; // ms ``` 时间单位有可能是分钟、秒等非毫秒数，如果代码里不写注释和毫秒数的时间放在一起，可能会让人感到疑惑，例如： ``` // redis 过期时间 export const REDIS_EXPIRE_TIME = 7 * 24 * 60 * 60; // s ``` 如果有一个工具能按照一定格式自动生成想要的时长，我们就能偷点懒了，可读性也强些。 上面的例子就会变成 ``` export const AXIOS_TIMEOUT_DEFAULT = timelong.ms5s; export const TASK_TIMEOUT_PERIOD = timelong.ms20m; export const REDIS_EXPIRE_TIME = timelong.s7d; ``` # 示例 ``` expect(timelong.ms1ms).toBe(1); expect(timelong.ms1s).toBe(1 * 1000); expect(timelong.ms1m).toBe(1 * 60 * 1000); expect(timelong.ms1h).toBe(1 * 60 * 60 * 1000); expect(timelong.ms1d).toBe(1 * 24 * 60 * 60 * 1000); expect(timelong.ms1w).toBe(1 * 7 * 24 * 60 * 60 * 1000); expect(timelong.ms12w34d56h78m9s10ms).toBe( 12 * timelong.ms1w + 34 * timelong.ms1d + 56 * timelong.ms1h + 78 * timelong.ms1m + 9 * timelong.ms1s + 10 ); ``` ``` expect(timelong.m1ms).toBeCloseTo(1 / 1000 / 60); expect(timelong.m1s).toBeCloseTo(1 / 60); expect(timelong.m1m).toBe(1); expect(timelong.m1h).toBe(1 * 60); expect(timelong.m1d).toBe(1 * 24 * 60); expect(timelong.m1w).toBe(1 * 7 * 24 * 60); expect(timelong.m12w34d56h78m9s10ms).toBeCloseTo( 12 * timelong.m1w + 34 * timelong.m1d + 56 * timelong.m1h + 78 * timelong.m1m + 9 * timelong.m1s + 10 * timelong.m1ms ); ``` ``` expect(timelong.时1日).toBe(1 * 24); expect(timelong.小时1日).toBe(1 * 24); expect(timelong.时1天).toBe(1 * 24); expect(timelong.小时1天).toBe(1 * 24); ``` 以此类推 # 实现原理 `Proxy`解析属性名为具体的单位、星期数、天数、小时数、分数、秒数和毫秒数再累加相除 --- _Source: https://npm.io/package/timelong · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._