@design-edito/tools 0.4.5 → 0.4.11

package/agnostic/misc/connection/index.test.js

@@ -0,0 +1,143 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { getConnection, getCurrentDownlink } from './index.js';
+import * as Window from '../crossenv/window/index.js';
+import { JSDOM } from 'jsdom';
+describe('getConnection', () => {
+    beforeEach(() => Window.set(new JSDOM().window));
+    afterEach(() => Window.unset());
+    it('returns undefined when navigator is not available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        Object.defineProperty(window, 'navigator', {
+            value: null,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getConnection()).toBeUndefined();
+    });
+    it('returns undefined when navigator exists but has no connection', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const navigator = {};
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getConnection()).toBeUndefined();
+    });
+    it('returns connection when available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const connection = {
+            downlink: 10,
+            type: 'wifi',
+            effectiveType: '4g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'connection', {
+            value: connection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        const result = getConnection();
+        expect(result).toEqual({
+            downlink: 10,
+            type: 'wifi',
+            effectiveType: '4g'
+        });
+    });
+    it('uses mozConnection as fallback', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const mozConnection = {
+            downlink: 5,
+            type: 'cellular',
+            effectiveType: '3g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'mozConnection', {
+            value: mozConnection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        const result = getConnection();
+        expect(result?.type).toBe('cellular');
+    });
+    it('uses webkitConnection as fallback', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const webkitConnection = {
+            downlink: 7.5,
+            type: 'ethernet',
+            effectiveType: '4g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'webkitConnection', {
+            value: webkitConnection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        const result = getConnection();
+        expect(result?.type).toBe('ethernet');
+    });
+});
+describe('getCurrentDownlink', () => {
+    beforeEach(() => Window.set(new JSDOM().window));
+    afterEach(() => Window.unset());
+    it('returns downlink when connection is available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const connection = {
+            downlink: 10,
+            type: 'wifi',
+            effectiveType: '4g'
+        };
+        const navigator = {};
+        Object.defineProperty(navigator, 'connection', {
+            value: connection,
+            writable: true,
+            configurable: true
+        });
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getCurrentDownlink()).toBe(10);
+    });
+    it('returns undefined when connection is not available', () => {
+        const dom = new JSDOM();
+        const window = dom.window;
+        const navigator = {};
+        Object.defineProperty(window, 'navigator', {
+            value: navigator,
+            writable: true,
+            configurable: true
+        });
+        Window.set(window);
+        expect(getCurrentDownlink()).toBeUndefined();
+    });
+});

package/agnostic/misc/crawler/index.js

