feat(tid): use high-precision system time in Node.js

.changeset/beige-pens-like.md

···
+---
+'@atcute/tid': minor
+---
+
+use high-precision system time in Node.js

.gitignore

···
 .DS_Store
 
 .pkgsize
-.research
+.research

packages/misc/time-ms/.gitignore

···
+build/
+prebuilds/

packages/misc/time-ms/CHANGELOG.md

···
+# @atcute/time-ms
+
+## 1.0.0
+
+### minor changes
+
+- initial release

packages/misc/time-ms/README.md

···
+# @atcute/time-ms
+
+high precision system time
+
+```sh
+npm install @atcute/time-ms
+```
+
+## usage
+
+```ts
+import { now } from '@atcute/time-ms';
+
+const timestamp = now();
+//    ^ 1766739339478426
+// returns microseconds since unix epoch
+```

packages/misc/time-ms/binding.gyp

···
+{
+	"targets": [
+		{
+			"target_name": "time_ms",
+			"sources": ["src/time_ms.c"],
+			"cflags": ["-Wall", "-Wextra", "-O3"],
+			"xcode_settings": {
+				"OTHER_CFLAGS": ["-Wall", "-Wextra", "-O3"]
+			},
+			"msvs_settings": {
+				"VCCLCompilerTool": {
+					"Optimization": 2,
+					"WarnAsError": "false"
+				}
+			}
+		}
+	]
+}

packages/misc/time-ms/lib/index.node.ts

···
+import { join } from 'node:path';
+
+type TimeBinding = {
+	now: () => number;
+};
+
+let binding: TimeBinding | null = null;
+
+try {
+	// node-gyp-build handles platform/arch detection, libc variants, etc.
+	binding = require('node-gyp-build')(join(import.meta.dirname, '..')) as TimeBinding;
+} catch {
+	binding = null;
+}
+
+/**
+ * whether the native module is available for the current runtime.
+ */
+export const hasNative = binding !== null;
+
+/**
+ * returns the current time in microseconds since unix epoch.
+ * @returns timestamp in microseconds
+ */
+export const now = (): number => {
+	if (binding === null) {
+		return Date.now() * 1_000;
+	}
+
+	return binding.now();
+};

packages/misc/time-ms/lib/index.ts

···
+/**
+ * whether the native module is available for the current runtime.
+ */
+export const hasNative = false;
+
+/**
+ * returns the current time in microseconds since unix epoch.
+ * @returns timestamp in microseconds
+ */
+export const now = (): number => {
+	return Date.now() * 1_000;
+};

packages/misc/time-ms/package.json

