@lp-labs/timecode-toolkit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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,72 @@
-# Temporary Holding Version
+# @lp-labs/timecode-toolkit
 
-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.
+Rational frame-rate timecode conversion. Exact integer-frame conversion for rational frame rates, including validated SMPTE 29.97/59.94 drop-frame.
+
+## Install
+
+```sh
+npm install @lp-labs/timecode-toolkit
+```
+
+## Quick start
+
+```js
+import { framesToTimecode } from '@lp-labs/timecode-toolkit';
+console.log(framesToTimecode(17982, { numerator: 30000, denominator: 1001 }, { dropFrame: true })); // 00:10:00;00
+```
+
+## Runtime exports
+
+- `framesToTimecode`
+- `timecodeToFrames`
+
+The package supplies independent ESM and CommonJS builds, bundled declarations, and no runtime or peer dependencies.
+
+## Complete public TypeScript declarations
+
+```ts
+export interface FrameRate {
+  numerator: number;
+  denominator: number;
+}
+export interface TimecodeOptions {
+  dropFrame?: boolean;
+  rollover24Hours?: boolean;
+}
+export interface Timecode {
+  hours: number;
+  minutes: number;
+  seconds: number;
+  frames: number;
+}
+export declare function framesToTimecode(
+  frameNumber: number,
+  rate: FrameRate,
+  options?: TimecodeOptions,
+): string;
+export declare function timecodeToFrames(
+  value: string,
+  rate: FrameRate,
+  options?: TimecodeOptions,
+): number;
+```
+
+## Scope and limits
+
+Converts safe non-negative integer frame indices to/from HH:MM:SS:FF labels. Non-drop mode supports integer frame rates from 1 through 120 and standard 24000/1001, 30000/1001, and 60000/1001 rates. Drop-frame mode is true label skipping for 30000/1001 (2 labels/minute) and 60000/1001 (4 labels/minute), except each tenth minute; skipped labels are rejected.
+
+## Errors and bounds
+
+Malformed labels/rates raise TypeError; out-of-range fields, dropped labels, mismatched separator/mode, unsupported rates, and unsafe indices raise RangeError.
+
+## Customization
+
+Use { numerator, denominator } for an exact rational rate. Set { dropFrame: true } only for the two listed drop-frame rates. Set rollover24Hours explicitly if timecode must wrap daily.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,16 @@
+export interface FrameRate {
+    numerator: number;
+    denominator: number;
+}
+export interface TimecodeOptions {
+    dropFrame?: boolean;
+    rollover24Hours?: boolean;
+}
+export interface Timecode {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    frames: number;
+}
+export declare function framesToTimecode(frameNumber: number, rate: FrameRate, options?: TimecodeOptions): string;
+export declare function timecodeToFrames(value: string, rate: FrameRate, options?: TimecodeOptions): number;