@@ -1,47 +1,69 @@
-// src/agnostic/time/wait/index.ts
-async function wait(durationMs) {
-  await new Promise((resolve) => {
-    setTimeout(() => resolve(true), durationMs);
-  });
+import { wait } from '../../time/wait/index.js';
+/**
+ * Creates a sequential crawler with optional delay.
+ *
+ * @template T - The type of content returned by the fetcher.
+ * @param {Options<T>} options - Crawler configuration options.
+ * @param {number} options.limit - Maximum number of URLs to process.
+ * @param {number | (() => number)} [options.delayMs] - Optional delay between processing URLs, in milliseconds, or a function returning the delay.
+ * @param {boolean} [options.allowDuplicates] - Optional, allows fetching and processing a URL that has already been seen.
+ * @param {Fetcher<T>} options.fetcher - Function that fetches content for each URL.
+ * @param {Processor<T>} options.processor - Function that processes fetched content.
+ * @returns {Crawler} An object with methods to start crawling, enqueue URLs, flush the waitlist, and access crawler state.
+ *
+ * @example
+ * ```typescript
+ * const crawler = create({
+ *   limit: 100,
+ *   delayMs: 1000,
+ *   fetcher: async (url) => fetch(url).then(r => r.text()),
+ *   processor: (url, content, { push, processed, waitlist }) => {
+ *     console.log(`Processed ${url}`);
+ *     console.log(`Remaining: ${waitlist.length}, Done: ${processed.size}`);
+ *     // Optionally push more URLs
+ *   }
+ * });
+ *
+ * await crawler.crawl('https://example.com');
+ * console.log('Total processed:', crawler.processed.size);
+ * ```
+ */
+export function create(options) {
+    let ops = 0;
+    const waitlist = [];
+    const push = (...urls) => waitlist.push(...urls);
+    const flush = () => { waitlist.length = 0; };
+    const processed = new Set();
+    const crawl = async (startUrl) => {
+        push(startUrl);
+        while (waitlist.length > 0 && ops < options.limit) {
+            ops++;
+            const currentUrl = waitlist[0];
+            if (!processed.has(currentUrl) || options.allowDuplicates === true) {
+                const content = await options.fetcher(currentUrl);
+                await options.processor(currentUrl, content, {
+                    push,
+                    flush,
+                    processed: new Set(processed),
+                    waitlist: [...waitlist]
+                });
+            }
+            waitlist.shift();
+            processed.add(currentUrl);
+            const delayMs = typeof options.delayMs === 'function'
+                ? options.delayMs()
+                : typeof options.delayMs === 'number'
+                    ? options.delayMs
+                    : 0;
+            if (delayMs !== 0)
+                await wait(delayMs);
+        }
+    };
+    return {
+        crawl,
+        push,
+        flush,
+        processed,
+        waitlist
+    };
 }
-
-// src/agnostic/misc/crawler/index.ts
-function create(options) {
-  let ops = 0;
-  const waitlist = [];
-  const push = (...urls) => waitlist.push(...urls);
-  const flush = () => {
-    waitlist.length = 0;
-  };
-  const processed = /* @__PURE__ */ new Set();
-  const crawl = async (startUrl) => {
-    push(startUrl);
-    while (waitlist.length > 0 && ops < options.limit) {
-      ops++;
-      const currentUrl = waitlist[0];
-      if (!processed.has(currentUrl) || options.allowDuplicates === true) {
-        const content = await options.fetcher(currentUrl);
-        await options.processor(currentUrl, content, {
-          push,
-          flush,
-          processed: new Set(processed),
-          waitlist: [...waitlist]
-        });
-      }
-      waitlist.shift();
-      processed.add(currentUrl);
-      const delayMs = typeof options.delayMs === "function" ? options.delayMs() : typeof options.delayMs === "number" ? options.delayMs : 0;
-      if (delayMs !== 0) await wait(delayMs);
-    }
-  };
-  return {
-    crawl,
-    push,
-    flush,
-    processed,
-    waitlist
-  };
-}
-export {
-  create
-};

package/agnostic/misc/crawler/index.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi } from 'vitest';
+import { create } from './index.js';
+describe('create', () => {
+    it('creates crawler with crawl, push, and flush methods', () => {
+        const crawler = create({
+            limit: 10,
+            fetcher: async () => 'content',
+            processor: async () => { }
+        });
+        expect(crawler).toHaveProperty('crawl');
+        expect(crawler).toHaveProperty('push');
+        expect(crawler).toHaveProperty('flush');
+    });
+    it('processes URLs up to the limit', async () => {
+        const spyFunc = vi.fn(() => 0);
+        const fetcher = async (url) => {
+            spyFunc();
+            return 'content';
+        };
+        const processor = (_u, _c, { push }) => push('new-url');
+        const crawler = create({ limit: 2, fetcher, processor });
+        await crawler.crawl('init-url');
+        expect(spyFunc).toHaveBeenCalledTimes(2);
+    });
+    it('allows processor to push new URLs', async () => {
+        const fetcher = async (url) => `content-${url}`;
+        const sypFunc = vi.fn(() => 0);
+        const processor = async (url, _c, hooks) => {
+            sypFunc();
+            if (url === 'url1')
+                hooks.push('url2', 'url3');
+        };
+        const crawler = create({ limit: 10, fetcher, processor });
+        await crawler.crawl('url1');
+        expect(sypFunc).toHaveBeenCalledTimes(3);
+    });
+    it('respects delay when provided', async () => {
+        const fetcher = vi.fn(async (url) => `content-${url}`);
+        const processor = vi.fn(async () => { });
+        const startTime = Date.now();
+        const crawler = create({ limit: 2, delayMs: 20, fetcher, processor });
+        await crawler.crawl('url1');
+        const elapsed = Date.now() - startTime;
+        expect(elapsed).toBeGreaterThanOrEqual(18);
+    });
+    it('allows flushing the waitlist', async () => {
+        const fetcher = vi.fn(async (url) => `content-${url}`);
+        const processor = vi.fn(async (_u, _c, hooks) => {
+            hooks.push('url2', 'url3');
+            hooks.flush();
+        });
+        const crawler = create({ limit: 10, fetcher, processor });
+        await crawler.crawl('url1');
+        expect(fetcher).toHaveBeenCalledTimes(1);
+    });
+});

