Added utility functions

- parseExact.ts to parse a date string according to an exact format
- addToDate.ts to modify dates
- The build process now updates the readme with bundle sizes automagically

Author: Atulin

CHANGELOG.md

@@ -2,8 +2,17 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+<a name="1.2.0"></a>
+## [1.2.0](https://github.com/atulin/tinytime/compare/v1.1.0...v1.2.0) (2025-05-17)
+
+### Features
+
+* Added exact date parsing with `parseExact` utility
+* Added date manipulation with `addToDate` utility
+* Improved build system with size reporting
+
 <a name="1.1.0"></a>
-## [1.1.0](https://github.com/atulin/tinytime/compare/v1.0.1...v1.1.0) (2017-06-08)
+## [1.1.0](https://github.com/atulin/tinytime/compare/v1.0.1...v1.1.0)
 
 ### Features
 
@@ -13,7 +22,7 @@ All notable changes to this project will be documented in this file. See [standa
 * Parser tokens are now typed and inlined as numbers instead of being strings
 
 <a name="1.0.0"></a>
-## [1.0.0](https://github.com/atulin/tinytime/compare/v0.2.6...v1.0.0) (2017-06-08)
+## [1.0.0](https://github.com/atulin/tinytime/compare/v0.2.6...v1.0.0)
 
 ### Features
 

README.md

@@ -13,10 +13,11 @@
 * Proper type definitions
 * More correct code
 * ESM-only
+* Additional [utilities](#utils)
 
 ## API
 
-tinytime exports a single function that returns a template object. This object has a single method, `render`, which
+Tinytime exports a single function that returns a template object. This object has a single method, `render`, which
 takes a `Date` and returns a string with the rendered data.
 
 ```js
@@ -50,12 +51,66 @@ template.render(new Date());
 > const template = tinytime('{Mo}', { padMonth: true })
 > ```
 
+## Utils
+
+Tinytime now comes with two utility functions exported from `tinytime/utils`
+
+### Date parsing
+
+The `parseExact(string, string)` function can be used to easily parse a date string according to a specified format.
+
+```ts
+import { parseExact } from "tinytime/parseExact";
+
+const date = parseExact("05 21 1997 (at 06:37:00 PM)", "MM dd yyyy (at hh:mm:ss aa)");
+
+console.assert(date === new Date("1997-05-21T18:37:00Z")); // assertion passes
+```
+
+The format tokens are as follows:
+
+* `y` - year
+* `M` - month
+* `d` - date
+* `h` - hours
+* `m` - minutes
+* `s` - seconds
+* `i` - milliseconds
+* `a` - AM/PM
+
+### Date manipulation
+
+The `addToDate(Date, DateDelta)` function can be used to add a desired delta to a given date.
+
+```ts
+import { addToDate } from "tinytime/addToDate"
+
+const now = Date.now(); // 2025-05-17T15:08:00.000Z
+
+const future = addToDate(now, { days: 3, years: 100, hours: 761 });
+
+future.toISOString(); // 2125-06-21T08:08:00.000Z
+```
+
+The `DateDelta` is defined as follows:
+
+```ts
+interface DateDelta {
+    years?: number;
+    months?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+```
 
 ## Efficiency
 
-tinytime takes an approach similar to a compiler and generates an AST representing your template. This AST is generated when
-you call the main `tinytime` function. This lets you efficiently re-render your template without tinytime having to parse the
-template string again. That means its important that you aren't recreating the template object frequently.
+Tinytime takes an approach similar to a compiler and generates an AST representing your template. This AST is generated when
+you call the main `tinytime` function. This lets you efficiently re-render your template without Tinytime having to parse the
+template string again. That means it's important that you aren't recreating the template object frequently.
 
 Here's an example showing the right and wrong way to use tinytime with React.
 
@@ -71,7 +126,7 @@ function Time({ date }) {
 }
 ```
 
-Instead, only create the template object once, and just re-render it.
+Instead, only create the template object once and re-render it.
 
 ```jsx
 const template = tinytime('{h}:{mm}:{ss}{a}');
@@ -84,6 +139,29 @@ function Time({ date }) {
 }
 ```
 
+## Current bundle size
+
+```x-sizes
+dist\addToDate.js      402  bytes
+dist\addToDate.js      246  bytes (GZIP)
+dist\addToDate.js      228  bytes (DEFLATE)
+dist\addToDate.min.js  270  bytes
+dist\addToDate.min.js  195  bytes (GZIP)
+dist\addToDate.min.js  177  bytes (DEFLATE)
+dist\parseExact.js     1083 bytes
+dist\parseExact.js     563  bytes (GZIP)
+dist\parseExact.js     545  bytes (DEFLATE)
+dist\parseExact.min.js 636  bytes
+dist\parseExact.min.js 450  bytes (GZIP)
+dist\parseExact.min.js 432  bytes (DEFLATE)
+dist\tinytime.js       3674 bytes
+dist\tinytime.js       1252 bytes (GZIP)
+dist\tinytime.js       1234 bytes (DEFLATE)
+dist\tinytime.min.js   1278 bytes
+dist\tinytime.min.js   771  bytes (GZIP)
+dist\tinytime.min.js   753  bytes (DEFLATE)
+```
+
 ### Babel Plugins
 
 Using one of the plugins below, you can resolve this efficiency concern at compile time.

build.ts

@@ -2,11 +2,15 @@
 import isolatedDecl from "bun-plugin-isolated-decl";
 
 const config = (min: boolean): BuildConfig => ({
-	entrypoints: ["./src/tinytime.ts"],
+	entrypoints: [
+		"./src/tinytime.ts",
+		"./src/utils/addToDate.ts",
+		"./src/utils/parseExact.ts",
+	],
 	outdir: "./dist",
 	format: "esm",
-	naming: min ? "[dir]/[name].min.[ext]" : "[dir]/[name].[ext]",
-	plugins: [isolatedDecl({})],
+	naming: min ? "[name].min.[ext]" : "[name].[ext]",
+	plugins: min ? [] : [isolatedDecl()],
 });
 
 for (const m of [true, false]) {
@@ -16,13 +20,36 @@ for (const m of [true, false]) {
 	});
 }
 
+const sizes: { file: string; size: number; suffix: string }[] = [];
 for await (const file of new Glob("dist/*.js").scan()) {
 	const content = await Bun.file(file).arrayBuffer();
-	console.log(`${file} ${content.byteLength} bytes`);
+	sizes.push({ file, size: content.byteLength, suffix: "bytes" });
 
 	const gzipped = Bun.gzipSync(content);
-	console.log(`${file} ${gzipped.byteLength} bytes (GZIP)`);
+	sizes.push({ file, size: gzipped.byteLength, suffix: "bytes (GZIP)" });
 
 	const deflated = Bun.deflateSync(content);
-	console.log(`${file} ${deflated.byteLength} bytes (DEFLATE)`);
+	sizes.push({ file, size: deflated.byteLength, suffix: "bytes (DEFLATE)" });
 }
+
+const max = sizes.reduce(
+	(acc, curr) => {
+		acc.file = Math.max(acc.file, curr.file.length);
+		acc.size = Math.max(acc.size, curr.size.toString().length);
+		return acc;
+	},
+	{ file: 0, size: 0 },
+);
+
+const line = ({ file, size, suffix }: (typeof sizes)[number]) =>
+	`${file.padEnd(max.file)} ${size.toString().padEnd(max.size)} ${suffix}`;
+const table = sizes.map(line).join("\n");
+
+console.log(table);
+
+const readme = await Bun.file("./README.md").text();
+const newReadme = readme.replace(
+	/(```x-sizes)[\s\S]*(```)/m,
+	`$1\n${table}\n$2`,
+);
+await Bun.write("./README.md", newReadme);

bun.lock

@@ -1,7 +1,11 @@
 {
 	"$schema": "https://jsr.io/schema/config-file.v1.json",
 	"name": "@angius/tinytime",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"license": "MIT",
-	"exports": "./src/tinytime.ts"
+	"exports": {
+		".": "./src/tinytime.ts",
+		"./addToDate": "./src/utils/addToDate.ts",
+		"./parseExact": "./src/utils/parseExact.ts"
+	}
 }

jsr.json

@@ -1,14 +1,33 @@
 {
 	"name": "@angius/tinytime",
-	"version": "1.1.0",
-	"exports": ["./dist/tinytime.js", "./dist/tinytime.min.js"],
+	"version": "1.2.0",
+	"exports": {
+		".": {
+			"types": "./dist/tinytime.d.ts",
+			"import": "./dist/tinytime.js",
+			"require": "./dist/tinytime.js"
+		},
+		"./addtoDate": {
+			"types": "./dist/addToDate.d.ts",
+			"import": "./dist/addToDate.js",
+			"require": "./dist/addToDate.js"
+		},
+		"./parseExact": {
+			"types": "./dist/parseExact.d.ts",
+			"import": "./dist/parseExact.js",
+			"require": "./dist/parseExact.js"
+		}
+	},
+	"files": ["dist"],
+	"main": "./dist/tinytime.js",
+	"module": "./dist/tinytime.js",
 	"types": "./dist/tinytime.d.ts",
 	"license": "MIT",
 	"keywords": ["date", "time", "formatter"],
 	"type": "module",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/Atulin/tinytime"
+		"url": "git+https://github.com/Atulin/tinytime.git"
 	},
 	"scripts": {
 		"build": "bun ./build.ts",

package.json

@@ -1,5 +1,5 @@
 /**
- * We want to represent each subs. type as minimally as possible,
+ * We want to represent each sub. type as minimally as possible,
  * so instead of using strings we just use numbers, which lets us
  * represent 27 individual subs. using a single number each.
  */

src/subs.ts

@@ -0,0 +1,27 @@
+export type DateTimeMethods = {
+	[K in keyof Date]: Date[K] extends (...args: unknown[]) => number
+		? K
+		: never;
+}[keyof Date];
+
+export type DateParams = [
+	year: number,
+	monthIndex: number,
+	date?: number,
+	hours?: number,
+	minutes?: number,
+	seconds?: number,
+	ms?: number,
+];
+
+export const dateParamsNames = [
+	"year",
+	"monthIndex",
+	"date",
+	"hours",
+	"minutes",
+	"seconds",
+	"ms",
+] as const;
+
+export type DateParamsNames = (typeof dateParamsNames)[number];

src/types.d.ts

@@ -0,0 +1,30 @@
+import type { DateParams, DateTimeMethods } from "../types";
+
+export interface DateDelta {
+	years?: number;
+	months?: number;
+	days?: number;
+	hours?: number;
+	minutes?: number;
+	seconds?: number;
+	milliseconds?: number;
+}
+
+const methods: [DateTimeMethods, keyof DateDelta][] = [
+	["getFullYear", "years"],
+	["getMonth", "months"],
+	["getDate", "days"],
+	["getHours", "hours"],
+	["getMinutes", "minutes"],
+	["getSeconds", "seconds"],
+	["getMilliseconds", "milliseconds"],
+] as const;
+
+export const addToDate = (date: Date, delta: DateDelta = {}): Date => {
+	return new Date(
+		...(methods.map(
+			([getter, prop]) =>
+				(date[getter] as () => number)() + (delta[prop] ?? 0),
+		) as DateParams),
+	);
+};