humane-ts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Woodell
+
+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

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# humane-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![CI](https://github.com/woodie/humane-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/woodie/humane-ts/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/woodie/humane-ts.svg)](https://github.com/woodie/humane-ts/releases/latest)
+[![License](https://img.shields.io/github/license/woodie/humane-ts.svg)](LICENSE)
+
+File sizes that read exactly the way macOS Finder shows them (`"4.1 MB"`,
+`"226 KB"`), and relative dates in Rails ActionView's wording (`"about 3 hours
+ago"`, `"in 3 minutes"`), for TypeScript and JavaScript. No dependencies.
+
+```ts
+import { humanSize, timeAgo, distanceInTime } from 'humane-ts'
+
+humanSize(225_935) // "226 KB"
+
+const mtime = new Date(Date.now() - 180_000)
+timeAgo(mtime) // "3 minutes ago" -- relative to the real clock
+
+const now = new Date()
+distanceInTime(mtime, now) // "3 minutes ago" -- explicit relativeTo, for tests
+```
+
+## Install
+
+```
+npm install humane-ts
+```
+
+To install the latest `main` instead, straight from GitHub (built on install):
+
+```
+npm install github:woodie/humane-ts
+```
+
+ES module only, with TypeScript types included.
+
+## File sizes
+
+`humanSize` matches Foundation's `ByteCountFormatter` (file style), which is
+what macOS Finder shows, and is checked against real Finder output:
+
+- 1000-based units with capitalized labels: `KB`, `MB`, `GB`, `TB`, and up.
+- A fixed number of decimal places per unit -- none for KB, one for MB, two
+  for GB and above -- with trailing zeros dropped (`"2 MB"`, not `"2.0 MB"`).
+- Rounds half up, and moves up a unit when rounding reaches 1000:
+  999,999 bytes is `"1 MB"`, not `"1000 KB"`.
+- Zero bytes is `"Zero KB"`, and anything under 1000 bytes is spelled out
+  (`"1 byte"`, `"7 bytes"`).
+
+```ts
+humanSize(2_579)         // "3 KB"
+humanSize(4_132_383)     // "4.1 MB"
+humanSize(999_999)       // "1 MB"
+humanSize(5_240_000_000) // "5.24 GB"
+```
+
+Popular alternatives like `pretty-bytes` and `filesize` round differently
+(`"4.13 MB"`, `"2.58 kB"`) and label units in SI style (`kB`, `B`), so their
+output won't match what Finder shows.
+
+## `distanceInTime` and `timeAgo`
+
+Two entry points, same naming split as ActionView's own
+`distance_of_time_in_words`/`time_ago_in_words`:
+
+- **`distanceInTime(at, relativeTo, options?)`** -- the explicit,
+  fully-tested core. Takes both times, plus a possibly-null `at`, so it's
+  what tests should call.
+- **`timeAgo(at, options?)`** -- a one-argument convenience for the common
+  "drop into a view" case. Supplies the current time as `relativeTo`.
+
+The wording follows ActionView's `distance_of_time_in_words`, with one
+difference: direction is picked for you. A past time reads `"3 minutes ago"`
+and a future one `"in 3 minutes"`, where ActionView leaves that to the caller.
+
+Both take the same options, with recommended defaults that already match
+ActionView's own -- pass none at all and you get them for free:
+
+```ts
+distanceInTime(at, relativeTo) // { approximate: true, includeSeconds: false }
+timeAgo(at)                    // same defaults, relativeTo is now
+```
+
+- **`approximate`** (default `true`): prefixes `"about"`/`"in about"` on the
+  hour-scale buckets (1 hour, and 2..24 hours), matching ActionView's
+  `distance_of_time_in_words` wording for those buckets exactly (down to its
+  44:30/89:30 rounding cutoffs), through the "1 day" bucket.
+- **`includeSeconds`** (default `false`): under 30 seconds, collapses to
+  `"less than a minute ago"`/`"in less than a minute"` instead of an exact
+  second count. Matches ActionView's `include_seconds` default.
+- **`whenNil`** (default `""`): if `at` is `null` or `undefined`,
+  `distanceInTime` returns this string without formatting -- for a scan,
+  download, or other record that doesn't have a timestamp yet.
+
+```ts
+distanceInTime(at, relativeTo, { approximate: false }) // "15 hours ago", not "about 15 hours ago"
+distanceInTime(null, new Date(), { whenNil: 'an unknown time' }) // "an unknown time"
+```
+
+`date-fns`'s `formatDistance` uses the same ActionView wording, and is the
+better choice if you already depend on it or need months and years. It has no
+way to drop `"about"`, phrases seconds differently (`"half a minute"`), and
+continues past days into `"about 1 month"` and `"about 2 years"`.
+
+## Scope
+
+Finder's byte-count style, and a numeric (non-calendar-aware) relative time
+style through the "1 day" bucket -- that's the whole surface area today.
+Alternate size units/styles and a named style (`"yesterday"`,
+calendar-boundary-aware) aren't implemented -- contributions welcome.
+
+## Development
+
+Requires Node 22.13 or later for the dev tools; the published library itself
+runs on Node 18 and any modern browser.
+
+```
+npm install
+make test
+make check
+```
+
+`make test` prints the full nested describe/context/it output from Vitest;
+`make check` runs lint, the type check and the tests together, quietly unless
+something fails.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { humanSize } from './size.js';
+export { distanceInTime, timeAgo } from './time.js';
+export type { TimeOptions } from './time.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { humanSize } from './size.js';
+export { distanceInTime, timeAgo } from './time.js';

package/dist/size.d.ts

@@ -0,0 +1 @@
+export declare function humanSize(bytes: number): string;

package/dist/size.js

@@ -0,0 +1,24 @@
+const SIZE_UNITS = ['KB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+// Lines up with SIZE_UNITS: KB 0, MB 1, GB and above 2.
+const DECIMAL_PLACES = [0, 1, 2, 2, 2, 2];
+export function humanSize(bytes) {
+    if (bytes === 0)
+        return 'Zero KB';
+    if (bytes < 1000)
+        return bytes === 1 ? '1 byte' : `${bytes} bytes`;
+    let exp = Math.min(Math.floor(Math.log(bytes) / Math.log(1000)), SIZE_UNITS.length);
+    let value = roundForUnit(bytes, exp);
+    if (value >= 1000 && exp < SIZE_UNITS.length) {
+        exp++;
+        value = roundForUnit(bytes, exp);
+    }
+    return `${trimZeros(value, DECIMAL_PLACES[exp - 1])} ${SIZE_UNITS[exp - 1]}`;
+}
+function roundForUnit(bytes, exp) {
+    const scale = 10 ** DECIMAL_PLACES[exp - 1];
+    return Math.round(bytes / 1000 ** exp * scale) / scale;
+}
+function trimZeros(value, decimals) {
+    const s = value.toFixed(decimals);
+    return s.includes('.') ? s.replace(/0+$/, '').replace(/\.$/, '') : s;
+}

package/dist/time.d.ts

@@ -0,0 +1,7 @@
+export interface TimeOptions {
+    approximate?: boolean;
+    includeSeconds?: boolean;
+    whenNil?: string;
+}
+export declare function distanceInTime(at: Date | null | undefined, relativeTo: Date, options?: TimeOptions): string;
+export declare function timeAgo(at: Date, options?: TimeOptions): string;

package/dist/time.js

@@ -0,0 +1,50 @@
+export function distanceInTime(at, relativeTo, options = {}) {
+    const { approximate = true, includeSeconds = false, whenNil = '' } = options;
+    if (at == null)
+        return whenNil;
+    let seconds = (relativeTo.getTime() - at.getTime()) / 1000;
+    const future = seconds < 0;
+    seconds = Math.abs(seconds);
+    if (!includeSeconds && seconds < 30) {
+        return future ? 'in less than a minute' : 'less than a minute ago';
+    }
+    if (includeSeconds && seconds < 60) {
+        return wrap(pluralize(Math.floor(seconds), 'second'), future);
+    }
+    // Buckets come from distanceInMinutes, not raw seconds re-divided per unit -- see docs/COMMENTS.md.
+    const distanceInMinutes = Math.floor(seconds / 60 + 0.5);
+    let text;
+    let approximable = false;
+    if (distanceInMinutes === 1) {
+        text = '1 minute';
+    }
+    else if (distanceInMinutes <= 44) {
+        text = pluralize(distanceInMinutes, 'minute');
+    }
+    else if (distanceInMinutes <= 89) {
+        text = '1 hour';
+        approximable = true;
+    }
+    else if (distanceInMinutes <= 1439) {
+        text = pluralize(Math.floor(distanceInMinutes / 60 + 0.5), 'hour');
+        approximable = true;
+    }
+    else if (distanceInMinutes <= 2519) {
+        text = '1 day';
+    }
+    else {
+        text = pluralize(Math.floor(distanceInMinutes / 1440 + 0.5), 'day');
+    }
+    if (approximate && approximable)
+        text = `about ${text}`;
+    return wrap(text, future);
+}
+export function timeAgo(at, options = {}) {
+    return distanceInTime(at, new Date(), options);
+}
+function wrap(text, future) {
+    return future ? `in ${text}` : `${text} ago`;
+}
+function pluralize(count, unit) {
+    return count === 1 ? `1 ${unit}` : `${count} ${unit}s`;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "humane-ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "File sizes the way macOS Finder shows them, and relative dates in Rails ActionView's wording",
+  "keywords": [
+    "file size",
+    "bytes",
+    "finder",
+    "relative time",
+    "time ago",
+    "actionview",
+    "distance of time in words"
+  ],
+  "license": "MIT",
+  "author": "John Woodell <woodie@netpress.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woodie/humane-ts.git"
+  },
+  "homepage": "https://github.com/woodie/humane-ts#readme",
+  "bugs": "https://github.com/woodie/humane-ts/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "lint": "eslint . && tsc --noEmit",
+    "test": "vitest run --reporter=tree",
+    "check": "eslint . && tsc --noEmit && vitest run --reporter=dot",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "devDependencies": {
+    "eslint": "^10.12.0",
+    "neostandard": "^0.14.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.4"
+  }
+}