package/agnostic/misc/crossenv/detect-runtime/index.js

@@ -1,14 +1,42 @@
-// src/agnostic/misc/crossenv/detect-runtime/index.ts
-function detectRuntime() {
-  if (typeof process?.versions?.node !== "undefined") return "Node.js" /* NODE */;
-  if (typeof window?.document !== "undefined") return "Browser" /* BROWSER */;
-  if (typeof Deno !== "undefined") return "Deno" /* DENO */;
-  if (typeof process !== "undefined" && typeof navigator.userAgent === "string" && navigator.userAgent.includes("ReactNative")) return "React Native" /* REACT_NATIVE */;
-  if (typeof process?.versions !== "undefined" && typeof process.version.electron !== "undefined") return "Electron" /* ELECTRON */;
-  if (typeof self !== "undefined" && typeof self.addEventListener === "function" && typeof Headers !== "undefined") return "Cloudflare Workers" /* CLOUDFLARE */;
-  if (typeof AWS !== "undefined" && typeof AWS.Lambda !== "undefined") return "AWS Lambda" /* AWS_LAMBDA */;
-  return null;
+import { RuntimeName } from '../types.js';
+/**
+ * Detects the current JavaScript runtime environment.
+ *
+ * Checks for Node.js, Browser, Deno, React Native, Electron,
+ * Cloudflare Workers, and AWS Lambda.
+ *
+ * @returns {RuntimeName | null}
+ * - The detected runtime as a `RuntimeName` enum value.
+ * - `null` if the runtime cannot be determined.
+ */
+export function detectRuntime() {
+    /* Node.js */
+    if (typeof process?.versions?.node !== 'undefined')
+        return RuntimeName.NODE;
+    /* Browser */
+    if (typeof window?.document !== 'undefined')
+        return RuntimeName.BROWSER;
+    /* Deno */
+    if (typeof Deno !== 'undefined')
+        return RuntimeName.DENO;
+    /* React Native */
+    if (typeof process !== 'undefined'
+        && typeof navigator.userAgent === 'string'
+        && navigator.userAgent.includes('ReactNative'))
+        return RuntimeName.REACT_NATIVE;
+    /* Electron */
+    if (typeof process?.versions !== 'undefined'
+        && typeof process.version.electron !== 'undefined')
+        return RuntimeName.ELECTRON;
+    /* Cloudflare Workers */
+    if (typeof self !== 'undefined'
+        && typeof self.addEventListener === 'function'
+        && typeof Headers !== 'undefined')
+        return RuntimeName.CLOUDFLARE;
+    /* AWS Lambda */
+    if (typeof AWS !== 'undefined'
+        && typeof AWS.Lambda !== 'undefined')
+        return RuntimeName.AWS_LAMBDA;
+    /* Other */
+    return null;
 }
-export {
-  detectRuntime
-};

package/agnostic/misc/crossenv/detect-runtime/index.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { detectRuntime } from './index.js';
+import { RuntimeName } from '../types.js';
+describe('detectRuntime', () => {
+    // [WIP] Cannot simulate browser in nodejs for now
+    // it('returns RuntimeName.BROWSER in browser environment', () => {
+    //   const result = detectRuntime()
+    //   // In test environment, this should detect browser if window is available
+    //   if (typeof window?.document !== 'undefined') {
+    //     expect(result).toBe(RuntimeName.BROWSER)
+    //   }
+    // })
+    it('returns RuntimeName.NODE in Node.js environment', () => {
+        // This test would need to be run in Node.js environment
+        // In browser test environment, it won't detect Node
+        if (typeof process?.versions?.node !== 'undefined') {
+            expect(detectRuntime()).toBe(RuntimeName.NODE);
+        }
+    });
+    it('returns null when runtime cannot be determined', () => {
+        // This is hard to test without mocking, but we can verify the function exists
+        expect(typeof detectRuntime).toBe('function');
+    });
+});

package/agnostic/misc/crossenv/types.js

@@ -1,14 +1,21 @@
-// src/agnostic/misc/crossenv/types.ts
-var RuntimeName = /* @__PURE__ */ ((RuntimeName2) => {
-  RuntimeName2["NODE"] = "Node.js";
-  RuntimeName2["BROWSER"] = "Browser";
-  RuntimeName2["DENO"] = "Deno";
-  RuntimeName2["REACT_NATIVE"] = "React Native";
-  RuntimeName2["ELECTRON"] = "Electron";
-  RuntimeName2["CLOUDFLARE"] = "Cloudflare Workers";
-  RuntimeName2["AWS_LAMBDA"] = "AWS Lambda";
-  return RuntimeName2;
-})(RuntimeName || {});
-export {
-  RuntimeName
-};
+/**
+ * Enum representing the possible runtime environments.
+ *
+ * - `NODE`         : Node.js
+ * - `BROWSER`      : Web browser
+ * - `DENO`         : Deno runtime
+ * - `REACT_NATIVE` : React Native
+ * - `ELECTRON`     : Electron
+ * - `CLOUDFLARE`   : Cloudflare Workers
+ * - `AWS_LAMBDA`   : AWS Lambda
+ */
+export var RuntimeName;
+(function (RuntimeName) {
+    RuntimeName["NODE"] = "Node.js";
+    RuntimeName["BROWSER"] = "Browser";
+    RuntimeName["DENO"] = "Deno";
+    RuntimeName["REACT_NATIVE"] = "React Native";
+    RuntimeName["ELECTRON"] = "Electron";
+    RuntimeName["CLOUDFLARE"] = "Cloudflare Workers";
+    RuntimeName["AWS_LAMBDA"] = "AWS Lambda";
+})(RuntimeName || (RuntimeName = {}));

package/agnostic/misc/crossenv/window/index.js

@@ -1,28 +1,49 @@
-// src/agnostic/misc/crossenv/window/index.ts
-function exists() {
-  return typeof globalThis !== "undefined" && "window" in globalThis;
+/**
+ * Checks whether a `window` object exists in the current environment.
+ *
+ * @returns {boolean} `true` if `window` is present, `false` otherwise.
+ */
+export function exists() {
+    return typeof globalThis !== 'undefined'
+        && 'window' in globalThis;
 }
-var _window = exists() ? globalThis.window ?? null : null;
-function set(customWindow) {
-  _window = customWindow;
-  return customWindow;
+let _window = exists()
+    ? (globalThis.window ?? null)
+    : null;
+/**
+ * Sets a custom `window` object to be used internally.
+ *
+ * @param {MinimalWindow | null} customWindow - The window object to set, or `null` to unset.
+ * @returns {MinimalWindow | null} The window object that was set.
+ */
+export function set(customWindow) {
+    _window = customWindow;
+    return customWindow;
 }
-function unset() {
-  if (exists()) {
-    _window = globalThis.window;
-  } else {
-    _window = null;
-  }
-  return _window;
+/**
+ * Resets the internal window reference to the global `window` if it exists,
+ * or `null` if no global `window` is available.
+ *
+ * @returns {MinimalWindow | null} The current internal window object after reset.
+ */
+export function unset() {
+    if (exists()) {
+        _window = globalThis.window;
+    }
+    else {
+        _window = null;
+    }
+    return _window;
 }
-function get() {
-  if (_window !== null) return _window;
-  const message = "window is undefined. Please call Window.setWindow(windowObj) before using Window.get.";
-  throw new Error(message);
+/**
+ * Retrieves the currently set `window` object.
+ *
+ * @returns {MinimalWindow} The internal window object.
+ * @throws Will throw an error if no window has been set and none exists globally.
+ */
+export function get() {
+    if (_window !== null)
+        return _window;
+    const message = 'window is undefined. Please call Window.setWindow(windowObj) before using Window.get.';
+    throw new Error(message);
 }
-export {
-  exists,
-  get,
-  set,
-  unset
-};

package/agnostic/misc/crossenv/window/index.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import * as Window from './index.js';
+import { JSDOM } from 'jsdom';
+const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+describe('window', () => {
+    it('does not have a global window in nodejs', () => {
+        expect(Window.exists()).toBe(false);
+    });
+    it('throws when getting before window obj has been set', () => {
+        expect(Window.get).toThrow();
+    });
+    it('does not throw when getting a window obj after having set one', () => {
+        Window.set(dom.window);
+        expect(Window.get).not.toThrow();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        Window.set(2);
+        expect(Window.get()).toBe(2);
+    });
+    it('unsets the window correctly', () => {
+        Window.set(dom.window);
+        Window.unset();
+        expect(Window.get).toThrow();
+    });
+});