scrabble-solver 2.18.10-alpha.1 → 2.18.10-alpha.2

package/packages/dictionaries/build/lib/DiskCache.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiskCache = void 0;
+const gaddag_1 = require("@kamilmielnik/gaddag");
+const logger_1 = require("@scrabble-solver/logger");
+const fs_1 = __importDefault(require("fs"));
+const constants_1 = require("../constants");
+const getDictionaryFilepath_1 = require("./getDictionaryFilepath");
+class DiskCache {
+    constructor(directory = constants_1.OUTPUT_DIRECTORY) {
+        this.directory = directory;
+    }
+    /**
+     * Returns undefined when the cached file cannot be deserialized (it was
+     * written by an app version with an incompatible format, or it is corrupted)
+     * so that callers re-download and re-serialize the dictionary.
+     */
+    async get(locale) {
+        if (!this.has(locale)) {
+            return undefined;
+        }
+        const filepath = (0, getDictionaryFilepath_1.getDictionaryFilepath)(locale, this.directory);
+        try {
+            const serialized = await fs_1.default.promises.readFile(filepath);
+            return gaddag_1.Gaddag.deserialize(new Uint8Array(serialized.buffer, serialized.byteOffset, serialized.byteLength));
+        }
+        catch (error) {
+            (0, logger_1.logError)('cache', error, { level: 'warn', locale });
+            await fs_1.default.promises.rm(filepath, { force: true });
+            return undefined;
+        }
+    }
+    getLastModifiedTimestamp(locale) {
+        const filepath = (0, getDictionaryFilepath_1.getDictionaryFilepath)(locale, this.directory);
+        if (!fs_1.default.existsSync(filepath)) {
+            return undefined;
+        }
+        const stats = fs_1.default.statSync(filepath);
+        return stats.mtimeMs;
+    }
+    has(locale) {
+        const filepath = (0, getDictionaryFilepath_1.getDictionaryFilepath)(locale, this.directory);
+        return fs_1.default.existsSync(filepath);
+    }
+    isStale(locale) {
+        if (!this.has(locale)) {
+            return undefined;
+        }
+        const lastModifiedTimestamp = this.getLastModifiedTimestamp(locale);
+        if (typeof lastModifiedTimestamp === 'undefined') {
+            return undefined;
+        }
+        const timeSinceModification = Math.abs(lastModifiedTimestamp - Date.now());
+        return timeSinceModification > constants_1.CACHE_STALE_THRESHOLD;
+    }
+    async set(locale, gaddag) {
+        const filepath = (0, getDictionaryFilepath_1.getDictionaryFilepath)(locale, this.directory);
+        await fs_1.default.promises.writeFile(filepath, gaddag.serialize());
+    }
+}
+exports.DiskCache = DiskCache;

package/packages/dictionaries/build/lib/LayeredCache.d.ts

@@ -0,0 +1,12 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { type Locale } from '@scrabble-solver/types';
+import type { Cache } from '../types';
+export declare class LayeredCache implements Cache<Locale, Gaddag> {
+    private readonly layers;
+    get(locale: Locale): Promise<Gaddag | undefined>;
+    getLastModifiedTimestamp(locale: Locale): number | undefined;
+    has(locale: Locale): boolean;
+    isStale(locale: Locale): boolean | undefined;
+    set(locale: Locale, gaddag: Gaddag): Promise<void>;
+    private getLastModifiedLayer;
+}

package/packages/dictionaries/build/lib/LayeredCache.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LayeredCache = void 0;
+const createCacheTimestampComparator_1 = require("./createCacheTimestampComparator");
+const DiskCache_1 = require("./DiskCache");
+const MemoryCache_1 = require("./MemoryCache");
+class LayeredCache {
+    constructor() {
+        this.layers = [new MemoryCache_1.MemoryCache(), new DiskCache_1.DiskCache()];
+    }
+    async get(locale) {
+        const cache = this.getLastModifiedLayer(locale);
+        if (!cache) {
+            return Promise.resolve(undefined);
+        }
+        const [memoryCache, diskCache] = this.layers;
+        const value = await cache.get(locale);
+        if (cache === diskCache && typeof value !== 'undefined') {
+            await memoryCache.set(locale, value);
+        }
+        return value;
+    }
+    getLastModifiedTimestamp(locale) {
+        const cache = this.getLastModifiedLayer(locale);
+        if (!cache) {
+            return undefined;
+        }
+        return cache.getLastModifiedTimestamp(locale);
+    }
+    has(locale) {
+        return this.layers.some((cache) => cache.has(locale));
+    }
+    isStale(locale) {
+        if (this.layers.some((cache) => cache.isStale(locale))) {
+            return true;
+        }
+        if (this.layers.every((cache) => typeof cache.isStale(locale) === 'undefined')) {
+            return undefined;
+        }
+        return false;
+    }
+    async set(locale, gaddag) {
+        const [memoryCache, diskCache] = this.layers;
+        await diskCache.set(locale, gaddag);
+        await memoryCache.set(locale, gaddag);
+    }
+    getLastModifiedLayer(locale) {
+        const layers = this.layers.filter((cache) => cache.has(locale));
+        const [cached] = [...layers].sort((0, createCacheTimestampComparator_1.createCacheTimestampComparator)(locale));
+        return cached;
+    }
+}
+exports.LayeredCache = LayeredCache;

