@chronicle.app/etl-sqlite 0.1.0

package/LICENSE

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

@@ -0,0 +1,13 @@
+# @chronicle.app/etl-sqlite
+
+SQLite extraction with built-in `node:sqlite` on Node >=22.13.0.
+
+Extend `SqliteExtractor`, declare `source` and `strategy`, and implement `extract()` using the protected `db` connection. Pass an existing database path as `input`. Always call `teardown()` in a `finally` block, including after setup or extraction fails.
+
+The connection is read-only: missing databases are not created, and journal mode is not changed. Live WAL databases require access to the database and its sidecar files; a copied database must include uncheckpointed WAL contents or be a consistent SQLite backup.
+
+`timeRangeConditions(column, range, options)` returns parameterized SQL conditions and values. The column is a trusted developer-supplied SQL identifier, not user input. Bounds are exclusive by default; conversion functions and inclusive operators are supported. Numeric dates are Unix milliseconds; the default SQL values are Unix seconds.
+
+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.
+
+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.

package/dist/SqliteExtractor.d.ts

@@ -0,0 +1,28 @@
+import { DatabaseSync } from 'node:sqlite';
+import { z } from 'zod';
+import { type Delivery, Extractor } from '@chronicle.app/etl';
+/** Read an existing source database without changing its journal mode. */
+export declare abstract class SqliteExtractor<SelfClass extends typeof SqliteExtractor = typeof SqliteExtractor> extends Extractor<SelfClass> {
+    static delivery: Delivery;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        input: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        input: string;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        input: string;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    protected db: DatabaseSync | null;
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+}
+//# sourceMappingURL=SqliteExtractor.d.ts.map

package/dist/SqliteExtractor.js

@@ -0,0 +1,25 @@
+import { DatabaseSync } from 'node:sqlite';
+import { z } from 'zod';
+import { Extractor } from '@chronicle.app/etl';
+/** Read an existing source database without changing its journal mode. */
+export class SqliteExtractor extends Extractor {
+    static delivery = 'local';
+    static schema = Extractor.schema.extend({
+        input: z.string().min(1).describe('Path to an existing SQLite database'),
+    });
+    db = null;
+    async setup() {
+        if (this.db)
+            throw new Error('Database already initialized');
+        await super.setup();
+        const { input } = this.config;
+        this.db = new DatabaseSync(input, { readOnly: true });
+    }
+    async teardown() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+        await super.teardown();
+    }
+}

package/dist/appleEpoch.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Apple epoch timestamp utilities.
+ *
+ * Apple's Core Data / Core Foundation timestamps count from
+ * January 1, 2001 00:00:00 UTC; Unix timestamps count from
+ * January 1, 1970 00:00:00 UTC. The difference is 978,307,200 seconds.
+ *
+ * Two unit families appear in Apple SQLite stores:
+ * - seconds since 2001 (Safari History.db, WhatsApp ChatStorage.sqlite,
+ *   CallHistory.storedata, Podcasts MTLibrary.sqlite)
+ * - nanoseconds since 2001 (Messages chat.db)
+ */
+export declare const APPLE_EPOCH_OFFSET_SECONDS = 978307200;
+/**
+ * Convert an iOS timestamp to a Unix timestamp
+ * @param iosTimestamp iOS timestamp (nanoseconds since Jan 1, 2001)
+ * @returns Unix timestamp in milliseconds
+ */
+export declare function iosToUnixTimestamp(iosTimestamp: number): number;
+/**
+ * Convert a Unix timestamp to an iOS timestamp
+ * @param unixTimestamp Unix timestamp in seconds
+ * @returns iOS timestamp in nanoseconds
+ */
+export declare function unixToIosTimestamp(unixTimestamp: number): number;
+/**
+ * Convert a Safari timestamp (seconds since 2001) to a Unix timestamp
+ * @param safariTimestamp Safari timestamp in seconds since Jan 1, 2001
+ * @returns Unix timestamp in seconds
+ */
+export declare function safariToUnixTimestamp(safariTimestamp: number): number;
+/**
+ * Convert a Unix timestamp to a Safari timestamp
+ * @param unixTimestamp Unix timestamp in seconds
+ * @returns Safari timestamp in seconds since Jan 1, 2001
+ */
+export declare function unixToSafariTimestamp(unixTimestamp: number): number;
+//# sourceMappingURL=appleEpoch.d.ts.map

package/dist/appleEpoch.js

