nyc-restroom-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Ortiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# nyc-restroom-mcp
+
+Ask Claude "where's the nearest public bathroom?" and get a real answer.
+
+This is an [MCP](https://modelcontextprotocol.io) server, a small plugin that
+gives an AI assistant (like Claude Desktop or Claude Code) new abilities. This
+one lets it search New York City's official public restroom data, live from
+[NYC Open Data](https://opendata.cityofnewyork.us/). Once installed, you can
+ask things like:
+
+- "Find a public restroom near Union Square that's open right now."
+- "Which restrooms near me are wheelchair accessible?"
+- "Is the bathroom at Jaime Campiz Playground actually clean?" (it looks up
+  the latest NYC Parks inspection report)
+
+It adds two tools:
+
+| Tool                  | What it does                                                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `find_restrooms`      | Lists open public restrooms near a location, closest first, with hours, accessibility, and changing-station info.      |
+| `get_restroom_status` | Looks up one restroom by name or coordinates, including its most recent NYC Parks inspection rating, where one exists. |
+
+If you don't give it a location, it can detect yours automatically (details
+below). Everything is read-only: it only ever fetches public city data.
+
+## Install
+
+You need [Node.js](https://nodejs.org) 20 or newer. No download or setup
+beyond the snippet for your app.
+
+**Claude Code** (one command):
+
+```bash
+claude mcp add nyc-restroom -- npx -y nyc-restroom-mcp
+```
+
+**Claude Desktop**: go to Settings -> Developer -> Edit Config and add this to
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nyc-restroom": {
+      "command": "npx",
+      "args": ["-y", "nyc-restroom-mcp"]
+    }
+  }
+}
+```
+
+Any other MCP client works the same way: have it launch
+`npx -y nyc-restroom-mcp` as a local (stdio) server.
+
+## Good to know
+
+- **Automatic location.** If you ask for nearby restrooms without saying
+  where you are, the server tries to figure it out: first from your device
+  (macOS only, if you `brew install corelocationcli` and grant it Location
+  Services access), otherwise a rough guess from your IP address. If neither
+  works, or you're outside NYC, it simply asks for explicit coordinates
+  instead of guessing wrong.
+- **Privacy.** Location detection only happens when you omit coordinates,
+  and your location is never written to logs. Pass explicit coordinates and
+  no location lookup happens at all.
+- **Live data.** Every answer comes straight from NYC Open Data (with a
+  short-lived in-memory cache), so results are as current as the city's own
+  records. Inspection reports only exist for restrooms run by NYC Parks;
+  library and other restrooms will honestly say no inspection data exists.
+- **More detail.** The [docs/](docs/) directory covers the full
+  [tool reference](docs/tools.md), [location detection](docs/location.md),
+  [data sources](docs/data-sources.md), [configuration](docs/configuration.md),
+  and [security model](docs/security.md). The reasoning behind every design
+  decision lives in [DECISIONS.md](DECISIONS.md).
+
+### Optional settings
+
+Set these as environment variables if you need them (most people don't):
+
+| Variable            | Purpose                                                              |
+| ------------------- | -------------------------------------------------------------------- |
+| `SOCRATA_APP_TOKEN` | A free NYC Open Data app token, for higher rate limits.              |
+| `LOG_LEVEL`         | `error`, `warn`, or `info` (default `info`). Logs go to stderr only. |
+
+A few more exist for testing and advanced setups; see
+[docs/configuration.md](docs/configuration.md).
+
+## Contributing
+
+Issues and pull requests are welcome at
+[DanielOrtiz0220/nyc-restroom-mcp](https://github.com/DanielOrtiz0220/nyc-restroom-mcp).
+
+Development uses [Bun](https://bun.sh) (1.1+):
+
+```bash
+git clone https://github.com/DanielOrtiz0220/nyc-restroom-mcp.git
+cd nyc-restroom-mcp
+bun install
+bun test            # full unit + end-to-end suite, runs completely offline
+bun run typecheck   # tsc --noEmit
+bun run lint        # eslint, zero warnings allowed
+bun run build       # compile src/ to dist/ (what the npm package ships)
+```
+
+To run your local copy inside an MCP client instead of the published package:
+
+```bash
+claude mcp add nyc-restroom -- bun "$(pwd)/src/index.ts"
+```
+
+Useful extras: `bun run test:live` runs one smoke test against the real NYC
+Open Data API (needs network), and `bun test --coverage` reports coverage
+(85%+ lines required on `src/lib/`). Before opening a PR, please make sure
+`bun test`, `bun run typecheck`, and `bun run lint` all pass. The full
+development guide (test architecture, project structure, invariants to
+preserve) is in [docs/development.md](docs/development.md), and
+[DECISIONS.md](DECISIONS.md) explains why things work the way they do.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// Server bootstrap + tool registration.
+//
+// This uses the SDK's low-level `Server` (not the high-level `McpServer`)
+// deliberately: the high-level class pre-validates tool arguments itself and
+// surfaces failures as a raw stringified ZodError, bypassing this codebase's
+// own actionable-error formatting (shared.ts's formatZodError). With the
+// low-level API, raw arguments flow straight into each tool handler, which
+// validates against the full refined zod schema and owns every error message
+// end to end - SPEC.md's "validation failures return actionable tool errors"
+// contract, enforced in exactly one place per tool.
+//
+// Per SPEC.md, stdout is reserved entirely for the MCP JSON-RPC protocol -
+// every log line anywhere in this codebase goes through `lib/logger.ts`,
+// which only ever writes to stderr.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { findRestroomsInputSchema, getRestroomStatusInputSchema, } from './schemas.js';
+import { SocrataClient } from './lib/socrata.js';
+import { TtlLruCache } from './lib/cache.js';
+import { Geolocator } from './lib/geolocate.js';
+import { DeviceLocationProvider } from './lib/device-location.js';
+import { LocationChain } from './lib/location-chain.js';
+import { logger } from './lib/logger.js';
+import { createFindRestroomsHandler } from './tools/find-restrooms.js';
+import { createGetRestroomStatusHandler } from './tools/get-restroom-status.js';
+/** Reads name/version from package.json so the advertised server identity can't drift from the manifest. */
+function readServerInfo() {
+    const packageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url));
+    const raw = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const name = typeof raw.name === 'string' ? raw.name : 'nyc-restroom-mcp';
+    const version = typeof raw.version === 'string' ? raw.version : '0.0.0';
+    return { name, version };
+}
+/**
+ * Converts a zod tool-input schema into the JSON Schema advertised via
+ * tools/list. Cross-field `.refine()` rules aren't representable in JSON
+ * Schema and are dropped here - each handler enforces them by parsing the
+ * full zod schema itself.
+ */
+function toInputJsonSchema(schema) {
+    const json = { ...z.toJSONSchema(schema, { io: 'input' }) };
+    // The $schema meta-key is noise in a tools/list response.
+    delete json.$schema;
+    return json;
+}
+// Both tools only ever read data (no write operations, per SPEC.md) and reach
+// out to the open network (NYC Open Data; find_restrooms's no-coordinates
+// path also uses a geoip service), so readOnlyHint/openWorldHint let clients
+// apply their read-only-tool safety policy instead of a stricter default.
+const READ_ONLY_OPEN_WORLD = { readOnlyHint: true, openWorldHint: true };
+const TOOLS = [
+    {
+        name: 'find_restrooms',
+        title: 'Find nearby NYC public restrooms',
+        description: 'Finds operational NYC public restrooms near a given point, sorted by distance ascending. ' +
+            'latitude/longitude may both be omitted to search from your current location, detected ' +
+            'automatically (precise on-device location if available, otherwise an approximate ' +
+            'IP-based guess) - only used when that location is within New York City, otherwise this ' +
+            'tool returns an error asking for explicit coordinates instead. Radius defaults to 800m ' +
+            'and is clamped to a 5000m maximum. Set open_now to filter to restrooms currently open ' +
+            '(restrooms with unparseable hours are kept, marked "unknown", rather than guessed at).',
+        inputSchema: toInputJsonSchema(findRestroomsInputSchema),
+        annotations: READ_ONLY_OPEN_WORLD,
+    },
+    {
+        name: 'get_restroom_status',
+        title: 'Get a specific NYC restroom and its latest inspection status',
+        description: 'Looks up one NYC public restroom by name or by nearest coordinates, and - where NYC Parks ' +
+            'inspection data is available for it - reports its most recent condition ratings. Only ' +
+            'restrooms operated by NYC Parks are covered by inspection data; other operators (libraries, ' +
+            'automated public toilets, private operators) will report status "no_inspection_data".',
+        inputSchema: toInputJsonSchema(getRestroomStatusInputSchema),
+        annotations: READ_ONLY_OPEN_WORLD,
+    },
+];
+/** Builds the Server with both tools wired up, unconnected to any transport (so tests can construct one). */
+// eslint-disable-next-line @typescript-eslint/no-deprecated -- Server's deprecation notice says "only use for advanced use cases"; owning tool-argument validation (see file header) is exactly that case.
+function buildServer() {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- see above.
+    const server = new Server(readServerInfo(), { capabilities: { tools: {} } });
+    // One SocrataClient for the whole process: it is stateless aside from its
+    // constructor options (baseUrl/token/fetchFn), all of which are read once
+    // from the environment at construction time (see lib/socrata.ts) - this is
+    // the injectable-fetch seam SPEC.md requires stay intact end to end, so
+    // SOCRATA_BASE_URL (used by E2E tests to point at a local fixture server)
+    // flows through untouched here.
+    const socrata = new SocrataClient();
+    // One Geolocator (IP-based fallback) and one DeviceLocationProvider
+    // (precise on-device CoreLocation, tried first) for the whole process,
+    // composed into a single LocationChain - see src/lib/location-chain.ts and
+    // DECISIONS.md's Phase 8 section for the full chain design. Geolocator's
+    // constructor reads GEOIP_BASE_URL from the environment once (defaulting
+    // to the real ipapi.co), and DeviceLocationProvider's constructor reads
+    // CORELOCATION_CMD once (defaulting to "CoreLocationCLI" resolved via
+    // PATH) - both are the seams E2E tests use to point this server at local
+    // fixtures/stubs instead of the real services - see
+    // tests/e2e/geolocation.e2e.test.ts. Only find_restrooms uses this; per
+    // DECISIONS.md's scoping note, get_restroom_status's coordinate variant
+    // still requires explicit latitude/longitude and never auto-locates.
+    const locationChain = new LocationChain({
+        deviceLocation: new DeviceLocationProvider(),
+        geolocator: new Geolocator(),
+    });
+    // A single restrooms-dataset cache is shared between both tools, since
+    // both query i7jb-7jku (find_restrooms via within_circle + status filter,
+    // get_restroom_status via name search or an unfiltered within_circle
+    // "nearest" search). Each query shape uses a distinctly prefixed cache key
+    // ("circle:", "name:", "nearest:" - see the two tool files), so sharing one
+    // instance cannot cause a cross-query-shape collision; it just means the
+    // two tools' upstream restroom lookups share one LRU capacity budget
+    // instead of each needing their own. The three Parks Inspection Program
+    // hop caches are separate instances because each holds a differently
+    // shaped row type (SitesRow / InspectionsRow / ConditionsRow) and is only
+    // ever used by get_restroom_status.
+    const restroomsCache = new TtlLruCache();
+    const sitesCache = new TtlLruCache();
+    const inspectionsCache = new TtlLruCache();
+    const conditionsCache = new TtlLruCache();
+    const handlers = {
+        find_restrooms: createFindRestroomsHandler({ socrata, restroomsCache, locationChain }),
+        get_restroom_status: createGetRestroomStatusHandler({
+            socrata,
+            restroomsCache,
+            sitesCache,
+            inspectionsCache,
+            conditionsCache,
+        }),
+    };
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const handler = handlers[request.params.name];
+        if (handler === undefined) {
+            // Per the MCP spec, an unknown tool name is a protocol-level invalid
+            // params error, not a tool execution error.
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+        }
+        return handler(request.params.arguments ?? {});
+    });
+    return server;
+}
+// Documented defaults for the two overridable base URLs - kept here (not
+// imported from lib/socrata.ts/lib/geolocate.ts) purely to avoid a second
+// export just for this comparison; if either module's own default ever
+// changes, this constant must be updated to match.
+const DEFAULT_SOCRATA_BASE_URL = 'https://data.cityofnewyork.us';
+const DEFAULT_GEOIP_BASE_URL = 'https://ipapi.co';
+/**
+ * Logs one info line for `envVarName` when it is set to something other than
+ * `defaultUrl` - only the origin (scheme + host + port) is logged, never the
+ * full URL or any embedded credentials (a URL can carry a `user:pass@host`
+ * component), per this project's "never log anything sensitive" convention.
+ * If the override isn't even a parseable URL, that fact alone is logged
+ * instead of the raw value, for the same reason.
+ */
+function logBaseUrlOverrideIfPresent(envVarName, value, defaultUrl) {
+    if (value === undefined || value === defaultUrl) {
+        return;
+    }
+    let origin;
+    try {
+        origin = new URL(value).origin;
+    }
+    catch {
+        origin = '(override is not a parseable URL)';
+    }
+    logger.info(`${envVarName} is overridden from its documented default`, { origin });
+}
+/** Startup notice when either upstream base URL is overridden, so logs show whether a deployment talks to the real hosts or a leftover test override. */
+function logStartupOverrideNotices() {
+    logBaseUrlOverrideIfPresent('SOCRATA_BASE_URL', process.env.SOCRATA_BASE_URL, DEFAULT_SOCRATA_BASE_URL);
+    logBaseUrlOverrideIfPresent('GEOIP_BASE_URL', process.env.GEOIP_BASE_URL, DEFAULT_GEOIP_BASE_URL);
+}
+/**
+ * Exits cleanly (code 0) once stdin closes: with stdin gone, a stdio-only
+ * server can never receive another message, and without this it would linger
+ * as an orphan process (verified live). Both 'end' and 'close' are listened
+ * for - which fires first depends on how the client closed the pipe - with a
+ * guard so firing both doesn't log/exit twice.
+ */
+function installStdinCloseHandler() {
+    let hasExited = false;
+    const handleStdinClosed = () => {
+        if (hasExited) {
+            return;
+        }
+        hasExited = true;
+        logger.info('stdin closed - shutting down cleanly', {});
+        process.exit(0);
+    };
+    process.stdin.on('end', handleStdinClosed);
+    process.stdin.on('close', handleStdinClosed);
+}
+async function main() {
+    logStartupOverrideNotices();
+    installStdinCloseHandler();
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const info = readServerInfo();
+    logger.info('nyc-restroom-mcp server started', { name: info.name, version: info.version });
+}
+main().catch((error) => {
+    // A failure here means the server never successfully attached to its
+    // transport (or crashed before doing so) - there is no client connection
+    // to report an MCP tool error through, so the only correct move is to log
+    // to stderr (stdout stays clean either way, since nothing has been
+    // written to it yet) and exit nonzero so the parent process (Claude
+    // Desktop/Code, or a shell) sees the failure.
+    logger.error('nyc-restroom-mcp failed to start', {
+        error: error instanceof Error ? error.message : String(error),
+    });
+    process.exit(1);
+});

package/dist/lib/bounded-body.js

@@ -0,0 +1,86 @@
+// Reads a fetch() Response body up to a byte cap, refusing to buffer past
+// it. Used by both lib/socrata.ts (5 MB cap) and lib/geolocate.ts (64 KB
+// cap) so neither client will ever fully buffer an arbitrarily large
+// upstream response into memory - see DECISIONS.md's security-review
+// section: a reviewer demonstrated parsing and caching a 300k-row response
+// from an unbounded `response.json()` call, which is a DoS vector (a
+// malicious or misbehaving upstream, or a MITM on an unauthenticated HTTP
+// connection, could hand this server a body large enough to exhaust its
+// memory).
+//
+// `Content-Length` is checked first when present, purely as a fast rejection
+// for the common case - it is NOT trusted on its own, since a server can
+// omit it, lie about it, or send a chunked response with no length header at
+// all. The actual enforcement happens while streaming: this function reads
+// the body in chunks via the underlying `ReadableStreamDefaultReader` and
+// aborts (cancelling the stream) the moment the running total exceeds
+// `maxBytes`, regardless of what any header claimed.
+/**
+ * Reads any `ReadableStream<Uint8Array>` up to `maxBytes`, decoding it as
+ * UTF-8 text on success. This is the lower-level primitive both
+ * `readBodyWithCap` (below, for fetch() Response bodies) and
+ * `lib/device-location.ts` (for a spawned CoreLocationCLI subprocess's
+ * stdout, which is a stream but never wrapped in a Response) build on -
+ * neither an HTTP response nor a subprocess's stdout should ever be buffered
+ * without a hard ceiling, for the same DoS reasoning documented at the top
+ * of this file.
+ */
+export async function readStreamWithCap(stream, maxBytes) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    // Sequential await-per-chunk is the only correct way to read a stream.
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        totalBytes += value.byteLength;
+        if (totalBytes > maxBytes) {
+            // Stop pulling more data immediately - cancelling releases the
+            // underlying connection/pipe rather than leaving it half-read.
+            await reader.cancel();
+            return {
+                ok: false,
+                reason: `stream exceeded the ${String(maxBytes)}-byte cap while reading`,
+            };
+        }
+        chunks.push(value);
+    }
+    const combined = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        combined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { ok: true, text: new TextDecoder().decode(combined) };
+}
+/**
+ * Reads `response.body` up to `maxBytes`, decoding it as UTF-8 text on
+ * success. Returns `{ ok: false, reason }` instead of throwing when the cap
+ * is exceeded (by a trusted `Content-Length` pre-check or by the streamed
+ * byte count), so callers can turn that into whatever "clean, non-retryable
+ * failure" shape their own error type uses (SocrataError, or a
+ * GeolocateResultUnavailable) without this module needing to know about
+ * either one.
+ */
+export async function readBodyWithCap(response, maxBytes) {
+    const contentLengthHeader = response.headers.get('content-length');
+    if (contentLengthHeader !== null) {
+        const contentLength = Number(contentLengthHeader);
+        if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+            return {
+                ok: false,
+                reason: `Content-Length ${String(contentLength)} exceeds the ${String(maxBytes)}-byte cap`,
+            };
+        }
+    }
+    const body = response.body;
+    if (body === null) {
+        // No body at all (e.g. a 204-style response) - nothing to bound, and
+        // JSON.parse('') will fail the same way it would for any other empty
+        // body, which is the caller's existing "not valid JSON" failure path.
+        return { ok: true, text: '' };
+    }
+    return readStreamWithCap(body, maxBytes);
+}

package/dist/lib/cache.js

@@ -0,0 +1,78 @@
+// Generic in-memory TTL + LRU cache, backed by a plain `Map`. SPEC.md rules
+// out any external cache dependency (Redis etc), and the whole server is a
+// single long-lived process, so a `Map` with lazy expiry checks on read is
+// all that's needed - see DECISIONS.md's "Cache design" entry for the
+// reasoning behind each choice below (lazy expiry vs a timer, why there's no
+// injected clock, how LRU order is tracked).
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_MAX_ENTRIES = 500;
+/**
+ * A TTL + LRU cache keyed by `K`, storing values of type `V`.
+ *
+ * TTL: each entry expires `ttlMs` after it was last written. Expiry is
+ * checked lazily on `get` - there is no background timer, since nothing in
+ * this server needs proactive eviction (the cache is only ever read in
+ * response to an incoming tool call).
+ *
+ * LRU: `Map` preserves insertion order under iteration, so recency is
+ * tracked by deleting and re-inserting a key whenever it is read (`get` hit)
+ * or written (`set`, including an update to an existing key). When a `set`
+ * would push the cache past `maxEntries`, the least-recently-used entry
+ * (the first key in iteration order) is evicted first.
+ *
+ * This class reads `Date.now()` directly rather than taking an injected
+ * clock function. `bun:test`'s `setSystemTime` patches the global `Date`
+ * object, which `Date.now()` observes automatically, so a custom clock seam
+ * would add a constructor parameter for no test benefit in this codebase.
+ */
+export class TtlLruCache {
+    store = new Map();
+    ttlMs;
+    maxEntries;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Returns the cached value for `key`, or `undefined` if there is no entry
+     * or the entry has expired. A hit refreshes the key's recency (moves it to
+     * the "most recently used" end); an expired entry is deleted as a side
+     * effect of being observed, so it doesn't linger and count against
+     * `maxEntries`.
+     */
+    get(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        if (Date.now() >= entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        // Delete + re-insert marks this key most-recently-used.
+        this.store.delete(key);
+        this.store.set(key, entry);
+        return entry.value;
+    }
+    /**
+     * Stores `value` under `key` with a fresh TTL starting now, evicting the
+     * least-recently-used entry first if the cache is at capacity.
+     */
+    set(key, value) {
+        // If this key already exists, drop it first so the size check below is
+        // accurate (an update to an existing key should never trigger eviction
+        // of a different entry).
+        this.store.delete(key);
+        if (this.store.size >= this.maxEntries) {
+            const oldestKey = this.store.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.store.delete(oldestKey);
+            }
+        }
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    /** Number of entries currently stored, including any not-yet-expired-but-stale ones. */
+    get size() {
+        return this.store.size;
+    }
+}