package/packages/dictionaries/build/lib/MemoryCache.d.ts

@@ -0,0 +1,12 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { type Locale } from '@scrabble-solver/types';
+import type { Cache } from '../types';
+export declare class MemoryCache implements Cache<Locale, Gaddag> {
+    private readonly cache;
+    private readonly cacheTimestamps;
+    get(locale: Locale): Promise<Gaddag | undefined>;
+    getLastModifiedTimestamp(locale: Locale): number | undefined;
+    has(locale: Locale): boolean;
+    isStale(locale: Locale): boolean | undefined;
+    set(locale: Locale, gaddag: Gaddag): Promise<void>;
+}

package/packages/dictionaries/build/lib/MemoryCache.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = void 0;
+const constants_1 = require("../constants");
+class MemoryCache {
+    constructor() {
+        this.cache = {};
+        this.cacheTimestamps = {};
+    }
+    get(locale) {
+        return Promise.resolve(this.cache[locale]);
+    }
+    getLastModifiedTimestamp(locale) {
+        return this.cacheTimestamps[locale];
+    }
+    has(locale) {
+        return typeof this.cache[locale] !== 'undefined';
+    }
+    isStale(locale) {
+        const timestamp = this.getLastModifiedTimestamp(locale);
+        if (!this.has(locale) || typeof timestamp === 'undefined') {
+            return undefined;
+        }
+        const timeSinceModification = Math.abs(timestamp - Date.now());
+        return timeSinceModification > constants_1.CACHE_STALE_THRESHOLD;
+    }
+    set(locale, gaddag) {
+        this.cacheTimestamps[locale] = Date.now();
+        this.cache[locale] = gaddag;
+        return Promise.resolve();
+    }
+}
+exports.MemoryCache = MemoryCache;

package/packages/dictionaries/build/lib/createAsyncProxy.d.ts

@@ -0,0 +1,3 @@
+type AsyncCallback<T> = () => Promise<T>;
+export declare const createAsyncProxy: <T>(asyncCallback: AsyncCallback<T>) => AsyncCallback<T>;
+export {};

package/packages/dictionaries/build/lib/createAsyncProxy.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAsyncProxy = void 0;
+const createAsyncProxy = (asyncCallback) => {
+    let promise = null;
+    return async () => {
+        if (promise) {
+            return promise;
+        }
+        try {
+            promise = asyncCallback();
+            return await promise;
+        }
+        finally {
+            promise = null;
+        }
+    };
+};
+exports.createAsyncProxy = createAsyncProxy;

package/packages/dictionaries/build/lib/createCacheTimestampComparator.d.ts

@@ -0,0 +1,4 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { type Locale } from '@scrabble-solver/types';
+import type { Cache } from '../types';
+export declare const createCacheTimestampComparator: (locale: Locale) => (a: Cache<Locale, Gaddag>, b: Cache<Locale, Gaddag>) => number;

package/packages/dictionaries/build/lib/createCacheTimestampComparator.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCacheTimestampComparator = void 0;
+const createCacheTimestampComparator = (locale) => {
+    return (a, b) => {
+        const aTimestamp = a.getLastModifiedTimestamp(locale);
+        const bTimestamp = b.getLastModifiedTimestamp(locale);
+        if (aTimestamp === bTimestamp) {
+            return 0;
+        }
+        if (typeof aTimestamp === 'undefined') {
+            return 1;
+        }
+        if (typeof bTimestamp === 'undefined') {
+            return -1;
+        }
+        return bTimestamp - aTimestamp;
+    };
+};
+exports.createCacheTimestampComparator = createCacheTimestampComparator;