@@ -0,0 +1,45 @@
+/**
+ * Apple epoch timestamp utilities.
+ *
+ * Apple's Core Data / Core Foundation timestamps count from
+ * January 1, 2001 00:00:00 UTC; Unix timestamps count from
+ * January 1, 1970 00:00:00 UTC. The difference is 978,307,200 seconds.
+ *
+ * Two unit families appear in Apple SQLite stores:
+ * - seconds since 2001 (Safari History.db, WhatsApp ChatStorage.sqlite,
+ *   CallHistory.storedata, Podcasts MTLibrary.sqlite)
+ * - nanoseconds since 2001 (Messages chat.db)
+ */
+export const APPLE_EPOCH_OFFSET_SECONDS = 978_307_200;
+/**
+ * Convert an iOS timestamp to a Unix timestamp
+ * @param iosTimestamp iOS timestamp (nanoseconds since Jan 1, 2001)
+ * @returns Unix timestamp in milliseconds
+ */
+export function iosToUnixTimestamp(iosTimestamp) {
+    return (iosTimestamp / 1_000_000_000 + APPLE_EPOCH_OFFSET_SECONDS) * 1000;
+}
+/**
+ * Convert a Unix timestamp to an iOS timestamp
+ * @param unixTimestamp Unix timestamp in seconds
+ * @returns iOS timestamp in nanoseconds
+ */
+export function unixToIosTimestamp(unixTimestamp) {
+    return (unixTimestamp - APPLE_EPOCH_OFFSET_SECONDS) * 1_000_000_000;
+}
+/**
+ * Convert a Safari timestamp (seconds since 2001) to a Unix timestamp
+ * @param safariTimestamp Safari timestamp in seconds since Jan 1, 2001
+ * @returns Unix timestamp in seconds
+ */
+export function safariToUnixTimestamp(safariTimestamp) {
+    return safariTimestamp + APPLE_EPOCH_OFFSET_SECONDS;
+}
+/**
+ * Convert a Unix timestamp to a Safari timestamp
+ * @param unixTimestamp Unix timestamp in seconds
+ * @returns Safari timestamp in seconds since Jan 1, 2001
+ */
+export function unixToSafariTimestamp(unixTimestamp) {
+    return unixTimestamp - APPLE_EPOCH_OFFSET_SECONDS;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './SqliteExtractor.js';
+export * from './timeRange.js';
+export * from './appleEpoch.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './SqliteExtractor.js';
+export * from './timeRange.js';
+export * from './appleEpoch.js';

package/dist/timeRange.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A since/until window, as it appears on every extractor config. Values are
+ * normally Dates (the extractor schema coerces them) but strings/numbers are
+ * accepted and parsed.
+ */
+export interface TimeRange {
+    since?: Date | string | number | null;
+    until?: Date | string | number | null;
+}
+export interface TimeRangeOptions {
+    /**
+     * Map a bound to the column's native representation. Defaults to Unix
+     * seconds. Pass an Apple-epoch conversion for Core Data columns
+     * (e.g. `(d) => unixToSafariTimestamp(d.getTime() / 1000)`), or a string
+     * formatter for text datetime columns.
+     */
+    convert?: (date: Date) => number | string;
+    /** Comparator for the since bound (default `>`). */
+    sinceOp?: '>' | '>=';
+    /** Comparator for the until bound (default `<`). */
+    untilOp?: '<' | '<=';
+}
+/**
+ * Build parameterized WHERE conditions for a since/until window over a raw SQL
+ * query. Returns one condition string (`"col > ?"`) plus its value per bound
+ * that is set; both empty when the range is unbounded.
+ */
+export declare function timeRangeConditions(column: string, range: TimeRange, options?: TimeRangeOptions): {
+    conditions: string[];
+    values: Array<number | string>;
+};
+//# sourceMappingURL=timeRange.d.ts.map

package/dist/timeRange.js

@@ -0,0 +1,26 @@
+const defaultConvert = (date) => date.getTime() / 1000;
+const asDate = (value) => {
+    const date = value instanceof Date ? value : new Date(value);
+    if (!Number.isFinite(date.getTime()))
+        throw new Error('Invalid time range date');
+    return date;
+};
+/**
+ * Build parameterized WHERE conditions for a since/until window over a raw SQL
+ * query. Returns one condition string (`"col > ?"`) plus its value per bound
+ * that is set; both empty when the range is unbounded.
+ */
+export function timeRangeConditions(column, range, options = {}) {
+    const { convert = defaultConvert, sinceOp = '>', untilOp = '<' } = options;
+    const conditions = [];
+    const values = [];
+    if (range.since !== undefined && range.since !== null) {
+        conditions.push(`${column} ${sinceOp} ?`);
+        values.push(convert(asDate(range.since)));
+    }
+    if (range.until !== undefined && range.until !== null) {
+        conditions.push(`${column} ${untilOp} ?`);
+        values.push(convert(asDate(range.until)));
+    }
+    return { conditions, values };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chronicle.app/etl-sqlite",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Read-only SQLite extraction using built-in node:sqlite",
+  "devDependencies": {
+    "@chronicle.app/tsconfig": "0.1.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "core/etl-sqlite"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/etl": "0.1.0",
+    "zod": "^3.24.1"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}