@nbtca/docs 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @nbtca/docs
+
+Data-only library for the [NBTCA documents repository](https://github.com/nbtca/documents).
+Fetches directory listings and raw markdown files from GitHub with built-in TTL caching,
+stale-while-revalidate fallback, and rate-limit handling.
+
+Rendering is the consumer's job (e.g. `@nbtca/prompt`).
+
+## Install
+
+```bash
+npm install @nbtca/docs
+```
+
+## Usage
+
+```ts
+import { createDocsClient } from '@nbtca/docs';
+
+const docs = createDocsClient(); // defaults to nbtca/documents@main
+
+const items = await docs.listDir('tutorial');  // DocItem[]
+const md    = await docs.getFile('repair/guide.md');  // string (raw markdown)
+```
+
+Custom target:
+
+```ts
+const docs = createDocsClient({
+  owner: 'my-org',
+  repo: 'my-docs',
+  branch: 'main',
+  token: process.env.GITHUB_TOKEN,
+});
+```
+
+## API
+
+### `createDocsClient(options?)`
+
+| Option | Default | Description |
+|---|---|---|
+| `owner` | `'nbtca'` | GitHub org/user |
+| `repo` | `'documents'` | Repository name |
+| `branch` | `'main'` | Branch or ref |
+| `token` | `GITHUB_TOKEN` env | Auth token (raises rate limit) |
+| `cacheTtlMs.dir` | `300000` (5 min) | Directory listing cache TTL |
+| `cacheTtlMs.file` | `600000` (10 min) | File content cache TTL |
+
+### `docs.listDir(path?)`
+
+Returns `DocItem[]` for the given path (root if omitted).
+Filters out hidden files, non-markdown files, and repository metadata.
+
+### `docs.getFile(path)`
+
+Returns raw markdown as a string. Falls back to stale cache on network error.
+
+### `DocsFetchError`
+
+Thrown when a fetch fails with no stale cache available. Has `.path` and `.status` fields.
+
+## License
+
+MIT

package/dist/__tests__/cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.test.d.ts.map

package/dist/__tests__/cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cache.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/cache.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { TtlCache } from '../cache.js';
+describe('TtlCache', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+    it('returns value before expiry', () => {
+        const c = new TtlCache(1000);
+        c.set('k', 'v');
+        expect(c.get('k')).toBe('v');
+    });
+    it('returns undefined after expiry', () => {
+        const c = new TtlCache(1000);
+        c.set('k', 'v');
+        vi.advanceTimersByTime(1001);
+        expect(c.get('k')).toBeUndefined();
+    });
+    it('getStale returns expired value', () => {
+        const c = new TtlCache(1000);
+        c.set('k', 'v');
+        vi.advanceTimersByTime(1001);
+        expect(c.getStale('k')).toBe('v');
+    });
+    it('evicts oldest when over maxSize', () => {
+        const c = new TtlCache(10000, 2);
+        c.set('a', 1);
+        vi.advanceTimersByTime(1);
+        c.set('b', 2);
+        vi.advanceTimersByTime(1);
+        c.set('c', 3); // should evict 'a'
+        expect(c.get('a')).toBeUndefined();
+        expect(c.get('b')).toBe(2);
+        expect(c.get('c')).toBe(3);
+    });
+    it('clear removes all entries', () => {
+        const c = new TtlCache(10000);
+        c.set('k', 'v');
+        c.clear();
+        expect(c.get('k')).toBeUndefined();
+        expect(c.getStale('k')).toBeUndefined();
+    });
+});
+//# sourceMappingURL=cache.test.js.map