package/packages/dictionaries/build/lib/downloadDictionary.d.ts

@@ -0,0 +1,3 @@
+import { Gaddag } from '@kamilmielnik/gaddag';
+import { type Locale } from '@scrabble-solver/types';
+export declare function downloadDictionary(locale: Locale): Promise<Gaddag>;

package/packages/dictionaries/build/lib/downloadDictionary.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadDictionary = downloadDictionary;
+const gaddag_1 = require("@kamilmielnik/gaddag");
+const logger_1 = require("@scrabble-solver/logger");
+const word_lists_1 = require("@scrabble-solver/word-lists");
+async function downloadDictionary(locale) {
+    const downloadStartedAt = performance.now();
+    const words = await (0, word_lists_1.getWordList)(locale);
+    const buildStartedAt = performance.now();
+    const gaddag = gaddag_1.Gaddag.fromArray(words);
+    (0, logger_1.logEvent)({
+        type: 'build',
+        locale,
+        words: words.length,
+        download_ms: Math.round(buildStartedAt - downloadStartedAt),
+        build_ms: Math.round(performance.now() - buildStartedAt),
+    });
+    return gaddag;
+}

package/packages/dictionaries/build/lib/getDictionaryFilepath.d.ts

@@ -0,0 +1,2 @@
+import { type Locale } from '@scrabble-solver/types';
+export declare const getDictionaryFilepath: (locale: Locale, directory?: string) => string;

package/packages/dictionaries/build/lib/getDictionaryFilepath.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDictionaryFilepath = void 0;
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("../constants");
+const getDictionaryFilepath = (locale, directory = constants_1.OUTPUT_DIRECTORY) => {
+    return path_1.default.resolve(directory, `${locale}.gaddag`);
+};
+exports.getDictionaryFilepath = getDictionaryFilepath;

package/packages/dictionaries/build/lib/index.d.ts

@@ -0,0 +1,7 @@
+export { createAsyncProxy } from './createAsyncProxy';
+export { createCacheTimestampComparator } from './createCacheTimestampComparator';
+export { DiskCache } from './DiskCache';
+export { downloadDictionary } from './downloadDictionary';
+export { getDictionaryFilepath } from './getDictionaryFilepath';
+export { LayeredCache } from './LayeredCache';
+export { MemoryCache } from './MemoryCache';

package/packages/dictionaries/build/lib/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = exports.LayeredCache = exports.getDictionaryFilepath = exports.downloadDictionary = exports.DiskCache = exports.createCacheTimestampComparator = exports.createAsyncProxy = void 0;
+var createAsyncProxy_1 = require("./createAsyncProxy");
+Object.defineProperty(exports, "createAsyncProxy", { enumerable: true, get: function () { return createAsyncProxy_1.createAsyncProxy; } });
+var createCacheTimestampComparator_1 = require("./createCacheTimestampComparator");
+Object.defineProperty(exports, "createCacheTimestampComparator", { enumerable: true, get: function () { return createCacheTimestampComparator_1.createCacheTimestampComparator; } });
+var DiskCache_1 = require("./DiskCache");
+Object.defineProperty(exports, "DiskCache", { enumerable: true, get: function () { return DiskCache_1.DiskCache; } });
+var downloadDictionary_1 = require("./downloadDictionary");
+Object.defineProperty(exports, "downloadDictionary", { enumerable: true, get: function () { return downloadDictionary_1.downloadDictionary; } });
+var getDictionaryFilepath_1 = require("./getDictionaryFilepath");
+Object.defineProperty(exports, "getDictionaryFilepath", { enumerable: true, get: function () { return getDictionaryFilepath_1.getDictionaryFilepath; } });
+var LayeredCache_1 = require("./LayeredCache");
+Object.defineProperty(exports, "LayeredCache", { enumerable: true, get: function () { return LayeredCache_1.LayeredCache; } });
+var MemoryCache_1 = require("./MemoryCache");
+Object.defineProperty(exports, "MemoryCache", { enumerable: true, get: function () { return MemoryCache_1.MemoryCache; } });

package/packages/dictionaries/build/types.d.ts