···
+{
+	"type": "module",
+	"name": "@atcute/time-ms",
+	"version": "1.0.0",
+	"description": "high precision system time helper",
+	"license": "0BSD",
+	"repository": {
+		"url": "https://github.com/mary-ext/atcute",
+		"directory": "packages/utilities/time-ms"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist/",
+		"lib/",
+		"prebuilds/",
+		"src/",
+		"binding.gyp",
+		"!lib/**/*.bench.ts",
+		"!lib/**/*.test.ts"
+	],
+	"exports": {
+		".": {
+			"node": "./dist/index.node.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"sideEffects": false,
+	"scripts": {
+		"install": "node-gyp-build",
+		"build:native": "prebuildify --napi --strip",
+		"build": "tsgo --project tsconfig.build.json",
+		"test": "vitest",
+		"prepublish": "rm -rf dist; pnpm run build:native; pnpm run build"
+	},
+	"devDependencies": {
+		"prebuildify": "^6.0.1",
+		"vitest": "^4.0.16"
+	},
+	"dependencies": {
+		"@types/node": "^22.19.3",
+		"node-gyp-build": "^4.8.4"
+	}
+}

packages/misc/time-ms/src/time_ms.c

···
+#include <node_api.h>
+#include <stdint.h>
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <time.h>
+#endif
+
+static napi_value now(napi_env env, napi_callback_info info) {
+	int64_t microseconds;
+
+#ifdef _WIN32
+	FILETIME ft;
+	ULARGE_INTEGER ul;
+	GetSystemTimePreciseAsFileTime(&ft);
+	ul.LowPart = ft.dwLowDateTime;
+	ul.HighPart = ft.dwHighDateTime;
+	// convert from 100-nanosecond intervals since 1601 to microseconds since 1970
+	microseconds = (int64_t)((ul.QuadPart - 116444736000000000ULL) / 10);
+#else
+	struct timespec ts;
+	clock_gettime(CLOCK_REALTIME, &ts);
+	microseconds = (int64_t)ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
+#endif
+
+	napi_value result;
+	napi_create_int64(env, microseconds, &result);
+	return result;
+}
+
+static napi_value init(napi_env env, napi_value exports) {
+	napi_property_descriptor desc = { "now", NULL, now, NULL, NULL, NULL, napi_default, NULL };
+	napi_define_properties(env, exports, 1, &desc);
+	return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, init)

packages/misc/time-ms/tsconfig.build.json

···
+{
+	"extends": "./tsconfig.json",
+	"exclude": ["**/*.test.ts"]
+}

packages/misc/time-ms/tsconfig.json

···
+{
+	"compilerOptions": {
+		"types": ["node"],
+		"outDir": "dist/",
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"target": "ESNext",
+		"allowJs": true,
+		"resolveJsonModule": true,
+		"moduleDetection": "force",
+		"isolatedModules": true,
+		"verbatimModuleSyntax": true,
+		"strict": true,
+		"noImplicitOverride": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true,
+		"module": "NodeNext",
+		"sourceMap": true,
+		"declaration": true,
+		"declarationMap": true,
+	},
+	"include": ["lib"],
+}

packages/utilities/tid/lib/index.ts

···
+import { now as getNow } from '@atcute/time-ms';
 import { s32decode, s32encode } from './s32.js';
 
-let lastTimestamp: number = 0;
+let lastTimestamp = 0;
+let lastCurrentTime = 0;
 
 const TID_RE = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/;
 
···
  * Return a TID based on current time
  */
 export const now = (): string => {
-	// we need these two aspects, which Date.now() doesn't provide:
-	// - monotonically increasing time
-	// - microsecond precision
+	const currentTime = getNow();
+	let timestamp: number;
 
-	// while `performance.timeOrigin + performance.now()` could be used here, they
-	// seem to have cross-browser differences, not sure on that yet.
+	if (currentTime === lastCurrentTime) {
+		// same time; increment to avoid collision
+		timestamp = lastTimestamp + 1;
+	} else {
+		// time changed
+		timestamp = currentTime;
+		lastCurrentTime = currentTime;
+	}
 
-	let timestamp = Math.max(Date.now() * 1_000, lastTimestamp);
-	lastTimestamp = timestamp + 1;
-
+	lastTimestamp = timestamp;
 	return createRaw(timestamp, Math.floor(Math.random() * 1023));
 };
 

packages/utilities/tid/package.json

···
 		"test": "vitest",
 		"prepublish": "rm -rf dist; pnpm run build"
 	},
+	"dependencies": {
+		"@atcute/time-ms": "workspace:^"
+	},
 	"devDependencies": {
 		"vitest": "^4.0.16"
 	}

pnpm-lock.yaml

···
       '@atcute/uint8array':
         specifier: workspace:^
         version: link:../../misc/uint8array
+      '@atcute/util-fetch':
+        specifier: workspace:^
+        version: link:../../misc/util-fetch
       '@badrap/valita':
         specifier: ^0.4.6
         version: 0.4.6
···
       vitest:
         specifier: ^4.0.16
         version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(tsx@4.20.6)(yaml@2.8.0)
+
+  packages/misc/time-ms:
+    dependencies:
+      '@types/node':
+        specifier: ^22.19.3
+        version: 22.19.3
+      node-gyp-build:
+        specifier: ^4.8.4
+        version: 4.8.4
+    devDependencies:
+      prebuildify:
+        specifier: ^6.0.1
+        version: 6.0.1
+      vitest:
+        specifier: ^4.0.16
+        version: 4.0.16(@types/node@22.19.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(tsx@4.20.6)(yaml@2.8.0)
 
   packages/misc/uint8array:
     devDependencies:
···
         version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(tsx@4.20.6)(yaml@2.8.0)
 
   packages/utilities/tid:
+    dependencies:
+      '@atcute/time-ms':
+        specifier: workspace:^
+        version: link:../../misc/time-ms
     devDependencies:
       vitest:
         specifier: ^4.0.16
···
     resolution: {integrity: sha512-+P72GAjVAbTxjjwUmwjVrqrdZROD4nf8KgpBoDxqXXTiYZZt/ud60dE5yvCSr9lRO8e8yv6kgJIC0K0PfZFVQw==}
     hasBin: true
 
+  node-gyp-build@4.8.4:
+    resolution: {integrity: sha512-LA4ZjwlnUblHVgq0oBF3Jl/6h/Nvs5fzBLwdEF4nuxnFdsfajde4WfxtJr3CaiH+F6ewcIB/q4jQ4UzPyid+CQ==}
+    hasBin: true
+
   nodemailer-html-to-text@3.2.0:
     resolution: {integrity: sha512-RJUC6640QV1PzTHHapOrc6IzrAJUZtk2BdVdINZ9VTLm+mcQNyBO9LYyhrnufkzqiD9l8hPLJ97rSyK4WanPNg==}
     engines: {node: '>= 10.23.0'}
···
     resolution: {integrity: sha512-Z+iLaBGVaSjbIzQ4pX6XV41HrooLsQ10ZWPUehGmuantvzWoDVBnmsdUcOIDM1t+yPor5pDhVlDESgOMEGxhHA==}
     engines: {node: '>=6.0.0'}
 
+  npm-run-path@3.1.0:
+    resolution: {integrity: sha512-Dbl4A/VfiVGLgQv29URL9xshU8XDY1GeLy+fsaZ1AA8JDSfjvr5P5+pzRbWqRSBxk6/DW7MIh8lTM/PaGnP2kg==}
+    engines: {node: '>=8'}
+
   object-assign@4.1.1:
     resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
     engines: {node: '>=0.10.0'}
···
   prebuild-install@7.1.3:
     resolution: {integrity: sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==}
     engines: {node: '>=10'}
+    hasBin: true
+
+  prebuildify@6.0.1:
+    resolution: {integrity: sha512-8Y2oOOateom/s8dNBsGIcnm6AxPmLH4/nanQzL5lQMU+sC0CMhzARZHizwr36pUPLdvBnOkCNQzxg4djuFSgIw==}
     hasBin: true
 
   prettier@2.8.8:
···
 
   '@types/bn.js@5.2.0':
     dependencies:
-      '@types/node': 25.0.3
+      '@types/node': 22.19.3
 
   '@types/bun@1.3.5':
     dependencies:
···
   '@types/node@25.0.3':
     dependencies:
       undici-types: 7.16.0
+    optional: true
 
   '@types/ws@8.18.1':
     dependencies:
-      '@types/node': 25.0.3
+      '@types/node': 22.19.3
 
   '@typescript/native-preview-darwin-arm64@7.0.0-dev.20251221.1':
     optional: true
···
 
   bun-types@1.3.5:
     dependencies:
-      '@types/node': 25.0.3
+      '@types/node': 22.19.3
 
   bytes@3.1.2: {}
 
···
       detect-libc: 2.1.2
     optional: true
 
+  node-gyp-build@4.8.4: {}
+
   nodemailer-html-to-text@3.2.0:
     dependencies:
       html-to-text: 7.1.1
 
   nodemailer@6.10.1: {}
+
+  npm-run-path@3.1.0:
+    dependencies:
+      path-key: 3.1.1
 
   object-assign@4.1.1: {}
 
···
       tar-fs: 2.1.4
       tunnel-agent: 0.6.0
 
+  prebuildify@6.0.1:
+    dependencies:
+      minimist: 1.2.8
+      mkdirp-classic: 0.5.3
+      node-abi: 3.85.0
+      npm-run-path: 3.1.0
+      pump: 3.0.3
+      tar-fs: 2.1.4
+
   prettier@2.8.8: {}
 
   prettier@3.7.4: {}
···
 
   undici-types@6.21.0: {}
 
-  undici-types@7.16.0: {}
+  undici-types@7.16.0:
+    optional: true
 
   undici@6.22.0: {}