package/dist/__tests__/cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.js","sourceRoot":"","sources":["../../src/__tests__/cache.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/__tests__/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/client.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createDocsClient } from '../client.js';
+import { DocsFetchError } from '../types.js';
+const mockDir = [
+    { name: 'repair', path: 'repair', type: 'dir' },
+    { name: 'guide.md', path: 'repair/guide.md', type: 'file' },
+    { name: 'node_modules', path: 'node_modules', type: 'dir' },
+    { name: '.github', path: '.github', type: 'dir' },
+    { name: 'image.png', path: 'repair/image.png', type: 'file' },
+];
+function mockFetch(response) {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response));
+}
+beforeEach(() => vi.restoreAllMocks());
+describe('createDocsClient', () => {
+    it('filters skipped names and non-md files', async () => {
+        mockFetch({ ok: true, json: async () => mockDir });
+        const client = createDocsClient();
+        const items = await client.listDir('repair');
+        expect(items.map(i => i.name)).not.toContain('node_modules');
+        expect(items.map(i => i.name)).not.toContain('.github');
+        expect(items.map(i => i.name)).not.toContain('image.png');
+        expect(items.find(i => i.name === 'guide.md')).toBeDefined();
+    });
+    it('sorts dirs before files', async () => {
+        mockFetch({ ok: true, json: async () => mockDir });
+        const client = createDocsClient();
+        const items = await client.listDir();
+        const types = items.map(i => i.type);
+        const firstFile = types.indexOf('file');
+        const lastDir = types.lastIndexOf('dir');
+        expect(lastDir).toBeLessThan(firstFile === -1 ? Infinity : firstFile);
+    });
+    it('caches directory results', async () => {
+        const spy = vi.fn().mockResolvedValue({ ok: true, json: async () => [] });
+        vi.stubGlobal('fetch', spy);
+        const client = createDocsClient();
+        await client.listDir('tutorial');
+        await client.listDir('tutorial');
+        expect(spy).toHaveBeenCalledTimes(1);
+    });
+    it('throws DocsFetchError on HTTP error', async () => {
+        mockFetch({ ok: false, status: 404 });
+        const client = createDocsClient();
+        await expect(client.listDir('nonexistent')).rejects.toBeInstanceOf(DocsFetchError);
+    });
+    it('getFile fetches raw content', async () => {
+        mockFetch({ ok: true, text: async () => '# Hello' });
+        const client = createDocsClient();
+        const content = await client.getFile('repair/guide.md');
+        expect(content).toBe('# Hello');
+    });
+    it('getFile caches content', async () => {
+        const spy = vi.fn().mockResolvedValue({ ok: true, text: async () => '# Doc' });
+        vi.stubGlobal('fetch', spy);
+        const client = createDocsClient();
+        await client.getFile('repair/guide.md');
+        await client.getFile('repair/guide.md');
+        expect(spy).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/__tests__/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,12 @@
+export declare class TtlCache<T> {
+    private readonly ttlMs;
+    private readonly maxSize;
+    private readonly map;
+    constructor(ttlMs: number, maxSize?: number);
+    get(key: string): T | undefined;
+    getStale(key: string): T | undefined;
+    set(key: string, value: T): void;
+    clear(): void;
+    private evictOldest;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAKA,qBAAa,QAAQ,CAAC,CAAC;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;gBAGhC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAW;IAGvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAO/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAKhC,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,WAAW;CAMpB"}

package/dist/cache.js

@@ -0,0 +1,34 @@
+export class TtlCache {
+    constructor(ttlMs, maxSize = 50) {
+        this.ttlMs = ttlMs;
+        this.maxSize = maxSize;
+        this.map = new Map();
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() < entry.expiresAt)
+            return entry.value;
+        return undefined;
+    }
+    getStale(key) {
+        return this.map.get(key)?.value;
+    }
+    set(key, value) {
+        this.map.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+        if (this.map.size > this.maxSize)
+            this.evictOldest();
+    }
+    clear() {
+        this.map.clear();
+    }
+    evictOldest() {
+        const oldest = [...this.map.entries()]
+            .sort((a, b) => a[1].expiresAt - b[1].expiresAt)
+            .slice(0, this.map.size - this.maxSize);
+        for (const [key] of oldest)
+            this.map.delete(key);
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,QAAQ;IAGnB,YACmB,KAAa,EACb,UAAkB,EAAE;QADpB,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAa;QAJtB,QAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IAKhD,CAAC;IAEJ,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QACrD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,QAAQ,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACjE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IACvD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;IAEO,WAAW;QACjB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;aACnC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;aAC/C,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,MAAM;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+import type { DocsClient, DocsClientOptions } from './types.js';
+export declare function createDocsClient(options?: DocsClientOptions): DocsClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA4BzE,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAuF5E"}

package/dist/client.js

@@ -0,0 +1,109 @@
+import { TtlCache } from './cache.js';
+import { DocsFetchError } from './types.js';
+const DEFAULTS = {
+    owner: 'nbtca',
+    repo: 'documents',
+    branch: 'main',
+    dirTtlMs: 5 * 60 * 1000,
+    fileTtlMs: 10 * 60 * 1000,
+};
+const SKIP = new Set(['.github', '.husky', '.vitepress', '.vscode', 'node_modules',
+    'assets', 'public', 'scripts', 'utils', 'package.json', 'pnpm-lock.yaml',
+    'tsconfig.json', 'eslint.config.mjs', '.nvmrc', '.gitignore',
+    '.markdownlint-cli2.jsonc', 'CONTRIBUTING.md', 'CONTEXT.md']);
+function filterAndSort(raw) {
+    return raw
+        .filter(i => !i.name.startsWith('.') && !SKIP.has(i.name) &&
+        (i.type === 'dir' || i.name.endsWith('.md')))
+        .map(i => ({ name: i.name, path: i.path, type: (i.type === 'dir' ? 'dir' : 'file') }))
+        .sort((a, b) => {
+        if (a.type !== b.type)
+            return a.type === 'dir' ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+}
+export function createDocsClient(options = {}) {
+    const owner = options.owner ?? DEFAULTS.owner;
+    const repo = options.repo ?? DEFAULTS.repo;
+    const branch = options.branch ?? DEFAULTS.branch;
+    const token = options.token ?? (typeof process !== 'undefined'
+        ? (process.env['GITHUB_TOKEN'] ?? process.env['GH_TOKEN'])
+        : undefined);
+    const dirCache = new TtlCache(options.cacheTtlMs?.dir ?? DEFAULTS.dirTtlMs, 30);
+    const fileCache = new TtlCache(options.cacheTtlMs?.file ?? DEFAULTS.fileTtlMs, 50);
+    function headers() {
+        const h = { 'Accept': 'application/vnd.github.v3+json' };
+        if (token)
+            h['Authorization'] = `Bearer ${token}`;
+        return h;
+    }
+    async function ghFetch(url, timeoutMs = 10000) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            const res = await fetch(url, { signal: ctrl.signal, headers: headers() });
+            return res;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async function listDir(path = '') {
+        const key = path || '__root__';
+        const hit = dirCache.get(key);
+        if (hit)
+            return hit;
+        const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}`;
+        let res;
+        try {
+            res = await ghFetch(url);
+        }
+        catch (err) {
+            const stale = dirCache.getStale(key);
+            if (stale)
+                return stale;
+            const msg = err instanceof Error && err.name === 'AbortError'
+                ? 'Request timed out' : String(err);
+            throw new DocsFetchError(path, null, msg);
+        }
+        if (!res.ok) {
+            const stale = dirCache.getStale(key);
+            if (stale)
+                return stale;
+            throw new DocsFetchError(path, res.status, `HTTP ${res.status}`);
+        }
+        const data = (await res.json());
+        const items = filterAndSort(data);
+        dirCache.set(key, items);
+        return items;
+    }
+    async function getFile(path) {
+        const hit = fileCache.get(path);
+        if (hit)
+            return hit;
+        const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+        let res;
+        try {
+            res = await ghFetch(url, 15000);
+        }
+        catch (err) {
+            const stale = fileCache.getStale(path);
+            if (stale)
+                return stale;
+            const msg = err instanceof Error && err.name === 'AbortError'
+                ? 'Request timed out' : String(err);
+            throw new DocsFetchError(path, null, msg);
+        }
+        if (!res.ok) {
+            const stale = fileCache.getStale(path);
+            if (stale)
+                return stale;
+            throw new DocsFetchError(path, res.status, `HTTP ${res.status}`);
+        }
+        const content = await res.text();
+        fileCache.set(path, content);
+        return content;
+    }
+    return { listDir, getFile };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createDocsClient } from './client.js';
+export type { DocItem, DocsClient, DocsClientOptions } from './types.js';
+export { DocsFetchError } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createDocsClient } from './client.js';
+export { DocsFetchError } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+export interface DocItem {
+    name: string;
+    path: string;
+    type: 'file' | 'dir';
+}
+export interface DocsClientOptions {
+    owner?: string;
+    repo?: string;
+    branch?: string;
+    token?: string;
+    cacheTtlMs?: {
+        dir?: number;
+        file?: number;
+    };
+}
+export interface DocsClient {
+    listDir(path?: string): Promise<DocItem[]>;
+    getFile(path: string): Promise<string>;
+}
+export declare class DocsFetchError extends Error {
+    readonly path: string;
+    readonly status: number | null;
+    constructor(path: string, status: number | null, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE;QACX,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,qBAAa,cAAe,SAAQ,KAAK;aAErB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM,GAAG,IAAI;gBADrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrC,OAAO,EAAE,MAAM;CAKlB"}

package/dist/types.js

@@ -0,0 +1,9 @@
+export class DocsFetchError extends Error {
+    constructor(path, status, message) {
+        super(message);
+        this.path = path;
+        this.status = status;
+        this.name = 'DocsFetchError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YACkB,IAAY,EACZ,MAAqB,EACrC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAe;QAIrC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nbtca/docs",
+  "version": "0.1.0",
+  "description": "Data-only library for the NBTCA documents repository",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "nbtca",
+    "documents",
+    "github"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}