@@ -0,0 +1,7 @@
+export interface Cache<Key extends string, Value> {
+    get(key: Key): Promise<Value | undefined>;
+    getLastModifiedTimestamp(key: Key): number | undefined;
+    has(key: Key): boolean;
+    isStale(key: Key): boolean | undefined;
+    set(key: Key, value: Value): Promise<void>;
+}

package/packages/dictionaries/build/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/packages/dictionaries/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@scrabble-solver/dictionaries",
+  "version": "2.18.10-alpha.2",
+  "description": "Dictionary manager for Scrabble Solver: downloads per-locale word lists and serves them as GADDAG automata with layered disk/memory caching.",
+  "keywords": [
+    "scrabble",
+    "dictionary",
+    "gaddag",
+    "word-list",
+    "cache"
+  ],
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "bin": {
+    "remove-dictionaries": "bin/remove-dictionaries.js",
+    "update-dictionaries": "bin/update-dictionaries.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamilmielnik/scrabble-solver.git"
+  },
+  "author": {
+    "name": "Kamil Mielnik",
+    "email": "kamil@kamilmielnik.com",
+    "url": "https://kamilmielnik.com"
+  },
+  "license": "CC-BY-NC-ND-4.0",
+  "bugs": {
+    "url": "https://github.com/kamilmielnik/scrabble-solver/issues"
+  },
+  "homepage": "https://scrabble-solver.org",
+  "scripts": {
+    "build": "tsc --project .",
+    "clean": "rimraf build/",
+    "clean:dictionaries": "node ./bin/remove-dictionaries.js",
+    "postbuild": "node ./bin/update-dictionaries.js",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@kamilmielnik/gaddag": "3.0.0",
+    "@scrabble-solver/logger": "2.18.10-alpha.2",
+    "@scrabble-solver/types": "2.18.10-alpha.2",
+    "@scrabble-solver/word-lists": "2.18.10-alpha.2"
+  },
+  "gitHead": "f029a11f306a01937ee99fc6365cb226b972dfed"
+}

package/packages/dictionaries/src/Dictionaries.ts

@@ -0,0 +1,65 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { logError } from '@scrabble-solver/logger';
+import { Locale } from '@scrabble-solver/types';
+import fs from 'fs';
+
+import { OUTPUT_DIRECTORY } from './constants';
+import { createAsyncProxy, downloadDictionary, LayeredCache } from './lib';
+import { type Cache } from './types';
+
+export class Dictionaries {
+  private readonly cache: Cache<Locale, Gaddag>;
+
+  private readonly downloadDictionaryProxies: Record<Locale, () => Promise<Gaddag>>;
+
+  constructor() {
+    this.cache = new LayeredCache();
+    this.downloadDictionaryProxies = Object.fromEntries(
+      Object.values(Locale).map((locale) => [locale, createAsyncProxy(() => downloadDictionary(locale))]),
+    ) as Record<Locale, () => Promise<Gaddag>>;
+  }
+
+  public async get(locale: Locale): Promise<Gaddag> {
+    if (this.cache.has(locale)) {
+      const gaddag = await this.cache.get(locale);
+
+      if (gaddag) {
+        return gaddag;
+      }
+    }
+
+    return this.updateDictionary(locale);
+  }
+
+  public remove(): void {
+    // @ts-expect-error incorrect @types/node? https://nodejs.org/docs/latest-v25.x/api/fs.html#fsrmdirsyncpath-options
+    fs.rmdirSync(OUTPUT_DIRECTORY, { recursive: true });
+  }
+
+  public async update(force?: boolean): Promise<Locale[]> {
+    const locales = force ? Object.values(Locale) : this.getLocalesToUpdate();
+    const outcomes = await Promise.allSettled(locales.map((locale) => this.updateDictionary(locale)));
+    const failedLocales: Locale[] = [];
+
+    outcomes.forEach((outcome, index) => {
+      if (outcome.status === 'rejected') {
+        logError('build', outcome.reason, { locale: locales[index] });
+        failedLocales.push(locales[index]);
+      }
+    });
+
+    return failedLocales;
+  }
+
+  private getLocalesToUpdate(): Locale[] {
+    return Object.values(Locale).filter((locale) => this.cache.isStale(locale) !== false);
+  }
+
+  private async updateDictionary(locale: Locale): Promise<Gaddag> {
+    fs.mkdirSync(OUTPUT_DIRECTORY, { recursive: true });
+    const downloadDictionaryProxy = this.downloadDictionaryProxies[locale];
+    const gaddag = await downloadDictionaryProxy();
+    await this.cache.set(locale, gaddag);
+    return gaddag;
+  }
+}

