@tsdoctor/snapshot 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,8 @@ Incremental-build snapshot tracking for static documentation pipelines. The pack
 ## What you get
 
 - **`SnapshotService`** — an Effect service tag with typed operations: single and bulk lookup, transactional batch upsert (with a conditional `ON CONFLICT ... DO UPDATE ... WHERE` that avoids rewriting unchanged rows), deletion and stale-entry cleanup.
-- **`SnapshotServiceLive(dbPath)`** — the live layer over a SQLite file. Layer construction applies migrations through `@effected/store`'s ledger; a WAL checkpoint runs as a scope finalizer on clean shutdown.
+- **`SnapshotService.layer(dbPath)`** — the live layer over a SQLite file. Layer construction applies migrations through `@effected/store`'s ledger; a WAL checkpoint runs as a scope finalizer on clean shutdown. It is a factory: call it once per database path and bind the result to a `const`, since layers memoize by reference.
+- **`SnapshotService.makeTest(overrides)` / `SnapshotService.layerTest(overrides)`** — an in-memory double describing a build with no prior snapshot: every lookup misses, every write is accepted and discarded, and nothing is reported stale.
 - **`hashContent` / `hashFrontmatter` / `normalizeContent`** — pure SHA-256 helpers that normalize markdown bodies and frontmatter (excluding timestamp fields) into stable change-detection hashes.
 - **`FileSnapshot`** / **`SnapshotDbError`** — the tracked-file record and the typed error every operation can fail with.
 
@@ -27,10 +28,10 @@ This is an ESM-only package. `effect` (v4) and `@effected/store` are peer depend
 ## Quick start
 
 ```ts
-import { SnapshotService, SnapshotServiceLive, hashContent } from "@tsdoctor/snapshot";
+import { SnapshotService, hashContent } from "@tsdoctor/snapshot";
 import { Effect } from "effect";
 
-const layer = SnapshotServiceLive(".api-docs/snapshot/api-docs.db");
+const layer = SnapshotService.layer(".api-docs/snapshot/api-docs.db");
 
 const program = Effect.gen(function* () {
   const snapshots = yield* SnapshotService;

package/SnapshotService.js

@@ -1,4 +1,6 @@
-import { Context, Data } from "effect";
+import { hashContent } from "./content-hash.js";
+import { Store } from "@effected/store";
+import { Context, Data, Effect, Layer, Option } from "effect";
 
 //#region src/SnapshotService.ts
 /**
@@ -16,12 +18,165 @@ var SnapshotDbError = class extends Data.TaggedError("SnapshotDbError") {
 * Effect service tag for the snapshot tracking store.
 *
 * @remarks
-* Provided by {@link SnapshotServiceLive}, which backs it with a
+* Provided by {@link SnapshotService.layer}, which backs it with a
 * schema-versioned SQLite database via `@effected/store`.
 *
 * @public
 */
-var SnapshotService = class extends Context.Service()("@tsdoctor/snapshot/SnapshotService") {};
+var SnapshotService = class SnapshotService extends Context.Service()("@tsdoctor/snapshot/SnapshotService") {
+	/**
+	* Builds the live {@link SnapshotService} layer over a SQLite database file.
+	*
+	* @remarks
+	* Backed by `@effected/store`'s `Store.layerSqlite`: layer construction opens
+	* the database (WAL mode), ensures the migration ledger and applies pending
+	* migrations. `checkpointOnClose` folds the WAL sidecar files back into the
+	* main database on clean shutdown.
+	*
+	* This is a parameterized layer factory: call it once per database path and
+	* bind the result to a `const` — layers memoize by reference, and a fresh
+	* call at each provide site would open the database more than once. The
+	* parent directory of `dbPath` must already exist.
+	*
+	* @param dbPath - Path to the SQLite database file
+	* @returns A layer providing {@link SnapshotService}
+	* @public
+	*/
+	static layer = (dbPath) => make(dbPath);
+	/**
+	* An in-memory double: no SQLite file, no migrations, no WAL.
+	*
+	* @remarks
+	* Defaults describe a build with **no prior snapshot** — every lookup misses
+	* and every write is accepted and discarded, which is the state a first
+	* build or a fresh clone is in, and the state the disk-fallback path is
+	* written against.
+	*
+	* `cleanupStale` defaults to reporting nothing stale rather than echoing its
+	* input: a double that claimed files were stale would have the caller DELETE
+	* them from disk.
+	*
+	* @public
+	*/
+	static makeTest = (overrides = {}) => ({
+		getSnapshot: overrides.getSnapshot ?? (() => Effect.succeed(Option.none())),
+		getAllForDirectory: overrides.getAllForDirectory ?? (() => Effect.succeed([])),
+		getFilePaths: overrides.getFilePaths ?? (() => Effect.succeed([])),
+		upsert: overrides.upsert ?? (() => Effect.succeed(true)),
+		batchUpsert: overrides.batchUpsert ?? ((snapshots) => Effect.succeed(snapshots.length)),
+		deleteSnapshot: overrides.deleteSnapshot ?? (() => Effect.void),
+		cleanupStale: overrides.cleanupStale ?? (() => Effect.succeed([]))
+	});
+	/**
+	* {@link SnapshotService.makeTest} behind a `Layer`.
+	*
+	* @public
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(SnapshotService, SnapshotService.makeTest(overrides));
+};
+function toFileSnapshot(row) {
+	return {
+		outputDir: row.output_dir,
+		filePath: row.file_path,
+		publishedTime: row.published_time,
+		modifiedTime: row.modified_time,
+		contentHash: row.content_hash,
+		frontmatterHash: row.frontmatter_hash,
+		buildTime: row.build_time
+	};
+}
+function toSnapshotDbError(error) {
+	return new SnapshotDbError({
+		operation: "query",
+		dbPath: "snapshot-db",
+		reason: error instanceof Error ? error.message : String(error)
+	});
+}
+const migrations = [{
+	id: 1,
+	name: "001_create_snapshots",
+	up: (sql) => Effect.gen(function* () {
+		yield* sql`
+					CREATE TABLE IF NOT EXISTS file_snapshots (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						output_dir TEXT NOT NULL,
+						file_path TEXT NOT NULL,
+						published_time TEXT NOT NULL,
+						modified_time TEXT NOT NULL,
+						content_hash TEXT NOT NULL,
+						frontmatter_hash TEXT NOT NULL,
+						build_time TEXT NOT NULL,
+						UNIQUE(output_dir, file_path)
+					)
+				`;
+		yield* sql`CREATE INDEX IF NOT EXISTS idx_output_dir ON file_snapshots(output_dir)`;
+		yield* sql`CREATE INDEX IF NOT EXISTS idx_file_path ON file_snapshots(file_path)`;
+	})
+}];
+const make = (dbPath) => {
+	const StoreLive = Store.layerSqlite({
+		filename: dbPath,
+		migrations,
+		checkpointOnClose: true
+	});
+	const ServiceImpl = Layer.effect(SnapshotService, Effect.gen(function* () {
+		const sql = (yield* Store).client;
+		return {
+			hashContent,
+			getSnapshot: (outputDir, filePath) => sql`SELECT * FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${filePath}`.pipe(Effect.map((rows) => rows.length > 0 ? Option.some(toFileSnapshot(rows[0])) : Option.none()), Effect.mapError(toSnapshotDbError)),
+			getAllForDirectory: (outputDir) => sql`SELECT * FROM file_snapshots WHERE output_dir = ${outputDir}`.pipe(Effect.map((rows) => rows.map(toFileSnapshot)), Effect.mapError(toSnapshotDbError)),
+			getFilePaths: (outputDir) => sql`SELECT file_path FROM file_snapshots WHERE output_dir = ${outputDir}`.pipe(Effect.map((rows) => rows.map((r) => r.file_path)), Effect.mapError(toSnapshotDbError)),
+			upsert: (snapshot) => sql`INSERT INTO file_snapshots
+						(output_dir, file_path, published_time, modified_time,
+						 content_hash, frontmatter_hash, build_time)
+						VALUES (${snapshot.outputDir}, ${snapshot.filePath},
+								${snapshot.publishedTime}, ${snapshot.modifiedTime},
+								${snapshot.contentHash}, ${snapshot.frontmatterHash},
+								${snapshot.buildTime})
+						ON CONFLICT(output_dir, file_path) DO UPDATE SET
+							published_time = ${snapshot.publishedTime},
+							modified_time = ${snapshot.modifiedTime},
+							content_hash = ${snapshot.contentHash},
+							frontmatter_hash = ${snapshot.frontmatterHash},
+							build_time = ${snapshot.buildTime}
+						WHERE published_time != ${snapshot.publishedTime}
+						   OR modified_time != ${snapshot.modifiedTime}
+						   OR content_hash != ${snapshot.contentHash}
+						   OR frontmatter_hash != ${snapshot.frontmatterHash}`.pipe(Effect.as(true), Effect.mapError(toSnapshotDbError)),
+			batchUpsert: (snapshots) => (snapshots.length === 0 ? Effect.succeed(0) : sql.withTransaction(Effect.forEach(snapshots, (s) => sql`INSERT INTO file_snapshots
+												(output_dir, file_path, published_time, modified_time,
+												 content_hash, frontmatter_hash, build_time)
+												VALUES (${s.outputDir}, ${s.filePath},
+														${s.publishedTime}, ${s.modifiedTime},
+														${s.contentHash}, ${s.frontmatterHash},
+														${s.buildTime})
+												ON CONFLICT(output_dir, file_path) DO UPDATE SET
+													published_time = ${s.publishedTime},
+													modified_time = ${s.modifiedTime},
+													content_hash = ${s.contentHash},
+													frontmatter_hash = ${s.frontmatterHash},
+													build_time = ${s.buildTime}
+												WHERE published_time != ${s.publishedTime}
+												   OR modified_time != ${s.modifiedTime}
+												   OR content_hash != ${s.contentHash}
+												   OR frontmatter_hash != ${s.frontmatterHash}`, { concurrency: 1 })).pipe(Effect.map(() => snapshots.length))).pipe(Effect.mapError(toSnapshotDbError)),
+			deleteSnapshot: (outputDir, filePath) => sql`DELETE FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${filePath}`.pipe(Effect.asVoid, Effect.mapError(toSnapshotDbError)),
+			cleanupStale: (outputDir, currentFiles) => Effect.gen(function* () {
+				const rows = yield* sql`SELECT file_path FROM file_snapshots WHERE output_dir = ${outputDir}`;
+				const staleFiles = [];
+				for (const row of rows) {
+					const fp = row.file_path;
+					if (!currentFiles.has(fp)) {
+						yield* sql`DELETE FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${fp}`;
+						staleFiles.push(fp);
+					}
+				}
+				return staleFiles;
+			}).pipe(Effect.mapError(toSnapshotDbError))
+		};
+	}));
+	return Layer.provide(ServiceImpl, StoreLive);
+};
 
 //#endregion
 export { SnapshotDbError, SnapshotService };

package/index.d.ts

@@ -1,5 +1,5 @@
-import { Context, Effect, Layer, Option } from "effect";
 import { StoreError, StoreMigrationError } from "@effected/store";
+import { Context, Effect, Layer, Option } from "effect";
 //#region src/content-hash.d.ts
 /**
  * Normalizes content string for consistent hashing.
@@ -119,8 +119,6 @@ declare class SnapshotDbError extends SnapshotDbError_base<{
  * @public
  */
 interface SnapshotServiceShape {
-  /** Hash normalized content with SHA-256 (pure, synchronous). */
-  readonly hashContent: (content: string) => string;
   /** Look up a single snapshot by output directory and file path. */
   readonly getSnapshot: (outputDir: string, filePath: string) => Effect.Effect<Option.Option<FileSnapshot>, SnapshotDbError>;
   /** Load every snapshot recorded for an output directory. */
@@ -143,34 +141,54 @@ declare const SnapshotService_base: Context.ServiceClass<SnapshotService, "@tsdo
  * Effect service tag for the snapshot tracking store.
  *
  * @remarks
- * Provided by {@link SnapshotServiceLive}, which backs it with a
+ * Provided by {@link SnapshotService.layer}, which backs it with a
  * schema-versioned SQLite database via `@effected/store`.
  *
  * @public
  */
-declare class SnapshotService extends SnapshotService_base {}
-//#endregion
-//#region src/SnapshotServiceLive.d.ts
-/**
- * Builds the live {@link SnapshotService} layer over a SQLite database file.
- *
- * @remarks
- * Backed by `@effected/store`'s `Store.layerSqlite`: layer construction opens
- * the database (WAL mode), ensures the migration ledger and applies pending
- * migrations. A WAL checkpoint (`PRAGMA wal_checkpoint(TRUNCATE)`) is
- * registered as a scope finalizer so the sidecar files are folded back into
- * the main database on clean shutdown.
- *
- * This is a parameterized layer factory: call it once per database path and
- * bind the result to a `const` — layers memoize by reference, and a fresh
- * call at each provide site would open the database more than once. The
- * parent directory of `dbPath` must already exist.
- *
- * @param dbPath - Path to the SQLite database file
- * @returns A layer providing {@link SnapshotService}
- * @public
- */
-declare const SnapshotServiceLive: (dbPath: string) => Layer.Layer<SnapshotService, StoreError | StoreMigrationError>;
+declare class SnapshotService extends SnapshotService_base {
+  /**
+   * Builds the live {@link SnapshotService} layer over a SQLite database file.
+   *
+   * @remarks
+   * Backed by `@effected/store`'s `Store.layerSqlite`: layer construction opens
+   * the database (WAL mode), ensures the migration ledger and applies pending
+   * migrations. `checkpointOnClose` folds the WAL sidecar files back into the
+   * main database on clean shutdown.
+   *
+   * This is a parameterized layer factory: call it once per database path and
+   * bind the result to a `const` — layers memoize by reference, and a fresh
+   * call at each provide site would open the database more than once. The
+   * parent directory of `dbPath` must already exist.
+   *
+   * @param dbPath - Path to the SQLite database file
+   * @returns A layer providing {@link SnapshotService}
+   * @public
+   */
+  static readonly layer: (dbPath: string) => Layer.Layer<SnapshotService, StoreError | StoreMigrationError>;
+  /**
+   * An in-memory double: no SQLite file, no migrations, no WAL.
+   *
+   * @remarks
+   * Defaults describe a build with **no prior snapshot** — every lookup misses
+   * and every write is accepted and discarded, which is the state a first
+   * build or a fresh clone is in, and the state the disk-fallback path is
+   * written against.
+   *
+   * `cleanupStale` defaults to reporting nothing stale rather than echoing its
+   * input: a double that claimed files were stale would have the caller DELETE
+   * them from disk.
+   *
+   * @public
+   */
+  static readonly makeTest: (overrides?: Partial<SnapshotServiceShape>) => SnapshotServiceShape;
+  /**
+   * {@link SnapshotService.makeTest} behind a `Layer`.
+   *
+   * @public
+   */
+  static readonly layerTest: (overrides?: Partial<SnapshotServiceShape>) => Layer.Layer<SnapshotService>;
+}
 //#endregion
-export { type FileSnapshot, SnapshotDbError, SnapshotService, SnapshotServiceLive, type SnapshotServiceShape, hashContent, hashFrontmatter, normalizeContent };
+export { type FileSnapshot, SnapshotDbError, SnapshotService, type SnapshotServiceShape, hashContent, hashFrontmatter, normalizeContent };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,5 +1,4 @@
 import { hashContent, hashFrontmatter, normalizeContent } from "./content-hash.js";
 import { SnapshotDbError, SnapshotService } from "./SnapshotService.js";
-import { SnapshotServiceLive } from "./SnapshotServiceLive.js";
 
-export { SnapshotDbError, SnapshotService, SnapshotServiceLive, hashContent, hashFrontmatter, normalizeContent };
+export { SnapshotDbError, SnapshotService, hashContent, hashFrontmatter, normalizeContent };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/snapshot",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"private": false,
 	"description": "Incremental-build snapshot tracking for static documentation pipelines: a schema-versioned SQLite store of per-file content hashes and timestamps, built on @effected/store, plus the pure SHA-256 content-hashing helpers that feed it.",
 	"keywords": [
@@ -37,7 +37,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/store": "^0.4.0",
+		"@effected/store": "^0.5.0",
 		"effect": "4.0.0-rc.109"
 	},
 	"engines": {

package/SnapshotServiceLive.js

@@ -1,131 +0,0 @@
-import { hashContent } from "./content-hash.js";
-import { SnapshotDbError, SnapshotService } from "./SnapshotService.js";
-import { Effect, Layer, Option } from "effect";
-import { Store } from "@effected/store";
-
-//#region src/SnapshotServiceLive.ts
-function toFileSnapshot(row) {
-	return {
-		outputDir: row.output_dir,
-		filePath: row.file_path,
-		publishedTime: row.published_time,
-		modifiedTime: row.modified_time,
-		contentHash: row.content_hash,
-		frontmatterHash: row.frontmatter_hash,
-		buildTime: row.build_time
-	};
-}
-function toSnapshotDbError(error) {
-	return new SnapshotDbError({
-		operation: "query",
-		dbPath: "snapshot-db",
-		reason: error instanceof Error ? error.message : String(error)
-	});
-}
-const migrations = [{
-	id: 1,
-	name: "001_create_snapshots",
-	up: (sql) => Effect.gen(function* () {
-		yield* sql`
-					CREATE TABLE IF NOT EXISTS file_snapshots (
-						id INTEGER PRIMARY KEY AUTOINCREMENT,
-						output_dir TEXT NOT NULL,
-						file_path TEXT NOT NULL,
-						published_time TEXT NOT NULL,
-						modified_time TEXT NOT NULL,
-						content_hash TEXT NOT NULL,
-						frontmatter_hash TEXT NOT NULL,
-						build_time TEXT NOT NULL,
-						UNIQUE(output_dir, file_path)
-					)
-				`;
-		yield* sql`CREATE INDEX IF NOT EXISTS idx_output_dir ON file_snapshots(output_dir)`;
-		yield* sql`CREATE INDEX IF NOT EXISTS idx_file_path ON file_snapshots(file_path)`;
-	})
-}];
-/**
-* Builds the live {@link SnapshotService} layer over a SQLite database file.
-*
-* @remarks
-* Backed by `@effected/store`'s `Store.layerSqlite`: layer construction opens
-* the database (WAL mode), ensures the migration ledger and applies pending
-* migrations. A WAL checkpoint (`PRAGMA wal_checkpoint(TRUNCATE)`) is
-* registered as a scope finalizer so the sidecar files are folded back into
-* the main database on clean shutdown.
-*
-* This is a parameterized layer factory: call it once per database path and
-* bind the result to a `const` — layers memoize by reference, and a fresh
-* call at each provide site would open the database more than once. The
-* parent directory of `dbPath` must already exist.
-*
-* @param dbPath - Path to the SQLite database file
-* @returns A layer providing {@link SnapshotService}
-* @public
-*/
-const SnapshotServiceLive = (dbPath) => {
-	const StoreLive = Store.layerSqlite({
-		filename: dbPath,
-		migrations
-	});
-	const ServiceImpl = Layer.effect(SnapshotService, Effect.gen(function* () {
-		const sql = (yield* Store).client;
-		yield* Effect.addFinalizer(() => sql`PRAGMA wal_checkpoint(TRUNCATE)`.pipe(Effect.ignore));
-		return {
-			hashContent,
-			getSnapshot: (outputDir, filePath) => sql`SELECT * FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${filePath}`.pipe(Effect.map((rows) => rows.length > 0 ? Option.some(toFileSnapshot(rows[0])) : Option.none()), Effect.mapError(toSnapshotDbError)),
-			getAllForDirectory: (outputDir) => sql`SELECT * FROM file_snapshots WHERE output_dir = ${outputDir}`.pipe(Effect.map((rows) => rows.map(toFileSnapshot)), Effect.mapError(toSnapshotDbError)),
-			getFilePaths: (outputDir) => sql`SELECT file_path FROM file_snapshots WHERE output_dir = ${outputDir}`.pipe(Effect.map((rows) => rows.map((r) => r.file_path)), Effect.mapError(toSnapshotDbError)),
-			upsert: (snapshot) => sql`INSERT INTO file_snapshots
-						(output_dir, file_path, published_time, modified_time,
-						 content_hash, frontmatter_hash, build_time)
-						VALUES (${snapshot.outputDir}, ${snapshot.filePath},
-								${snapshot.publishedTime}, ${snapshot.modifiedTime},
-								${snapshot.contentHash}, ${snapshot.frontmatterHash},
-								${snapshot.buildTime})
-						ON CONFLICT(output_dir, file_path) DO UPDATE SET
-							published_time = ${snapshot.publishedTime},
-							modified_time = ${snapshot.modifiedTime},
-							content_hash = ${snapshot.contentHash},
-							frontmatter_hash = ${snapshot.frontmatterHash},
-							build_time = ${snapshot.buildTime}
-						WHERE published_time != ${snapshot.publishedTime}
-						   OR modified_time != ${snapshot.modifiedTime}
-						   OR content_hash != ${snapshot.contentHash}
-						   OR frontmatter_hash != ${snapshot.frontmatterHash}`.pipe(Effect.as(true), Effect.mapError(toSnapshotDbError)),
-			batchUpsert: (snapshots) => (snapshots.length === 0 ? Effect.succeed(0) : sql.withTransaction(Effect.forEach(snapshots, (s) => sql`INSERT INTO file_snapshots
-												(output_dir, file_path, published_time, modified_time,
-												 content_hash, frontmatter_hash, build_time)
-												VALUES (${s.outputDir}, ${s.filePath},
-														${s.publishedTime}, ${s.modifiedTime},
-														${s.contentHash}, ${s.frontmatterHash},
-														${s.buildTime})
-												ON CONFLICT(output_dir, file_path) DO UPDATE SET
-													published_time = ${s.publishedTime},
-													modified_time = ${s.modifiedTime},
-													content_hash = ${s.contentHash},
-													frontmatter_hash = ${s.frontmatterHash},
-													build_time = ${s.buildTime}
-												WHERE published_time != ${s.publishedTime}
-												   OR modified_time != ${s.modifiedTime}
-												   OR content_hash != ${s.contentHash}
-												   OR frontmatter_hash != ${s.frontmatterHash}`, { concurrency: 1 })).pipe(Effect.map(() => snapshots.length))).pipe(Effect.mapError(toSnapshotDbError)),
-			deleteSnapshot: (outputDir, filePath) => sql`DELETE FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${filePath}`.pipe(Effect.asVoid, Effect.mapError(toSnapshotDbError)),
-			cleanupStale: (outputDir, currentFiles) => Effect.gen(function* () {
-				const rows = yield* sql`SELECT file_path FROM file_snapshots WHERE output_dir = ${outputDir}`;
-				const staleFiles = [];
-				for (const row of rows) {
-					const fp = row.file_path;
-					if (!currentFiles.has(fp)) {
-						yield* sql`DELETE FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${fp}`;
-						staleFiles.push(fp);
-					}
-				}
-				return staleFiles;
-			}).pipe(Effect.mapError(toSnapshotDbError))
-		};
-	}));
-	return Layer.provide(ServiceImpl, StoreLive);
-};
-
-//#endregion
-export { SnapshotServiceLive };