package/dist/cjs/index.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.framesToTimecode = framesToTimecode;
+exports.timecodeToFrames = timecodeToFrames;
+const MAX_HOURS = 99_999;
+function rateInfo(rate, dropFrame) {
+    if (!rate ||
+        !Number.isSafeInteger(rate.numerator) ||
+        !Number.isSafeInteger(rate.denominator) ||
+        rate.numerator <= 0 ||
+        rate.denominator <= 0) {
+        throw new TypeError('Frame rate must use positive integer numerator and denominator.');
+    }
+    const nominal = Math.round(rate.numerator / rate.denominator);
+    const exactRate = rate.numerator / rate.denominator;
+    const standardFractionalRate = rate.denominator === 1_001 &&
+        (rate.numerator === 24_000 || rate.numerator === 30_000 || rate.numerator === 60_000);
+    if (nominal < 1 ||
+        nominal > 120 ||
+        (!standardFractionalRate && Math.abs(exactRate - nominal) > 0.01))
+        throw new RangeError('Unsupported frame rate.');
+    let drop = 0;
+    if (dropFrame) {
+        if (rate.numerator === 30_000 && rate.denominator === 1_001)
+            drop = 2;
+        else if (rate.numerator === 60_000 && rate.denominator === 1_001)
+            drop = 4;
+        else
+            throw new RangeError('Drop-frame supports only 30000/1001 or 60000/1001.');
+    }
+    return { nominal, drop };
+}
+function framesToTimecode(frameNumber, rate, options = {}) {
+    if (!Number.isSafeInteger(frameNumber) || frameNumber < 0)
+        throw new RangeError('Frame number must be a non-negative safe integer.');
+    if (options.dropFrame !== undefined && typeof options.dropFrame !== 'boolean')
+        throw new TypeError('dropFrame must be boolean.');
+    if (options.rollover24Hours !== undefined && typeof options.rollover24Hours !== 'boolean')
+        throw new TypeError('rollover24Hours must be boolean.');
+    const { nominal, drop } = rateInfo(rate, options.dropFrame ?? false);
+    if (options.rollover24Hours) {
+        const dayFrames = nominal * 86_400 - drop * (1_440 - 144);
+        frameNumber %= dayFrames;
+    }
+    let labelFrame = frameNumber;
+    if (drop > 0) {
+        const blockSize = nominal * 600 - drop * 9;
+        const blocks = Math.floor(frameNumber / blockSize);
+        let remainder = frameNumber % blockSize;
+        labelFrame = blocks * nominal * 600;
+        const fullMinute = nominal * 60;
+        if (remainder >= fullMinute) {
+            remainder -= fullMinute;
+            labelFrame += fullMinute;
+            for (let minute = 1; minute < 10; minute += 1) {
+                labelFrame += drop;
+                const minuteFrames = fullMinute - drop;
+                if (remainder < minuteFrames) {
+                    labelFrame += remainder;
+                    remainder = 0;
+                    break;
+                }
+                remainder -= minuteFrames;
+                labelFrame += minuteFrames;
+            }
+            if (remainder > 0)
+                labelFrame += remainder;
+        }
+        else
+            labelFrame += remainder;
+    }
+    const hours = Math.floor(labelFrame / (nominal * 3600));
+    if (hours > MAX_HOURS)
+        throw new RangeError('Timecode exceeds supported hours.');
+    const minutes = Math.floor(labelFrame / (nominal * 60)) % 60;
+    const seconds = Math.floor(labelFrame / nominal) % 60;
+    const frames = labelFrame % nominal;
+    return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}${drop ? ';' : ':'}${String(frames).padStart(2, '0')}`;
+}
+function timecodeToFrames(value, rate, options = {}) {
+    const { nominal, drop } = rateInfo(rate, options.dropFrame ?? false);
+    if (typeof value !== 'string' || value.length > 32)
+        throw new TypeError('Timecode must be a string up to 32 characters.');
+    if (options.dropFrame !== undefined && typeof options.dropFrame !== 'boolean')
+        throw new TypeError('dropFrame must be boolean.');
+    if (options.rollover24Hours !== undefined && typeof options.rollover24Hours !== 'boolean')
+        throw new TypeError('rollover24Hours must be boolean.');
+    const match = /^(\d{2,5}):([0-5]\d):([0-5]\d)([:;])(\d{2})(?![\s\S])/.exec(value);
+    if (!match)
+        throw new TypeError('Expected HH:MM:SS:FF or drop-frame HH:MM:SS;FF.');
+    const [, hourText, minuteText, secondText, separator, frameText] = match;
+    const hours = Number(hourText);
+    const minutes = Number(minuteText);
+    const seconds = Number(secondText);
+    const frames = Number(frameText);
+    if (hours > MAX_HOURS || frames >= nominal)
+        throw new RangeError('Timecode field is out of range.');
+    if (options.rollover24Hours && hours >= 24)
+        throw new RangeError('Rollover timecode labels must be within one 24-hour day.');
+    if (drop > 0 !== (separator === ';'))
+        throw new RangeError('Timecode separator does not match drop-frame mode.');
+    if (drop > 0 && seconds === 0 && minutes % 10 !== 0 && frames < drop)
+        throw new RangeError('Timecode names a dropped frame label.');
+    const totalMinutes = hours * 60 + minutes;
+    let result = (hours * 3600 + minutes * 60 + seconds) * nominal + frames;
+    if (drop > 0)
+        result -= drop * (totalMinutes - Math.floor(totalMinutes / 10));
+    if (!Number.isSafeInteger(result))
+        throw new RangeError('Frame number exceeds safe integer range.');
+    return result;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,16 @@
+export interface FrameRate {
+    numerator: number;
+    denominator: number;
+}
+export interface TimecodeOptions {
+    dropFrame?: boolean;
+    rollover24Hours?: boolean;
+}
+export interface Timecode {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    frames: number;
+}
+export declare function framesToTimecode(frameNumber: number, rate: FrameRate, options?: TimecodeOptions): string;
+export declare function timecodeToFrames(value: string, rate: FrameRate, options?: TimecodeOptions): number;

package/dist/esm/index.js

@@ -0,0 +1,107 @@
+const MAX_HOURS = 99_999;
+function rateInfo(rate, dropFrame) {
+    if (!rate ||
+        !Number.isSafeInteger(rate.numerator) ||
+        !Number.isSafeInteger(rate.denominator) ||
+        rate.numerator <= 0 ||
+        rate.denominator <= 0) {
+        throw new TypeError('Frame rate must use positive integer numerator and denominator.');
+    }
+    const nominal = Math.round(rate.numerator / rate.denominator);
+    const exactRate = rate.numerator / rate.denominator;
+    const standardFractionalRate = rate.denominator === 1_001 &&
+        (rate.numerator === 24_000 || rate.numerator === 30_000 || rate.numerator === 60_000);
+    if (nominal < 1 ||
+        nominal > 120 ||
+        (!standardFractionalRate && Math.abs(exactRate - nominal) > 0.01))
+        throw new RangeError('Unsupported frame rate.');
+    let drop = 0;
+    if (dropFrame) {
+        if (rate.numerator === 30_000 && rate.denominator === 1_001)
+            drop = 2;
+        else if (rate.numerator === 60_000 && rate.denominator === 1_001)
+            drop = 4;
+        else
+            throw new RangeError('Drop-frame supports only 30000/1001 or 60000/1001.');
+    }
+    return { nominal, drop };
+}
+export function framesToTimecode(frameNumber, rate, options = {}) {
+    if (!Number.isSafeInteger(frameNumber) || frameNumber < 0)
+        throw new RangeError('Frame number must be a non-negative safe integer.');
+    if (options.dropFrame !== undefined && typeof options.dropFrame !== 'boolean')
+        throw new TypeError('dropFrame must be boolean.');
+    if (options.rollover24Hours !== undefined && typeof options.rollover24Hours !== 'boolean')
+        throw new TypeError('rollover24Hours must be boolean.');
+    const { nominal, drop } = rateInfo(rate, options.dropFrame ?? false);
+    if (options.rollover24Hours) {
+        const dayFrames = nominal * 86_400 - drop * (1_440 - 144);
+        frameNumber %= dayFrames;
+    }
+    let labelFrame = frameNumber;
+    if (drop > 0) {
+        const blockSize = nominal * 600 - drop * 9;
+        const blocks = Math.floor(frameNumber / blockSize);
+        let remainder = frameNumber % blockSize;
+        labelFrame = blocks * nominal * 600;
+        const fullMinute = nominal * 60;
+        if (remainder >= fullMinute) {
+            remainder -= fullMinute;
+            labelFrame += fullMinute;
+            for (let minute = 1; minute < 10; minute += 1) {
+                labelFrame += drop;
+                const minuteFrames = fullMinute - drop;
+                if (remainder < minuteFrames) {
+                    labelFrame += remainder;
+                    remainder = 0;
+                    break;
+                }
+                remainder -= minuteFrames;
+                labelFrame += minuteFrames;
+            }
+            if (remainder > 0)
+                labelFrame += remainder;
+        }
+        else
+            labelFrame += remainder;
+    }
+    const hours = Math.floor(labelFrame / (nominal * 3600));
+    if (hours > MAX_HOURS)
+        throw new RangeError('Timecode exceeds supported hours.');
+    const minutes = Math.floor(labelFrame / (nominal * 60)) % 60;
+    const seconds = Math.floor(labelFrame / nominal) % 60;
+    const frames = labelFrame % nominal;
+    return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}${drop ? ';' : ':'}${String(frames).padStart(2, '0')}`;
+}
+export function timecodeToFrames(value, rate, options = {}) {
+    const { nominal, drop } = rateInfo(rate, options.dropFrame ?? false);
+    if (typeof value !== 'string' || value.length > 32)
+        throw new TypeError('Timecode must be a string up to 32 characters.');
+    if (options.dropFrame !== undefined && typeof options.dropFrame !== 'boolean')
+        throw new TypeError('dropFrame must be boolean.');
+    if (options.rollover24Hours !== undefined && typeof options.rollover24Hours !== 'boolean')
+        throw new TypeError('rollover24Hours must be boolean.');
+    const match = /^(\d{2,5}):([0-5]\d):([0-5]\d)([:;])(\d{2})(?![\s\S])/.exec(value);
+    if (!match)
+        throw new TypeError('Expected HH:MM:SS:FF or drop-frame HH:MM:SS;FF.');
+    const [, hourText, minuteText, secondText, separator, frameText] = match;
+    const hours = Number(hourText);
+    const minutes = Number(minuteText);
+    const seconds = Number(secondText);
+    const frames = Number(frameText);
+    if (hours > MAX_HOURS || frames >= nominal)
+        throw new RangeError('Timecode field is out of range.');
+    if (options.rollover24Hours && hours >= 24)
+        throw new RangeError('Rollover timecode labels must be within one 24-hour day.');
+    if (drop > 0 !== (separator === ';'))
+        throw new RangeError('Timecode separator does not match drop-frame mode.');
+    if (drop > 0 && seconds === 0 && minutes % 10 !== 0 && frames < drop)
+        throw new RangeError('Timecode names a dropped frame label.');
+    const totalMinutes = hours * 60 + minutes;
+    let result = (hours * 3600 + minutes * 60 + seconds) * nominal + frames;
+    if (drop > 0)
+        result -= drop * (totalMinutes - Math.floor(totalMinutes / 10));
+    if (!Number.isSafeInteger(result))
+        throw new RangeError('Frame number exceeds safe integer range.');
+    return result;
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@lp-labs/timecode-toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Exact integer-frame conversion for rational frame rates, including validated SMPTE 29.97/59.94 drop-frame.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  },
+  "dependencies": {},
+  "peerDependencies": {}
+}