package/packages/dictionaries/src/constants.ts

@@ -0,0 +1,8 @@
+import os from 'os';
+import path from 'path';
+
+export const DAY = 24 * 60 * 60 * 1000;
+
+export const CACHE_STALE_THRESHOLD = 1 * DAY; // eslint-disable-line no-implicit-coercion
+
+export const OUTPUT_DIRECTORY = path.resolve(os.homedir(), '.scrabble-solver', 'dictionaries');

package/packages/dictionaries/src/index.ts

@@ -0,0 +1,5 @@
+import { Dictionaries } from './Dictionaries';
+
+export * from './lib';
+
+export const dictionaries = new Dictionaries();

package/packages/dictionaries/src/lib/DiskCache.test.ts

@@ -0,0 +1,75 @@
+import { Gaddag } from '@kamilmielnik/gaddag';
+import { Locale } from '@scrabble-solver/types';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { DiskCache } from './DiskCache';
+import { getDictionaryFilepath } from './getDictionaryFilepath';
+
+const LOCALE = Locale.EN_US;
+const WORDS = ['scrabble', 'solver', 'gaddag'];
+
+describe('DiskCache', () => {
+  let directory: string;
+  let cache: DiskCache;
+
+  beforeEach(() => {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'dictionaries-test-'));
+    cache = new DiskCache(directory);
+  });
+
+  afterEach(() => {
+    fs.rmSync(directory, { force: true, recursive: true });
+  });
+
+  it('misses when there is no file', async () => {
+    expect(cache.has(LOCALE)).toBe(false);
+    expect(await cache.get(LOCALE)).toBeUndefined();
+    expect(cache.isStale(LOCALE)).toBeUndefined();
+    expect(cache.getLastModifiedTimestamp(LOCALE)).toBeUndefined();
+  });
+
+  it('round-trips a dictionary', async () => {
+    await cache.set(LOCALE, Gaddag.fromArray(WORDS));
+
+    expect(cache.has(LOCALE)).toBe(true);
+    expect(cache.isStale(LOCALE)).toBe(false);
+
+    const gaddag = await cache.get(LOCALE);
+
+    for (const word of WORDS) {
+      expect(gaddag?.has(word)).toBe(true);
+    }
+
+    expect(gaddag?.has('trie')).toBe(false);
+  });
+
+  it('treats a file written in an incompatible format as a cache miss and removes it', async () => {
+    const filepath = getDictionaryFilepath(LOCALE, directory);
+    fs.writeFileSync(filepath, 'serialized trie from a previous app version');
+
+    expect(cache.has(LOCALE)).toBe(true);
+    expect(await cache.get(LOCALE)).toBeUndefined();
+    expect(cache.has(LOCALE)).toBe(false);
+  });
+
+  it('treats a corrupted (truncated) file as a cache miss and removes it', async () => {
+    const serialized = Gaddag.fromArray(WORDS).serialize();
+    const filepath = getDictionaryFilepath(LOCALE, directory);
+    fs.writeFileSync(filepath, serialized.subarray(0, 10));
+
+    expect(await cache.get(LOCALE)).toBeUndefined();
+    expect(cache.has(LOCALE)).toBe(false);
+  });
+
+  it('reports files older than the stale threshold as stale', async () => {
+    await cache.set(LOCALE, Gaddag.fromArray(WORDS));
+
+    const filepath = getDictionaryFilepath(LOCALE, directory);
+    const twoDaysAgo = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000);
+    fs.utimesSync(filepath, twoDaysAgo, twoDaysAgo);
+
+    expect(cache.isStale(LOCALE)).toBe(true);
+  });
+});

package/packages/dictionaries/src/lib/DiskCache.ts

