@chronicle.app/etl-sqlite 0.3.0 → 0.4.0

package/README.md

@@ -32,6 +32,8 @@ The connection is read-only: missing databases are not created, and journal mode
 
 Apple epoch helpers retain the existing API: iOS inputs/outputs use nanoseconds since 2001, Safari inputs/outputs use seconds since 2001. `iosToUnixTimestamp` returns Unix milliseconds; other Unix arguments/results use seconds.
 
+Chrome epoch helpers cover Chromium's microseconds since 1601. `chromeToUnixMsSql(column)` returns a SQL expression in Unix milliseconds, since current Chrome times are too large to read as numbers. `unixMsToChromeTimestamp(ms)` converts a bound back, as a `timeRangeConditions` `convert`.
+
 Node SQLite returns large INTEGER values only when `statement.setReadBigInts(true)` is enabled. Use that for source nanosecond timestamps and convert deliberately at the application boundary.
 
 ## Porting from better-sqlite3

package/dist/SqliteExtractor.js

@@ -1,6 +1,6 @@
 import { DatabaseSync } from 'node:sqlite';
 import { z } from 'zod';
-import { Extractor } from '@chronicle.app/etl';
+import { Extractor, assertReadable } from '@chronicle.app/etl';
 /** Read an existing source database without changing its journal mode. */
 export class SqliteExtractor extends Extractor {
     static delivery = 'local';
@@ -21,6 +21,9 @@ export class SqliteExtractor extends Extractor {
      * as a copy of a locked database, after closing and clearing `this.db`.
      */
     openDatabase(path) {
+        // SQLite says only "unable to open database file"; say whether the file
+        // is missing or macOS privacy controls refused it.
+        assertReadable(path, 'database');
         return new DatabaseSync(path, { readOnly: true });
     }
     async teardown() {

package/dist/chromeEpoch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Chrome epoch timestamp utilities.
+ *
+ * Chromium stores times (History `visits.visit_time`, `urls.last_visit_time`)
+ * as microseconds since January 1, 1601 00:00:00 UTC, the Windows FILETIME
+ * epoch. Unix timestamps count from January 1, 1970 00:00:00 UTC. The
+ * difference is 11,644,473,600 seconds.
+ *
+ * Current Chrome times exceed Number.MAX_SAFE_INTEGER, so `node:sqlite` throws
+ * ERR_OUT_OF_RANGE when reading them as numbers. Convert in SQL with
+ * `chromeToUnixMsSql(column)`, or read with `statement.setReadBigInts(true)`.
+ */
+export declare const CHROME_EPOCH_OFFSET_MS = 11644473600000;
+/**
+ * A SQL expression converting a Chrome time column to Unix milliseconds
+ * (integer division, so sub-millisecond precision is dropped).
+ * @param column A trusted, developer-supplied column name
+ */
+export declare function chromeToUnixMsSql(column: string): string;
+/**
+ * Convert Unix milliseconds to a Chrome timestamp, for binding against a Chrome
+ * time column. The result is exact until the year 3800 although it exceeds
+ * Number.MAX_SAFE_INTEGER: it is a multiple of 1000, and so of 8, below 2^56.
+ * @param unixMs Unix timestamp in milliseconds
+ * @returns Chrome timestamp in microseconds since Jan 1, 1601
+ */
+export declare function unixMsToChromeTimestamp(unixMs: number): number;
+//# sourceMappingURL=chromeEpoch.d.ts.map

package/dist/chromeEpoch.js

@@ -0,0 +1,31 @@
+/**
+ * Chrome epoch timestamp utilities.
+ *
+ * Chromium stores times (History `visits.visit_time`, `urls.last_visit_time`)
+ * as microseconds since January 1, 1601 00:00:00 UTC, the Windows FILETIME
+ * epoch. Unix timestamps count from January 1, 1970 00:00:00 UTC. The
+ * difference is 11,644,473,600 seconds.
+ *
+ * Current Chrome times exceed Number.MAX_SAFE_INTEGER, so `node:sqlite` throws
+ * ERR_OUT_OF_RANGE when reading them as numbers. Convert in SQL with
+ * `chromeToUnixMsSql(column)`, or read with `statement.setReadBigInts(true)`.
+ */
+export const CHROME_EPOCH_OFFSET_MS = 11_644_473_600_000;
+/**
+ * A SQL expression converting a Chrome time column to Unix milliseconds
+ * (integer division, so sub-millisecond precision is dropped).
+ * @param column A trusted, developer-supplied column name
+ */
+export function chromeToUnixMsSql(column) {
+    return `(${column} / 1000 - ${CHROME_EPOCH_OFFSET_MS})`;
+}
+/**
+ * Convert Unix milliseconds to a Chrome timestamp, for binding against a Chrome
+ * time column. The result is exact until the year 3800 although it exceeds
+ * Number.MAX_SAFE_INTEGER: it is a multiple of 1000, and so of 8, below 2^56.
+ * @param unixMs Unix timestamp in milliseconds
+ * @returns Chrome timestamp in microseconds since Jan 1, 1601
+ */
+export function unixMsToChromeTimestamp(unixMs) {
+    return (Math.floor(unixMs) + CHROME_EPOCH_OFFSET_MS) * 1000;
+}

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * from './SqliteExtractor.js';
 export * from './statements.js';
 export * from './timeRange.js';
 export * from './appleEpoch.js';
+export * from './chromeEpoch.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './SqliteExtractor.js';
 export * from './statements.js';
 export * from './timeRange.js';
 export * from './appleEpoch.js';
+export * from './chromeEpoch.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/etl-sqlite",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -19,8 +19,8 @@
   "type": "module",
   "description": "Read-only SQLite extraction using built-in node:sqlite",
   "devDependencies": {
-    "@chronicle.app/etl": "0.3.0",
-    "@chronicle.app/tsconfig": "0.3.0",
+    "@chronicle.app/etl": "0.4.0",
+    "@chronicle.app/tsconfig": "0.4.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },