diff --git a/docs/development.md b/docs/development.md index 1c201dce..e60c8fd7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -76,6 +76,25 @@ class. Its extracted functions and their focused tests live in `src/managers/StorageEventManager/`. These organise the event lifecycle separately from the file handler's database and storage effects. +## File-name lookup implementation + +`ServiceFileAccessBase.ts` forwards name queries to the host adapter or its +package-private `ServiceFileAccessBase/fileNames.ts` fallback. The fallback +retains one typed request for the active storage-event count and comparison +policy, shares its pending listing, and uses `FilePathIndex` to select candidates. +A fresh read retires that request before listing again. Older completions remain +visible to their original callers without replacing a newer retained request. +`StorageAccess` inherits the name-query methods from the shared `FileNameLookup` +contract. The host adapter's indexed capability remains optional; the facade's +fallback keeps both methods available without redeclaring their signatures. + +The fallback factory owns only its active-request state. Index creation, request +reuse, candidate selection, and rejection retirement are named module-level +operations with explicit state and dependency parameters. Listing-only operations +accept just `getFileNames`; observation counting is required only by candidate +selection. Direct operation tests cover promise sharing, re-entrant invalidation, +older request rejection, and policy snapshots alongside the factory contract tests. + ## Service composition and state ownership Commonlib uses four related forms of composition. Choose between them by ownership and dependency direction, not merely by whether an implementation has mutable state. diff --git a/docs/platform-storage.md b/docs/platform-storage.md index c586953a..c0b72f76 100644 --- a/docs/platform-storage.md +++ b/docs/platform-storage.md @@ -122,6 +122,28 @@ version. Its ordinary case-mismatch check remains separate from path-version admission. See [Unicode path identity](unicode-path-identity.md#supported-hosts) for the current publication and host-adoption boundaries. +## File-name candidate lookup + +These file-name APIs are an unreleased Commonlib change. `FilePathIndex`, +exported from `/storage`, keeps original file names and groups +all candidates under an explicit Unicode and case policy. It performs no I/O +and owns no watcher or readiness state. The host owns the index lifetime, +initial listing, supported-path rules, and membership updates; use +`replaceAll()` for an initial snapshot and `apply({ removed, added })` for a +membership change. Content-only events do not require an index update. + +Hosts can expose an asynchronous `FileNameLookup` through the optional +`fileNameLookup` property of `IFileSystemAdapter`. When `{ fresh: true }` is +supplied, `getFileNames()` must ask the host's supported listing authority +again. `findPathIdentityCandidates(path, policy)` returns every matching original +path whose comparison key matches the requested identity. Multiple results are +candidates for the caller's collision decision. Keep fresh listing guarantees +host-specific. A host without this +capability continues to list through `getFiles()` and uses the storage-access +fallback. +Direct `StorageAccess` implementations must also implement the required +`findPathIdentityCandidates()` method when adopting this pre-1.0 interface. + ## Bundling boundary Browser consumers import only `@vrtmrz/livesync-commonlib/browser`. Packed-package tests build that entry with browser conditions and verify that the Node implementation is absent. Node consumers import `@vrtmrz/livesync-commonlib/node`; the root and context entries do not load Node built-ins. diff --git a/src/interfaces/StorageAccess.ts b/src/interfaces/StorageAccess.ts index 7d5f293d..105fd78e 100644 --- a/src/interfaces/StorageAccess.ts +++ b/src/interfaces/StorageAccess.ts @@ -9,6 +9,7 @@ import type { } from "@lib/common/types"; import type { CustomRegExp } from "@lib/common/utils"; import type { FileWithFileStat, FileWithStatAsProp } from "@lib/common/models/fileaccess.type"; +import type { FileNameLookup } from "@lib/platform/FilePathIndex.ts"; export interface IStorageAccessManager { processWriteFile(file: UXFileInfoStub | FilePathWithPrefix, proc: () => Promise): Promise; processReadFile(file: UXFileInfoStub | FilePathWithPrefix, proc: () => Promise): Promise; @@ -17,7 +18,13 @@ export interface IStorageAccessManager { touch(file: FileWithStatAsProp | FileWithFileStat): void; clearTouched(): void; } -export interface StorageAccess { +/** + * Storage facade with the shared name-query contract available on every host. + * + * An adapter can omit its indexed lookup capability; the service facade supplies + * the base fallback while retaining the FileNameLookup method contract. + */ +export interface StorageAccess extends FileNameLookup { normalisePath(path: string): string; restoreState(): Promise; @@ -54,7 +61,6 @@ export interface StorageAccess { getStub(path: string): Promise; getFiles(): Promise; - getFileNames(): Promise; touched(file: UXFileInfoStub | FilePathWithPrefix): Promise; recentlyTouched(file: UXFileInfoStub | FilePathWithPrefix): Promise; diff --git a/src/platform/FilePathIndex.ts b/src/platform/FilePathIndex.ts new file mode 100644 index 00000000..a415711d --- /dev/null +++ b/src/platform/FilePathIndex.ts @@ -0,0 +1,239 @@ +import { getStoragePathComparisonKey } from "./pathComparison.ts"; +import type { FilePath, PathComparisonKey, PathComparisonSettings } from "./pathTypes.ts"; + +/** + * Original file paths removed and added by one synchronous membership change. + * + * @remarks + * Repeated additions and absent removals are harmless. A path present in both + * lists remains present, including when it was absent before the change. + * Hosts expand folder renames into file-path deltas before applying them. + */ +export interface FilePathDelta { + readonly removed: readonly FilePath[]; + readonly added: readonly FilePath[]; +} + +/** Controls whether a name read can reuse the host's maintained inventory. */ +export interface FileNameReadOptions { + /** + * Ask the host's listing authority again instead of reusing the name index. + * + * @remarks + * Freshness follows that host's existing listing contract. For example, + * Obsidian supplies its Vault listing rather than an independent disk walk. + */ + readonly fresh?: boolean; +} + +/** Host-owned name reads and candidate selection for one storage root. */ +export interface FileNameLookup { + /** + * Read the host's supported original file paths. + * + * @param options - Whether to ask the listing authority for a fresh view. + * @returns A copy of the complete supported inventory, preserving spelling. + * @throws Rejects unavailable or failed inventory reads rather than reporting + * a successful empty inventory. Host-specific listing exclusions still apply. + */ + getFileNames(options?: FileNameReadOptions): Promise; + + /** + * Find original paths which match the requested path-identity comparison key. + * + * @param path - Original file path to compare within this storage root. + * @param policy - Explicit Unicode normalisation and case comparison rules. + * @returns Every matching original path in diagnostic order, including the + * requested spelling when present. An empty result means no supported match. + * @throws Rejects unavailable coverage and host validation or read failures. + * @remarks + * The host establishes read readiness and physical-path safety. The caller + * decides whether multiple candidates constitute a collision; this operation + * neither chooses a preferred spelling nor compares file contents. + */ + findPathIdentityCandidates(path: FilePath, policy: PathComparisonSettings): Promise; +} + +/** Cache slot for the four supported Unicode/case policies, rather than a file identity. */ +type IdentityPolicyKey = `${PathComparisonSettings["pathNormalizationVersion"]}:${"sensitive" | "insensitive"}`; + +type IdentityBuckets = Map, Set>; + +interface CachedIdentityBuckets { + readonly policy: PathComparisonSettings; + readonly buckets: IdentityBuckets; +} + +function validatePath(path: FilePath): FilePath { + if (typeof path !== "string") { + throw new TypeError("File paths must be strings"); + } + return path; +} + +function snapshotPolicy(policy: PathComparisonSettings): PathComparisonSettings { + const { pathNormalizationVersion, handleFilenameCaseSensitive } = policy; + if (pathNormalizationVersion !== 0 && pathNormalizationVersion !== 1) { + throw new Error(`Unsupported path normalisation version: ${pathNormalizationVersion}`); + } + if (typeof handleFilenameCaseSensitive !== "boolean") { + throw new TypeError("Filename case handling must be explicit"); + } + return { pathNormalizationVersion, handleFilenameCaseSensitive }; +} + +/** Select a bounded cache slot after validating and copying the comparison policy. */ +function getPolicyKey(policy: PathComparisonSettings): IdentityPolicyKey { + return `${policy.pathNormalizationVersion}:${policy.handleFilenameCaseSensitive ? "sensitive" : "insensitive"}`; +} + +/** Group retained spellings by the shared storage comparison key for one policy. */ +function createIdentityBuckets(paths: Iterable, policy: PathComparisonSettings): IdentityBuckets { + const buckets: IdentityBuckets = new Map(); + for (const path of paths) { + const key = getStoragePathComparisonKey(path, policy); + const bucket = buckets.get(key) ?? new Set(); + bucket.add(path); + buckets.set(key, bucket); + } + return buckets; +} + +/** + * Maintains original file-path membership and lazily materialised identity buckets. + * + * @remarks + * The host owns supported-path validation, observation, and query readiness. + * This class stores original spellings and performs no I/O. Membership changes + * update every materialised policy map; at most four policy maps are retained. + * Queries return copies and leave file contents and physical names untouched. + * + * A first query for a policy derives its buckets in one pass over the retained + * paths. Subsequent queries select and sort only the matching candidates. + */ +export class FilePathIndex { + private paths = new Set(); + private indexes = new Map(); + + /** + * Replace the complete inventory and all materialised policy maps together. + * + * @param paths - Host-enumerated original file paths. Duplicate paths collapse + * into one membership without normalising their spelling. + * @throws Propagates invalid runtime members or iterable failures before + * replacing the current inventory or any existing policy map. + * @remarks + * Validation checks string members; filesystem admission remains the host's + * responsibility. Callers use this after a successful initial or fresh read. + */ + replaceAll(paths: Iterable): void { + const nextPaths = new Set(); + for (const path of paths) { + nextPaths.add(validatePath(path)); + } + + const nextIndexes = new Map(); + for (const [key, { policy }] of this.indexes) { + nextIndexes.set(key, { policy, buckets: createIdentityBuckets(nextPaths, policy) }); + } + + this.paths = nextPaths; + this.indexes = nextIndexes; + } + + /** + * Apply one membership delta to the inventory and every cached policy map. + * + * @param delta - Original paths removed and added by the same change. + * @throws Propagates invalid runtime members before changing retained state. + * @remarks + * Inputs and comparison keys are prepared before mutation. The synchronous + * update publishes no intermediate rename state. Repeated notifications do + * not create duplicate memberships, and content-only edits need no delta. + */ + apply(delta: FilePathDelta): void { + const removed = new Set(delta.removed.map(validatePath)); + const added = new Set(delta.added.map(validatePath)); + + // A same-path remove/add is a no-op only when that membership already exists. + for (const path of added) { + if (removed.has(path)) { + removed.delete(path); + if (this.paths.has(path)) { + added.delete(path); + } + } + } + + const actualRemoved = [...removed].filter((path) => this.paths.has(path)); + const actualAdded = [...added].filter((path) => !this.paths.has(path)); + if (actualRemoved.length === 0 && actualAdded.length === 0) { + return; + } + + // Compute every key before mutating membership or any cached policy map. + const indexUpdates = [...this.indexes.values()].map(({ buckets, policy }) => ({ + buckets, + removed: actualRemoved.map((path) => [getStoragePathComparisonKey(path, policy), path] as const), + added: actualAdded.map((path) => [getStoragePathComparisonKey(path, policy), path] as const), + })); + + for (const path of actualRemoved) { + this.paths.delete(path); + } + for (const path of actualAdded) { + this.paths.add(path); + } + for (const { buckets, removed: removedKeys, added: addedKeys } of indexUpdates) { + for (const [key, path] of removedKeys) { + const bucket = buckets.get(key); + bucket?.delete(path); + if (bucket?.size === 0) { + buckets.delete(key); + } + } + for (const [key, path] of addedKeys) { + const bucket = buckets.get(key) ?? new Set(); + bucket.add(path); + buckets.set(key, bucket); + } + } + } + + /** + * Copy the current in-memory membership without refreshing the host listing. + * + * @returns Original spellings in an independent array. Full-list ordering is + * unspecified; changing the returned array cannot change this index. + */ + getFileNames(): FilePath[] { + return [...this.paths]; + } + + /** + * Select every indexed path with the requested storage comparison key. + * + * @param path - Path whose identity selects a candidate bucket. + * @param policy - Explicit Unicode normalisation and case comparison rules. + * @returns A sorted copy of all matching original paths, or an empty array + * when no indexed path matches. Multiple paths remain separate candidates. + * @throws Rejects a non-string path or unsupported comparison settings. + * @remarks + * The first query for each policy materialises its buckets. Later membership + * deltas maintain those buckets incrementally. Host readiness, existence, + * physical alias checks, and the final collision decision are external. + */ + findPathIdentityCandidates(path: FilePath, policy: PathComparisonSettings): readonly FilePath[] { + const validatedPath = validatePath(path); + const policySnapshot = snapshotPolicy(policy); + const policyKey = getPolicyKey(policySnapshot); + let index = this.indexes.get(policyKey); + if (!index) { + index = { policy: policySnapshot, buckets: createIdentityBuckets(this.paths, policySnapshot) }; + this.indexes.set(policyKey, index); + } + + const key = getStoragePathComparisonKey(validatedPath, policySnapshot); + return [...(index.buckets.get(key) ?? [])].sort(); + } +} diff --git a/src/platform/FilePathIndex.unit.spec.ts b/src/platform/FilePathIndex.unit.spec.ts new file mode 100644 index 00000000..555637ec --- /dev/null +++ b/src/platform/FilePathIndex.unit.spec.ts @@ -0,0 +1,147 @@ +import { describe, expect, it } from "vitest"; +import { parseFilePath } from "./pathComparison.ts"; +import { FilePathIndex } from "./FilePathIndex.ts"; + +const path = (value: string) => parseFilePath(value); +const policy = (pathNormalizationVersion: 0 | 1, handleFilenameCaseSensitive: boolean) => ({ + pathNormalizationVersion, + handleFilenameCaseSensitive, +}); + +describe("FilePathIndex", () => { + it("retains original spelling and returns every match for all comparison policies", () => { + const nfc = path("Café.md"); + const nfd = path("Cafe\u0301.md"); + const upper = path("CAFÉ.md"); + const index = new FilePathIndex(); + index.replaceAll([nfc, nfd, upper, path("Note.md"), path("note.md")]); + + expect(index.findPathIdentityCandidates(nfc, policy(0, true))).toEqual([nfc]); + expect(index.findPathIdentityCandidates(nfd, policy(0, false))).toEqual([nfd]); + expect(index.findPathIdentityCandidates(nfc, policy(1, true))).toEqual([nfd, nfc].sort()); + expect(index.findPathIdentityCandidates(path("café.md"), policy(1, false))).toEqual([nfc, nfd, upper].sort()); + expect(index.findPathIdentityCandidates(path("NOTE.md"), policy(0, false))).toEqual(["Note.md", "note.md"]); + expect(index.findPathIdentityCandidates(path("Note.md"), policy(0, true))).toEqual(["Note.md"]); + }); + + it("applies idempotent membership deltas to every materialised policy map", () => { + const index = new FilePathIndex(); + index.replaceAll([path("A.md"), path("a.md")]); + for (const version of [0, 1] as const) { + index.findPathIdentityCandidates(path("a.md"), policy(version, false)); + } + + index.apply({ removed: [path("absent.md"), path("A.md")], added: [path("B.md"), path("B.md")] }); + + expect(index.getFileNames().sort()).toEqual(["B.md", "a.md"]); + expect(index.findPathIdentityCandidates(path("b.md"), policy(0, false))).toEqual(["B.md"]); + expect(index.findPathIdentityCandidates(path("a.md"), policy(1, false))).toEqual(["a.md"]); + }); + + it("treats a same-path remove/add as a no-op and publishes a rename as one delta", () => { + const index = new FilePathIndex(); + index.replaceAll([path("old.md"), path("keep.md")]); + index.apply({ removed: [path("old.md")], added: [path("old.md")] }); + expect(index.getFileNames().sort()).toEqual(["keep.md", "old.md"]); + + index.apply({ removed: [path("new.md")], added: [path("new.md")] }); + expect(index.getFileNames().sort()).toEqual(["keep.md", "new.md", "old.md"]); + + index.apply({ removed: [path("old.md")], added: [path("new.md")] }); + expect(index.getFileNames().sort()).toEqual(["keep.md", "new.md"]); + expect(index.findPathIdentityCandidates(path("old.md"), policy(0, true))).toEqual([]); + }); + + it("leaves membership unchanged when replacement or a delta fails validation", () => { + const index = new FilePathIndex(); + index.replaceAll([path("kept.md")]); + index.findPathIdentityCandidates(path("kept.md"), policy(1, false)); + + const invalidPath = 123 as unknown as ReturnType; + expect(() => index.replaceAll([path("replacement.md"), invalidPath])).toThrow("File paths must be strings"); + expect(() => + index.apply({ + removed: [path("kept.md")], + added: [invalidPath], + }) + ).toThrow("File paths must be strings"); + + expect(index.getFileNames()).toEqual(["kept.md"]); + expect(index.findPathIdentityCandidates(path("kept.md"), policy(1, false))).toEqual(["kept.md"]); + }); + + it("rebuilds every warmed policy candidate set when replacing the inventory", () => { + const nfc = path("Café.md"); + const nfd = path("Cafe\u0301.md"); + const upper = path("CAFÉ.md"); + const replacementNfd = path("cafe\u0301.md"); + const index = new FilePathIndex(); + const policies = [policy(0, true), policy(0, false), policy(1, true), policy(1, false)]; + index.replaceAll([nfc, nfd, upper]); + + for (const selectedPolicy of policies) { + index.findPathIdentityCandidates(nfc, selectedPolicy); + } + + index.replaceAll([replacementNfd, upper, path("other.md")]); + + expect(index.findPathIdentityCandidates(nfc, policies[0]!)).toEqual([]); + expect(index.findPathIdentityCandidates(nfc, policies[1]!)).toEqual([upper]); + expect(index.findPathIdentityCandidates(nfc, policies[2]!)).toEqual([]); + expect(index.findPathIdentityCandidates(path("café.md"), policies[2]!)).toEqual([replacementNfd]); + expect(index.findPathIdentityCandidates(nfc, policies[3]!)).toEqual([replacementNfd, upper].sort()); + expect(index.getFileNames().sort()).toEqual([replacementNfd, upper, "other.md"].sort()); + }); + + it("removes the last cached candidate and restores it after a later addition", () => { + const original = path("Note.md"); + const selectedPolicy = policy(1, false); + const index = new FilePathIndex(); + index.replaceAll([original]); + expect(index.findPathIdentityCandidates(path("note.md"), selectedPolicy)).toEqual([original]); + + index.apply({ removed: [original], added: [] }); + expect(index.findPathIdentityCandidates(path("note.md"), selectedPolicy)).toEqual([]); + + const replacement = path("NOTE.md"); + index.apply({ removed: [], added: [replacement] }); + expect(index.findPathIdentityCandidates(path("note.md"), selectedPolicy)).toEqual([replacement]); + }); + + it("rejects unsupported policies without changing retained membership", () => { + const index = new FilePathIndex(); + index.replaceAll([path("kept.md")]); + const unsupportedPolicy = { + pathNormalizationVersion: 2, + handleFilenameCaseSensitive: true, + } as unknown as Parameters[1]; + + expect(() => index.findPathIdentityCandidates(path("kept.md"), unsupportedPolicy)).toThrow( + "Unsupported path normalisation version: 2" + ); + const invalidCasePolicy = { + pathNormalizationVersion: 1, + handleFilenameCaseSensitive: "true", + } as unknown as Parameters[1]; + expect(() => index.findPathIdentityCandidates(path("kept.md"), invalidCasePolicy)).toThrow( + "Filename case handling must be explicit" + ); + expect(index.getFileNames()).toEqual(["kept.md"]); + expect(index.findPathIdentityCandidates(path("kept.md"), policy(1, true))).toEqual(["kept.md"]); + }); + + it("keeps instances independent and returns copies", () => { + const first = new FilePathIndex(); + const second = new FilePathIndex(); + first.replaceAll([path("Note.md")]); + + const fileNames = first.getFileNames(); + fileNames.push(path("Other.md")); + const candidates = first.findPathIdentityCandidates(path("Note.md"), policy(0, true)) as string[]; + candidates.push("Other.md"); + + expect(first.getFileNames()).toEqual(["Note.md"]); + expect(first.findPathIdentityCandidates(path("Note.md"), policy(0, true))).toEqual(["Note.md"]); + expect(second.getFileNames()).toEqual([]); + }); +}); diff --git a/src/serviceFeatures/targetFilter.ts b/src/serviceFeatures/targetFilter.ts index c579157d..d24fe337 100644 --- a/src/serviceFeatures/targetFilter.ts +++ b/src/serviceFeatures/targetFilter.ts @@ -2,12 +2,11 @@ import { LOG_LEVEL_DEBUG, LOG_LEVEL_VERBOSE, type UXFileInfoStub } from "@lib/co import { createInstanceLogFunction, type LogFunction } from "@lib/services/lib/logUtils"; import { getStoragePathFromUXFileInfo } from "@lib/common/typeUtils"; import { isAcceptedAll } from "@lib/string_and_binary/path"; -import { Computed } from "octagonal-wheels/dataobject/Computed"; import type { NecessaryServices } from "@lib/interfaces/ServiceModule"; import type { IVaultService } from "@lib/services/base/IService"; import { promiseWithResolvers } from "octagonal-wheels/promises"; -import { getPathNormalizationVersion, normalisePathForIdentity } from "@lib/common/pathNormalization"; +import { getPathNormalizationVersion } from "@lib/common/pathNormalization"; /** * This is a simple handler that accepts all files. @@ -23,54 +22,22 @@ export function isAcceptedAlwaysFactory(host: NecessaryServices, l * Check if a file is accepted based on filename duplication in the vault. */ export function isAcceptedInFilenameDuplicationFactory( - host: NecessaryServices<"vault" | "fileProcessing" | "setting", "storageAccess">, + host: NecessaryServices<"vault" | "setting", "storageAccess">, log: LogFunction ) { - const fileCountMapComputed = new Computed({ - evaluation: async (fileEventCount: number, version: number, caseInsensitive: boolean) => { - const vaultFiles = (await host.serviceModules.storageAccess.getFileNames()).sort(); - const fileCountMap = new Map(); - for (const file of vaultFiles) { - const normalised = normalisePathForIdentity(file, version); - const key = caseInsensitive ? normalised.toLowerCase() : normalised; - const paths = fileCountMap.get(key) ?? []; - paths.push(file); - fileCountMap.set(key, paths); - } - return fileCountMap; - }, - requiresUpdate: (args, previousArgs, previousResult) => { - if (!previousResult) return true; - if (previousResult instanceof Error) return true; - if (!previousArgs) return true; - if (args.every((value, index) => value === previousArgs[index])) { - return false; - } - return true; - }, - }); - return async function isAcceptedInFilenameDuplication( file: string | UXFileInfoStub, options?: Parameters[1] ): Promise { if (options?.skipCaseCollisionCheck) return true; - const version = getPathNormalizationVersion(host.services.setting.currentSettings()); - const caseInsensitive = host.services.vault.shouldCheckCaseInsensitively(); - const fileCountMap = ( - await fileCountMapComputed.update( - host.services.fileProcessing.totalStorageFileEventCount, - version, - caseInsensitive - ) - ).value; - + const policy = { + pathNormalizationVersion: getPathNormalizationVersion(host.services.setting.currentSettings()), + handleFilenameCaseSensitive: !host.services.vault.shouldCheckCaseInsensitively(), + }; const filepath = getStoragePathFromUXFileInfo(file); - const normalised = normalisePathForIdentity(filepath, version); - const key = caseInsensitive ? normalised.toLowerCase() : normalised; - const duplicates = fileCountMap.get(key); - if (duplicates && duplicates.length > 1) { - log("File path identity collision: " + duplicates.map((path) => JSON.stringify(path)).join(", ")); + const candidates = await host.serviceModules.storageAccess.findPathIdentityCandidates(filepath, policy); + if (candidates.length > 1) { + log("File path identity collision: " + candidates.map((path) => JSON.stringify(path)).join(", ")); return false; } log("File is not duplicated: " + filepath, LOG_LEVEL_DEBUG); @@ -199,7 +166,6 @@ export function useTargetFilters( services: { context: services.context, vault: services.vault, - fileProcessing: services.fileProcessing, setting: services.setting, }, serviceModules: { storageAccess: serviceModules.storageAccess }, diff --git a/src/serviceFeatures/targetFilter.unit.spec.ts b/src/serviceFeatures/targetFilter.unit.spec.ts index 77da2965..574fd014 100644 --- a/src/serviceFeatures/targetFilter.unit.spec.ts +++ b/src/serviceFeatures/targetFilter.unit.spec.ts @@ -4,6 +4,8 @@ import { isAcceptedAlwaysFactory } from "./targetFilter"; import { type LogFunction, createInstanceLogFunction } from "@lib/services/lib/logUtils"; import { handlers } from "@lib/services/lib/HandlerUtils"; import type { IVaultService } from "@lib/services/base/IService"; +import { getStoragePathComparisonKey } from "@lib/platform/pathComparison.ts"; +import type { FilePath, PathComparisonSettings } from "@lib/platform/pathTypes.ts"; const APIServiceMock = { addLog(message: string, level?: any) { // For testing, we can simply log to console or store logs in an array if needed. @@ -38,13 +40,19 @@ const mockVault = { return this._caseSensitivityDisabled; }, }; -const mockStorageAccess = { - _files: ["a.md", "A.md", "b.txt", "c.txt", "c.md"], - getFileNames: () => mockStorageAccess._files, -}; -const mockFileProcessing = { - totalStorageFileEventCount: 0, -}; +function createCandidateStorage(files: string[]) { + return { + _files: files, + findPathIdentityCandidates(path: FilePath, policy: PathComparisonSettings) { + const key = getStoragePathComparisonKey(path, policy); + return Promise.resolve( + this._files + .filter((candidate) => getStoragePathComparisonKey(candidate as FilePath, policy) === key) + .sort() + ); + }, + }; +} describe("isAcceptedInFilenameDuplication", () => { let logger: LogFunction; beforeAll(() => { @@ -55,11 +63,10 @@ describe("isAcceptedInFilenameDuplication", () => { return { services: { vault: mockVault, - fileProcessing: mockFileProcessing, setting: { currentSettings: () => ({ pathNormalizationVersion: 0 }) }, }, serviceModules: { - storageAccess: mockStorageAccess, + storageAccess: createCandidateStorage(["a.md", "A.md", "b.txt", "c.txt", "c.md"]), }, } as any; } @@ -77,17 +84,11 @@ describe("isAcceptedInFilenameDuplication", () => { expect(await handler("A.md")).toBe(false); expect(await handler("b.txt")).toBe(true); }); - it("should memorise file count map and update only when totalStorageFileEventCount changes", async () => { + it("delegates candidate freshness to storage access", async () => { const host = createHost({ caseInsensitive: true }); const handler = isAcceptedInFilenameDuplicationFactory(host, logger); - expect(await handler("a.md")).toBe(false); - expect(await handler("A.md")).toBe(false); expect(await handler("b.txt")).toBe(true); host.serviceModules.storageAccess._files.push("B.txt"); - // still should return false because the file count map is memorised and not updated yet - expect(await handler("b.txt")).toBe(true); - // update totalStorageFileEventCount to trigger file count map update - host.services.fileProcessing.totalStorageFileEventCount++; expect(await handler("b.txt")).toBe(false); }); @@ -120,9 +121,8 @@ describe("NFC filename duplication", () => { services: { setting: { currentSettings: () => settings }, vault: { shouldCheckCaseInsensitively: () => caseInsensitive }, - fileProcessing: { totalStorageFileEventCount: 0 }, }, - serviceModules: { storageAccess: { getFileNames: async () => files } }, + serviceModules: { storageAccess: createCandidateStorage(files) }, } as any; return { settings, files, handler: isAcceptedInFilenameDuplicationFactory(host, createLogger("NFC")) }; } @@ -145,6 +145,42 @@ describe("NFC filename duplication", () => { }); }); +describe("filename collision candidate lookup", () => { + it("delegates candidate lookup with one explicit comparison policy", async () => { + const candidateLookups: Array<{ path: string; policy: unknown }> = []; + let wholeNameReads = 0; + const storageAccess = { + getFileNames: async () => { + wholeNameReads++; + return ["a.md"]; + }, + findPathIdentityCandidates: async (path: string, policy: unknown) => { + candidateLookups.push({ path, policy }); + return [path]; + }, + }; + const host = { + services: { + setting: { currentSettings: () => ({ pathNormalizationVersion: 1 }) }, + vault: { shouldCheckCaseInsensitively: () => false }, + fileProcessing: { totalStorageFileEventCount: 0 }, + }, + serviceModules: { storageAccess }, + } as any; + + const accepted = await isAcceptedInFilenameDuplicationFactory(host, createLogger("candidate lookup"))("a.md"); + + expect(accepted).toBe(true); + expect(wholeNameReads).toBe(0); + expect(candidateLookups).toEqual([ + { + path: "a.md", + policy: { pathNormalizationVersion: 1, handleFilenameCaseSensitive: true }, + }, + ]); + }); +}); + describe("isAcceptedByLocalDB", () => { let logger: LogFunction; beforeAll(() => { diff --git a/src/serviceModules/FileAccessBase.ts b/src/serviceModules/FileAccessBase.ts index 2b51f3ce..94ec2459 100644 --- a/src/serviceModules/FileAccessBase.ts +++ b/src/serviceModules/FileAccessBase.ts @@ -6,6 +6,8 @@ import type { IAPIService, IPathService, ISettingService, IVaultService } from " import { createInstanceLogFunction } from "@lib/services/lib/logUtils.ts"; import type { FileWithFileStat } from "@lib/common/models/fileaccess.type"; import type { IFileSystemAdapter } from "./adapters"; +import type { FileNameReadOptions } from "@lib/platform/FilePathIndex.ts"; +import type { PathComparisonSettings } from "@lib/platform/pathTypes.ts"; export function toArrayBuffer(arr: Uint8Array | ArrayBuffer | DataView): ArrayBuffer { if (arr instanceof Uint8Array) { @@ -296,6 +298,21 @@ export class FileAccessBase { + if (this.adapter.fileNameLookup) { + return await this.adapter.fileNameLookup.getFileNames(options); + } + const files = await this.getFiles(); + return files.map((file) => this.getPath(file)); + } + + findPathIdentityCandidates( + path: FilePath, + policy: PathComparisonSettings + ): Promise | undefined { + return this.adapter.fileNameLookup?.findPathIdentityCandidates(path, policy); + } + async ensureDirectory(fullPath: string) { const pathElements = fullPath.split("/"); pathElements.pop(); diff --git a/src/serviceModules/FileAccessBase.unit.spec.ts b/src/serviceModules/FileAccessBase.unit.spec.ts index a20f1283..fd143a5b 100644 --- a/src/serviceModules/FileAccessBase.unit.spec.ts +++ b/src/serviceModules/FileAccessBase.unit.spec.ts @@ -11,6 +11,8 @@ import type { } from "./adapters"; import type { FilePath, UXDataWriteOptions, UXFileInfoStub, UXFolderInfo, UXStat } from "@lib/common/types"; import { compareFileFreshnessGeneric } from "@lib/services/implements/injectable/InjectablePathService"; +import type { FileNameLookup } from "@lib/platform/FilePathIndex.ts"; +import type { PathComparisonSettings } from "@lib/platform/pathTypes.ts"; // Mock file types interface MockFile { @@ -261,6 +263,7 @@ class MockFileSystemAdapter implements IFileSystemAdapter; readonly storage: MockStorageAdapter; readonly vault: MockVaultAdapter; + fileNameLookup?: FileNameLookup; private files = new Map(); @@ -583,6 +586,44 @@ describe("FileAccessBase", () => { expect(files).toContain(file2); }); + it("forwards file-name and candidate queries through the optional adapter capability", async () => { + const policy: PathComparisonSettings = { + pathNormalizationVersion: 1, + handleFilenameCaseSensitive: false, + }; + const lookup: FileNameLookup = { + getFileNames: vi.fn(async (options) => { + expect(options).toEqual({ fresh: true }); + return ["listed.md"] as FilePath[]; + }), + findPathIdentityCandidates: vi.fn(async () => ["listed.md"] as FilePath[]), + }; + adapter.fileNameLookup = lookup; + + await expect(fileAccess.getFileNames({ fresh: true })).resolves.toEqual(["listed.md"]); + await expect(fileAccess.findPathIdentityCandidates("listed.md" as FilePath, policy)).resolves.toEqual([ + "listed.md", + ]); + expect(lookup.getFileNames).toHaveBeenCalledWith({ fresh: true }); + expect(lookup.findPathIdentityCandidates).toHaveBeenCalledWith("listed.md", policy); + }); + + it("derives file names from the existing listing when the adapter has no name capability", async () => { + const file: MockFile = { + path: "fallback.md", + name: "fallback.md", + stat: { ctime: 0, mtime: 0, size: 1, type: "file" }, + content: "", + }; + adapter.setMockFile(file.path, file); + + await expect(fileAccess.getFileNames()).resolves.toEqual(["fallback.md"]); + expect(fileAccess.findPathIdentityCandidates("fallback.md" as FilePath, { + pathNormalizationVersion: 0, + handleFilenameCaseSensitive: true, + })).toBeUndefined(); + }); + it("should use case-insensitive search when storage is insensitive", async () => { const file: MockFile = { path: "CaseSensitive.md", diff --git a/src/serviceModules/Rebuilder.ts b/src/serviceModules/Rebuilder.ts index f8ecc525..efa22e59 100644 --- a/src/serviceModules/Rebuilder.ts +++ b/src/serviceModules/Rebuilder.ts @@ -272,7 +272,7 @@ Please enable them from the settings screen after setup is complete.`, await assertDatabasePathIdentity(this.database.localDatabase.localDatabase, settings); } if (getPathNormalizationVersion(settings) === 0) return; - const paths = await this.storageAccess.getFileNames(); + const paths = await this.storageAccess.getFileNames({ fresh: true }); const selected = []; const databaseReady = this.database.isDatabaseReady(); for (const path of paths) { diff --git a/src/serviceModules/Rebuilder.unit.spec.ts b/src/serviceModules/Rebuilder.unit.spec.ts index e17c7185..a2f1627a 100644 --- a/src/serviceModules/Rebuilder.unit.spec.ts +++ b/src/serviceModules/Rebuilder.unit.spec.ts @@ -480,6 +480,7 @@ describe("ServiceRebuilder NFC path preflight", () => { services.database.resetDatabaseForCurrentSettings.mockRejectedValueOnce(resetBoundary); await expect(rebuilder.rebuildEverything()).rejects.toBe(resetBoundary); expect(services.storageAccess.getFileNames).toHaveBeenCalledOnce(); + expect(services.storageAccess.getFileNames).toHaveBeenCalledWith({ fresh: true }); expect(services.database.resetDatabaseForCurrentSettings).toHaveBeenCalledOnce(); expect(services.replication.markLocked).not.toHaveBeenCalled(); }); diff --git a/src/serviceModules/ServiceFileAccessBase.ts b/src/serviceModules/ServiceFileAccessBase.ts index 9b2bbc54..73bee817 100644 --- a/src/serviceModules/ServiceFileAccessBase.ts +++ b/src/serviceModules/ServiceFileAccessBase.ts @@ -9,6 +9,8 @@ import type { UXFolderInfo, UXStat, } from "@lib/common/types"; +import type { FileNameReadOptions } from "@lib/platform/FilePathIndex.ts"; +import type { PathComparisonSettings } from "@lib/platform/pathTypes.ts"; import { ServiceModuleBase } from "@lib/serviceModules/ServiceModuleBase"; import type { APIService } from "@lib/services/base/APIService"; @@ -21,6 +23,7 @@ import type { VaultService } from "@lib/services/base/VaultService"; import type { SettingService } from "@lib/services/base/SettingService"; import type { FileAccessBase, ExtractFile, ExtractFolder } from "@lib/serviceModules/FileAccessBase"; import type { IFileSystemAdapter } from "@lib/serviceModules/adapters"; +import { createFallbackFileNameLookup, type FallbackFileNameLookup } from "./ServiceFileAccessBase/fileNames.ts"; // eslint-disable-next-line @typescript-eslint/no-explicit-any -- For type extraction. export interface StorageAccessBaseDependencies> { API: APIService; @@ -32,6 +35,7 @@ export interface StorageAccessBaseDependencies; } + // eslint-disable-next-line @typescript-eslint/no-explicit-any -- For type extraction. export class ServiceFileAccessBase> extends ServiceModuleBase> @@ -41,6 +45,7 @@ export class ServiceFileAccessBase) { super(services); @@ -49,6 +54,10 @@ export class ServiceFileAccessBase this.getFileNames(), + getStorageFileEventCount: () => services.fileProcessing.totalStorageFileEventCount, + }); services.appLifecycle.onFirstInitialise.addHandler(this._everyOnFirstInitialize.bind(this)); services.fileProcessing.commitPendingFileEvents.addHandler(this._everyCommitPendingFileEvent.bind(this)); services.appLifecycle.onBeforeUnload.addHandler(async () => { @@ -279,9 +288,20 @@ export class ServiceFileAccessBase this.vaultAccess.nativeFileToUXFileInfoStub(f)); } - async getFileNames(): Promise { - const files = await this.vaultAccess.getFiles(); - return files.map((f) => f.path as FilePath); + async getFileNames(options?: FileNameReadOptions): Promise { + if (options?.fresh) { + this.fallbackFileNames.invalidate(); + } + return await this.vaultAccess.getFileNames(options); + } + + async findPathIdentityCandidates(path: FilePath, policy: PathComparisonSettings): Promise { + const indexedCandidates = this.vaultAccess.findPathIdentityCandidates(path, policy); + if (indexedCandidates) { + return await indexedCandidates; + } + + return await this.fallbackFileNames.findPathIdentityCandidates(path, policy); } async getFilesIncludeHidden( diff --git a/src/serviceModules/ServiceFileAccessBase.unit.spec.ts b/src/serviceModules/ServiceFileAccessBase.unit.spec.ts index 487c2904..8eb3a164 100644 --- a/src/serviceModules/ServiceFileAccessBase.unit.spec.ts +++ b/src/serviceModules/ServiceFileAccessBase.unit.spec.ts @@ -1,6 +1,7 @@ import { describe, expect, it, vi } from "vitest"; import { ServiceFileAccessBase } from "./ServiceFileAccessBase"; import type { FilePath, FilePathWithPrefix } from "@lib/common/types"; +import type { PathComparisonSettings } from "@lib/platform/pathTypes.ts"; type MockFolder = { kind: "folder"; @@ -257,3 +258,116 @@ describe("ServiceFileAccessBase local completion lifecycle", () => { await expect(getBeforeUnload()!()).rejects.toThrow("Snapshot unavailable"); }); }); + +describe("ServiceFileAccessBase file-name lookup", () => { + function createFileNameService( + getFileNames: (options?: { fresh?: boolean }) => Promise, + indexedLookup?: (path: FilePath, policy: PathComparisonSettings) => Promise | undefined + ) { + const fileProcessing = { + totalStorageFileEventCount: 0, + commitPendingFileEvents: { addHandler: vi.fn() }, + }; + const vaultAccess = { + getFileNames, + findPathIdentityCandidates: indexedLookup ?? (() => undefined), + }; + const service = new ServiceFileAccessBase({ + API: { addLog: vi.fn() } as any, + appLifecycle: { + onFirstInitialise: { addHandler: vi.fn() }, + onBeforeUnload: { addHandler: vi.fn() }, + } as any, + fileProcessing: fileProcessing as any, + vault: {} as any, + setting: {} as any, + storageEventManager: {} as any, + storageAccessManager: {} as any, + vaultAccess: vaultAccess as any, + }); + return { service, fileProcessing, vaultAccess }; + } + + const caseInsensitivePolicy = { pathNormalizationVersion: 0 as const, handleFilenameCaseSensitive: false }; + + it("forwards candidate queries when the adapter supplies a lookup", async () => { + const candidates = ["A.md"] as FilePath[]; + const indexedLookup = vi.fn(async () => candidates); + const getFileNames = vi.fn(async () => [] as FilePath[]); + const { service } = createFileNameService(getFileNames, indexedLookup); + + await expect(service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy)).resolves.toEqual( + candidates + ); + expect(indexedLookup).toHaveBeenCalledWith("a.md", caseInsensitivePolicy); + expect(getFileNames).not.toHaveBeenCalled(); + }); + + it("caches fallback candidates by event count and effective comparison policy", async () => { + const names = ["A.md"] as FilePath[]; + const getFileNames = vi.fn(async () => [...names]); + const { service, fileProcessing } = createFileNameService(getFileNames); + + await expect(service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy)).resolves.toEqual([ + "A.md", + ]); + await service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy); + expect(getFileNames).toHaveBeenCalledOnce(); + + names.push("a.md" as FilePath); + await expect(service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy)).resolves.toEqual([ + "A.md", + ]); + fileProcessing.totalStorageFileEventCount++; + await expect(service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy)).resolves.toEqual([ + "A.md", + "a.md", + ]); + expect(getFileNames).toHaveBeenCalledTimes(2); + }); + + it("coalesces concurrent fallback reads with the same cache key", async () => { + let resolveNames!: (paths: FilePath[]) => void; + const pendingNames = new Promise((resolve) => { + resolveNames = resolve; + }); + const getFileNames = vi.fn(() => pendingNames); + const { service } = createFileNameService(getFileNames); + + const first = service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy); + const second = service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy); + expect(getFileNames).toHaveBeenCalledOnce(); + resolveNames(["A.md"] as FilePath[]); + + await expect(Promise.all([first, second])).resolves.toEqual([["A.md"], ["A.md"]]); + }); + + it("does not publish an older in-flight fallback map after a fresh listing", async () => { + let resolveOldNames!: (paths: FilePath[]) => void; + const oldNames = new Promise((resolve) => { + resolveOldNames = resolve; + }); + let currentNames = ["A.md"] as FilePath[]; + let ordinaryReads = 0; + const getFileNames = vi.fn(async (options?: { fresh?: boolean }) => { + if (options?.fresh) { + return [...currentNames]; + } + ordinaryReads++; + return ordinaryReads === 1 ? await oldNames : [...currentNames]; + }); + const { service } = createFileNameService(getFileNames); + + const oldLookup = service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy); + currentNames = ["A.md", "a.md"] as FilePath[]; + await expect(service.getFileNames({ fresh: true })).resolves.toEqual(currentNames); + resolveOldNames(["A.md"] as FilePath[]); + await expect(oldLookup).resolves.toEqual(["A.md"]); + + await expect(service.findPathIdentityCandidates("a.md" as FilePath, caseInsensitivePolicy)).resolves.toEqual([ + "A.md", + "a.md", + ]); + expect(getFileNames).toHaveBeenCalledTimes(3); + }); +}); diff --git a/src/serviceModules/ServiceFileAccessBase/fileNames.ts b/src/serviceModules/ServiceFileAccessBase/fileNames.ts new file mode 100644 index 00000000..1d5b5ab6 --- /dev/null +++ b/src/serviceModules/ServiceFileAccessBase/fileNames.ts @@ -0,0 +1,122 @@ +import { promiseWithResolvers } from "octagonal-wheels/promises"; +import { FilePathIndex, type FileNameLookup } from "@lib/platform/FilePathIndex.ts"; +import type { FilePath, PathComparisonSettings } from "@lib/platform/pathTypes.ts"; + +/** The listing and invalidation inputs needed by a non-indexed storage host. */ +export interface FileNameLookupDependencies { + readonly getFileNames: () => Promise; + readonly getStorageFileEventCount: () => number; +} + +/** Values which make a retained name listing reusable for the active policy. */ +export interface FileNameIndexSnapshot { + readonly storageEventCount: number; + readonly policy: PathComparisonSettings; +} + +/** One shared pending or fulfilled listing; rejected requests are removed. */ +export interface FileNameIndexRequest extends FileNameIndexSnapshot { + readonly index: Promise; +} + +/** The factory owns one active request; operations receive that ownership explicitly. */ +export interface FallbackFileNameLookupState { + retained: FileNameIndexRequest | undefined; +} + +/** Private fallback view used by the storage facade when its host has no index. */ +export interface FallbackFileNameLookup extends Pick { + /** Retire the retained request before obtaining a fresh authoritative listing. */ + invalidate(): void; +} + +/** Compare the host observation count and identity-policy values which permit request reuse. */ +export function matchesSnapshot(request: FileNameIndexSnapshot, snapshot: FileNameIndexSnapshot): boolean { + return ( + request.storageEventCount === snapshot.storageEventCount && + request.policy.pathNormalizationVersion === snapshot.policy.pathNormalizationVersion && + request.policy.handleFilenameCaseSensitive === snapshot.policy.handleFilenameCaseSensitive + ); +} + +/** Build an index from the host listing without retaining or publishing it. */ +export async function createFilePathIndex( + dependencies: Pick +): Promise { + const paths = await dependencies.getFileNames(); + const index = new FilePathIndex(); + index.replaceAll(paths); + return index; +} + +/** Retire reuse immediately; existing callers can still finish their own request. */ +export function invalidateFileNameLookup(state: FallbackFileNameLookupState): void { + state.retained = undefined; +} + +/** An older rejected request must not evict a newer active listing. */ +export function discardRejectedRequest(state: FallbackFileNameLookupState, request: FileNameIndexRequest): void { + if (state.retained === request) { + invalidateFileNameLookup(state); + } +} + +/** + * Reuse or start the request matching this snapshot, preserving its promise identity. + * + * Publish a pending request before starting host code: that code can invalidate + * or re-enter this lookup synchronously. Completion belongs to the captured + * request and cannot replace whichever request is active by then. + */ +export function getIndex( + dependencies: Pick, + state: FallbackFileNameLookupState, + snapshot: FileNameIndexSnapshot +): Promise { + if (state.retained && matchesSnapshot(state.retained, snapshot)) { + return state.retained.index; + } + + const pending = promiseWithResolvers(); + const request: FileNameIndexRequest = { ...snapshot, index: pending.promise }; + state.retained = request; + void request.index.catch(() => discardRejectedRequest(state, request)); + void createFilePathIndex(dependencies).then(pending.resolve, pending.reject); + return request.index; +} + +/** Capture the host observation and policy before awaiting the matching original-name candidates. */ +export async function findPathIdentityCandidates( + dependencies: FileNameLookupDependencies, + state: FallbackFileNameLookupState, + path: FilePath, + policy: PathComparisonSettings +): Promise { + const snapshot: FileNameIndexSnapshot = { + storageEventCount: dependencies.getStorageFileEventCount(), + policy: { + pathNormalizationVersion: policy.pathNormalizationVersion, + handleFilenameCaseSensitive: policy.handleFilenameCaseSensitive, + }, + }; + const index = await getIndex(dependencies, state, snapshot); + return index.findPathIdentityCandidates(path, snapshot.policy); +} + +/** + * Retain and share the active host listing until its event count or policy changes. + * + * @param dependencies - Narrow host callbacks, resolved when a query runs. + * @returns A per-service fallback lookup with explicit fresh-read invalidation. + * @remarks + * The factory owns only the retained request state and delegates to standalone + * operations. Retiring a request fences older work: it can finish for existing + * callers without publishing over a newer request. Failed reads can be retried. + */ +export function createFallbackFileNameLookup(dependencies: FileNameLookupDependencies): FallbackFileNameLookup { + const state: FallbackFileNameLookupState = { retained: undefined }; + return { + invalidate: () => invalidateFileNameLookup(state), + findPathIdentityCandidates: (path, policy) => findPathIdentityCandidates(dependencies, state, path, policy), + }; +} diff --git a/src/serviceModules/ServiceFileAccessBase/fileNames.unit.spec.ts b/src/serviceModules/ServiceFileAccessBase/fileNames.unit.spec.ts new file mode 100644 index 00000000..5a74ec03 --- /dev/null +++ b/src/serviceModules/ServiceFileAccessBase/fileNames.unit.spec.ts @@ -0,0 +1,244 @@ +import { describe, expect, it, vi } from "vitest"; +import { parseFilePath } from "@lib/platform/pathComparison.ts"; +import type { FilePath, PathComparisonSettings } from "@lib/platform/pathTypes.ts"; +import { + createFallbackFileNameLookup, + findPathIdentityCandidates, + getIndex, + invalidateFileNameLookup, + type FallbackFileNameLookupState, +} from "./fileNames.ts"; + +const insensitive: PathComparisonSettings = { pathNormalizationVersion: 0, handleFilenameCaseSensitive: false }; + +function deferredNames() { + let resolve!: (paths: FilePath[]) => void; + let reject!: (error: Error) => void; + const promise = new Promise((accept, fail) => { + resolve = accept; + reject = fail; + }); + return { promise, resolve, reject }; +} + +function names(...paths: string[]): FilePath[] { + return paths.map(parseFilePath); +} + +describe("non-indexed host file-name lookup", () => { + it("shares a pending listing and returns every matching original spelling", async () => { + const read = deferredNames(); + const getFileNames = vi.fn(() => read.promise); + const lookup = createFallbackFileNameLookup({ getFileNames, getStorageFileEventCount: () => 0 }); + + const first = lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive); + const second = lookup.findPathIdentityCandidates(parseFilePath("A.md"), insensitive); + expect(getFileNames).toHaveBeenCalledOnce(); + read.resolve(names("a.md", "A.md")); + await expect(first).resolves.toEqual(["A.md", "a.md"]); + await expect(second).resolves.toEqual(["A.md", "a.md"]); + }); + + it("retires a request invalidated while its host listing starts", async () => { + const getFileNames = vi.fn(async () => { + if (getFileNames.mock.calls.length === 1) { + lookup.invalidate(); + return names("A.md"); + } + return names("A.md", "a.md"); + }); + const lookup = createFallbackFileNameLookup({ getFileNames, getStorageFileEventCount: () => 0 }); + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).resolves.toEqual(["A.md"]); + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).resolves.toEqual([ + "A.md", + "a.md", + ]); + expect(getFileNames).toHaveBeenCalledTimes(2); + }); + + it("keeps a newer request when an invalidated older listing finishes", async () => { + const oldRead = deferredNames(); + const getFileNames = vi + .fn() + .mockImplementationOnce(() => oldRead.promise) + .mockResolvedValue(names("A.md", "a.md")); + const lookup = createFallbackFileNameLookup({ getFileNames, getStorageFileEventCount: () => 0 }); + const old = lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive); + + lookup.invalidate(); + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).resolves.toEqual([ + "A.md", + "a.md", + ]); + oldRead.resolve(names("A.md")); + await expect(old).resolves.toEqual(["A.md"]); + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).resolves.toEqual([ + "A.md", + "a.md", + ]); + expect(getFileNames).toHaveBeenCalledTimes(2); + }); + + it("retries a failed listing without evicting a newer request on an older failure", async () => { + const oldRead = deferredNames(); + const getFileNames = vi + .fn() + .mockRejectedValueOnce(new Error("initial read failed")) + .mockImplementationOnce(() => oldRead.promise) + .mockResolvedValue(names("A.md", "a.md")); + const lookup = createFallbackFileNameLookup({ getFileNames, getStorageFileEventCount: () => 0 }); + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).rejects.toThrow( + "initial read failed" + ); + const old = lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive); + const rejectedOld = expect(old).rejects.toThrow("older read failed"); + + lookup.invalidate(); + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).resolves.toEqual([ + "A.md", + "a.md", + ]); + oldRead.reject(new Error("older read failed")); + await rejectedOld; + await expect(lookup.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).resolves.toEqual([ + "A.md", + "a.md", + ]); + expect(getFileNames).toHaveBeenCalledTimes(3); + }); + + it("reads again when the active comparison policy or storage event count changes", async () => { + let eventCount = 0; + const getFileNames = vi.fn(async () => names("cafe\u0301.md", "café.md")); + const lookup = createFallbackFileNameLookup({ getFileNames, getStorageFileEventCount: () => eventCount }); + const legacy = { pathNormalizationVersion: 0, handleFilenameCaseSensitive: true } as const; + const nfc = { pathNormalizationVersion: 1, handleFilenameCaseSensitive: true } as const; + + await expect(lookup.findPathIdentityCandidates(parseFilePath("café.md"), legacy)).resolves.toEqual(["café.md"]); + await lookup.findPathIdentityCandidates(parseFilePath("café.md"), legacy); + expect(getFileNames).toHaveBeenCalledOnce(); + await expect(lookup.findPathIdentityCandidates(parseFilePath("café.md"), nfc)).resolves.toEqual([ + "cafe\u0301.md", + "café.md", + ]); + expect(getFileNames).toHaveBeenCalledTimes(2); + eventCount++; + await lookup.findPathIdentityCandidates(parseFilePath("café.md"), nfc); + expect(getFileNames).toHaveBeenCalledTimes(3); + }); + + it("keeps listings independent between service instances", async () => { + const first = createFallbackFileNameLookup({ + getFileNames: async () => names("first.md"), + getStorageFileEventCount: () => 0, + }); + const second = createFallbackFileNameLookup({ + getFileNames: async () => names("second.md"), + getStorageFileEventCount: () => 0, + }); + await expect(first.findPathIdentityCandidates(parseFilePath("first.md"), insensitive)).resolves.toEqual([ + "first.md", + ]); + await expect(second.findPathIdentityCandidates(parseFilePath("first.md"), insensitive)).resolves.toEqual([]); + first.invalidate(); + await expect(second.findPathIdentityCandidates(parseFilePath("second.md"), insensitive)).resolves.toEqual([ + "second.md", + ]); + }); +}); + +describe("standalone fallback lookup operations", () => { + it("shares the same pending index promise using only the host listing port", async () => { + const read = deferredNames(); + const getFileNames = vi.fn(() => read.promise); + const state: FallbackFileNameLookupState = { retained: undefined }; + const snapshot = { storageEventCount: 0, policy: insensitive }; + + const first = getIndex({ getFileNames }, state, snapshot); + const second = getIndex({ getFileNames }, state, snapshot); + + expect(first).toBe(second); + expect(getFileNames).toHaveBeenCalledOnce(); + read.resolve(names("a.md", "A.md")); + const index = await first; + expect(index.findPathIdentityCandidates(parseFilePath("a.md"), insensitive)).toEqual(["A.md", "a.md"]); + expect(state.retained?.index).toBe(first); + }); + + it("publishes the request before a host callback can invalidate it", async () => { + const state: FallbackFileNameLookupState = { retained: undefined }; + let publishedBeforeHostRead = false; + const getFileNames = vi.fn(() => { + publishedBeforeHostRead = state.retained !== undefined; + invalidateFileNameLookup(state); + return Promise.resolve(names("old.md")); + }); + + const index = await getIndex({ getFileNames }, state, { storageEventCount: 0, policy: insensitive }); + + expect(publishedBeforeHostRead).toBe(true); + expect(state.retained).toBeUndefined(); + expect(index.getFileNames()).toEqual(["old.md"]); + }); + + it("does not let an invalidated older rejection retire a newer index request", async () => { + const oldRead = deferredNames(); + const getFileNames = vi + .fn() + .mockImplementationOnce(() => oldRead.promise) + .mockResolvedValue(names("A.md", "a.md")); + const state: FallbackFileNameLookupState = { retained: undefined }; + const snapshot = { storageEventCount: 0, policy: insensitive }; + const old = getIndex({ getFileNames }, state, snapshot); + const oldRejection = expect(old).rejects.toThrow("retired read failed"); + + invalidateFileNameLookup(state); + const current = getIndex({ getFileNames }, state, snapshot); + oldRead.reject(new Error("retired read failed")); + await oldRejection; + await current; + + expect(getIndex({ getFileNames }, state, snapshot)).toBe(current); + expect(getFileNames).toHaveBeenCalledTimes(2); + }); + + it("retires a rejected active request so the next caller can retry", async () => { + const getFileNames = vi + .fn() + .mockRejectedValueOnce(new Error("active read failed")) + .mockResolvedValue(names("retry.md")); + const state: FallbackFileNameLookupState = { retained: undefined }; + const snapshot = { storageEventCount: 0, policy: insensitive }; + + await expect(getIndex({ getFileNames }, state, snapshot)).rejects.toThrow("active read failed"); + expect(state.retained).toBeUndefined(); + const index = await getIndex({ getFileNames }, state, snapshot); + + expect(index.getFileNames()).toEqual(["retry.md"]); + expect(getFileNames).toHaveBeenCalledTimes(2); + }); + + it("captures policy values before awaiting names and rereads after a new observation", async () => { + const read = deferredNames(); + const getFileNames = vi + .fn() + .mockImplementationOnce(() => read.promise) + .mockResolvedValue(names("A.md", "a.md")); + let storageEventCount = 0; + const dependencies = { getFileNames, getStorageFileEventCount: () => storageEventCount }; + const state: FallbackFileNameLookupState = { retained: undefined }; + const policy = { ...insensitive }; + + const pending = findPathIdentityCandidates(dependencies, state, parseFilePath("a.md"), policy); + policy.handleFilenameCaseSensitive = true; + read.resolve(names("A.md", "a.md")); + await expect(pending).resolves.toEqual(["A.md", "a.md"]); + await expect(findPathIdentityCandidates(dependencies, state, parseFilePath("a.md"), policy)).resolves.toEqual([ + "a.md", + ]); + storageEventCount++; + await findPathIdentityCandidates(dependencies, state, parseFilePath("a.md"), policy); + + expect(getFileNames).toHaveBeenCalledTimes(3); + }); +}); diff --git a/src/serviceModules/adapters/IFileSystemAdapter.ts b/src/serviceModules/adapters/IFileSystemAdapter.ts index e263054e..2e5f831a 100644 --- a/src/serviceModules/adapters/IFileSystemAdapter.ts +++ b/src/serviceModules/adapters/IFileSystemAdapter.ts @@ -4,6 +4,7 @@ import type { ITypeGuardAdapter } from "./ITypeGuardAdapter.ts"; import type { IConversionAdapter } from "./IConversionAdapter.ts"; import type { IStorageAdapter } from "./IStorageAdapter.ts"; import type { IVaultAdapter } from "./IVaultAdapter.ts"; +import type { FileNameLookup } from "@lib/platform/FilePathIndex.ts"; /** * Main file system adapter interface @@ -30,6 +31,9 @@ export interface IFileSystemAdapter< /** Storage operations */ readonly storage: IStorageAdapter; + /** Optional maintained file-name inventory and candidate lookup. */ + readonly fileNameLookup?: FileNameLookup; + /** Vault operations */ readonly vault: IVaultAdapter; diff --git a/src/storage.ts b/src/storage.ts index b8597321..be709684 100644 --- a/src/storage.ts +++ b/src/storage.ts @@ -13,6 +13,8 @@ export type { StoragePathResolver, StoragePathResolverOptions, } from "./platform/pathTypes.ts"; +export { FilePathIndex } from "./platform/FilePathIndex.ts"; +export type { FileNameLookup, FileNameReadOptions, FilePathDelta } from "./platform/FilePathIndex.ts"; export { parseFilePath, parseDocumentPath,