@@ -0,0 +1,75 @@
+import { Gaddag } from '@kamilmielnik/gaddag';
+import { logError } from '@scrabble-solver/logger';
+import { type Locale } from '@scrabble-solver/types';
+import fs from 'fs';
+
+import { CACHE_STALE_THRESHOLD, OUTPUT_DIRECTORY } from '../constants';
+import type { Cache } from '../types';
+
+import { getDictionaryFilepath } from './getDictionaryFilepath';
+
+export class DiskCache implements Cache<Locale, Gaddag> {
+  private readonly directory: string;
+
+  constructor(directory: string = OUTPUT_DIRECTORY) {
+    this.directory = directory;
+  }
+
+  /**
+   * Returns undefined when the cached file cannot be deserialized (it was
+   * written by an app version with an incompatible format, or it is corrupted)
+   * so that callers re-download and re-serialize the dictionary.
+   */
+  public async get(locale: Locale): Promise<Gaddag | undefined> {
+    if (!this.has(locale)) {
+      return undefined;
+    }
+
+    const filepath = getDictionaryFilepath(locale, this.directory);
+
+    try {
+      const serialized = await fs.promises.readFile(filepath);
+      return Gaddag.deserialize(new Uint8Array(serialized.buffer, serialized.byteOffset, serialized.byteLength));
+    } catch (error) {
+      logError('cache', error, { level: 'warn', locale });
+      await fs.promises.rm(filepath, { force: true });
+      return undefined;
+    }
+  }
+
+  public getLastModifiedTimestamp(locale: Locale): number | undefined {
+    const filepath = getDictionaryFilepath(locale, this.directory);
+
+    if (!fs.existsSync(filepath)) {
+      return undefined;
+    }
+
+    const stats = fs.statSync(filepath);
+    return stats.mtimeMs;
+  }
+
+  public has(locale: Locale): boolean {
+    const filepath = getDictionaryFilepath(locale, this.directory);
+    return fs.existsSync(filepath);
+  }
+
+  public isStale(locale: Locale): boolean | undefined {
+    if (!this.has(locale)) {
+      return undefined;
+    }
+
+    const lastModifiedTimestamp = this.getLastModifiedTimestamp(locale);
+
+    if (typeof lastModifiedTimestamp === 'undefined') {
+      return undefined;
+    }
+
+    const timeSinceModification = Math.abs(lastModifiedTimestamp - Date.now());
+    return timeSinceModification > CACHE_STALE_THRESHOLD;
+  }
+
+  public async set(locale: Locale, gaddag: Gaddag): Promise<void> {
+    const filepath = getDictionaryFilepath(locale, this.directory);
+    await fs.promises.writeFile(filepath, gaddag.serialize());
+  }
+}

package/packages/dictionaries/src/lib/LayeredCache.ts

@@ -0,0 +1,67 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { type Locale } from '@scrabble-solver/types';
+
+import type { Cache } from '../types';
+
+import { createCacheTimestampComparator } from './createCacheTimestampComparator';
+import { DiskCache } from './DiskCache';
+import { MemoryCache } from './MemoryCache';
+
+export class LayeredCache implements Cache<Locale, Gaddag> {
+  private readonly layers = [new MemoryCache(), new DiskCache()];
+
+  public async get(locale: Locale): Promise<Gaddag | undefined> {
+    const cache = this.getLastModifiedLayer(locale);
+
+    if (!cache) {
+      return Promise.resolve(undefined);
+    }
+
+    const [memoryCache, diskCache] = this.layers;
+    const value = await cache.get(locale);
+
+    if (cache === diskCache && typeof value !== 'undefined') {
+      await memoryCache.set(locale, value);
+    }
+
+    return value;
+  }
+
+  public getLastModifiedTimestamp(locale: Locale): number | undefined {
+    const cache = this.getLastModifiedLayer(locale);
+
+    if (!cache) {
+      return undefined;
+    }
+
+    return cache.getLastModifiedTimestamp(locale);
+  }
+
+  public has(locale: Locale): boolean {
+    return this.layers.some((cache) => cache.has(locale));
+  }
+
+  public isStale(locale: Locale): boolean | undefined {
+    if (this.layers.some((cache) => cache.isStale(locale))) {
+      return true;
+    }
+
+    if (this.layers.every((cache) => typeof cache.isStale(locale) === 'undefined')) {
+      return undefined;
+    }
+
+    return false;
+  }
+
+  public async set(locale: Locale, gaddag: Gaddag): Promise<void> {
+    const [memoryCache, diskCache] = this.layers;
+    await diskCache.set(locale, gaddag);
+    await memoryCache.set(locale, gaddag);
+  }
+
+  private getLastModifiedLayer(locale: Locale): Cache<Locale, Gaddag> | undefined {
+    const layers = this.layers.filter((cache) => cache.has(locale));
+    const [cached] = [...layers].sort(createCacheTimestampComparator(locale));
+    return cached;
+  }
+}