@algolia/client-common 4.14.2 → 5.0.0-alpha.3

package/package.json

@@ -1,22 +1,31 @@
 {
   "name": "@algolia/client-common",
-  "version": "4.14.2",
-  "private": false,
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/algolia/algoliasearch-client-javascript.git"
-  },
+  "version": "5.0.0-alpha.3",
+  "description": "Common package for the Algolia JavaScript API client.",
+  "repository": "algolia/algoliasearch-client-javascript",
   "license": "MIT",
-  "sideEffects": false,
-  "main": "index.js",
-  "module": "dist/client-common.esm.js",
-  "types": "dist/client-common.d.ts",
+  "author": "Algolia",
+  "main": "dist/client-common.cjs.js",
+  "module": "dist/client-common.esm.node.js",
+  "types": "dist/index.d.ts",
   "files": [
-    "index.js",
-    "dist"
+    "dist",
+    "src",
+    "index.ts"
   ],
-  "dependencies": {
-    "@algolia/requester-common": "4.14.2",
-    "@algolia/transporter": "4.14.2"
+  "scripts": {
+    "clean": "rm -rf dist/",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@types/jest": "28.1.6",
+    "@types/node": "16.11.45",
+    "jest": "28.1.3",
+    "jest-environment-jsdom": "28.1.3",
+    "ts-jest": "28.0.7",
+    "typescript": "4.7.4"
+  },
+  "engines": {
+    "node": ">= 14.0.0"
   }
 }

package/src/__tests__/cache/browser-local-storage-cache.test.ts

@@ -0,0 +1,134 @@
+import { createBrowserLocalStorageCache } from '../../cache';
+
+const version = 'foobar';
+const notAvailableStorage = new Proxy(window.localStorage, {
+  get() {
+    return (): void => {
+      throw new Error('Component is not available');
+    };
+  },
+});
+
+type DefaultValue = Promise<{ bar: number }>;
+
+describe('browser local storage cache', () => {
+  const missMock = jest.fn();
+  const events = {
+    miss: (): Promise<any> => Promise.resolve(missMock()),
+  };
+
+  beforeEach(() => {
+    window.localStorage.clear();
+    jest.clearAllMocks();
+  });
+
+  it('sets/gets values', async () => {
+    const cache = createBrowserLocalStorageCache({ key: version });
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 1 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { bar: 1 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+
+    await cache.set({ key: 'foo' }, { foo: 2 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { foo: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('deletes keys', async () => {
+    const cache = createBrowserLocalStorageCache({ key: version });
+
+    await cache.set({ key: 'foo' }, { bar: 1 });
+    await cache.delete({ key: 'foo' });
+
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 2 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { bar: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('can be cleared', async () => {
+    const cache = createBrowserLocalStorageCache({ key: version });
+
+    await cache.set({ key: 'foo' }, { bar: 1 });
+    await cache.clear();
+
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 2 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { bar: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+    expect(localStorage.length).toBe(0);
+  });
+
+  it('do throws localstorage exceptions on access', async () => {
+    const message =
+      "Failed to read the 'localStorage' property from 'Window': Access is denied for this document.";
+    const cache = createBrowserLocalStorageCache(
+      new Proxy(
+        { key: 'foo' },
+        {
+          get(_, key): DOMException | string {
+            if (key === 'key') {
+              return 'foo';
+            }
+
+            // Simulates a window.localStorage access.
+            throw new DOMException(message);
+          },
+        }
+      )
+    );
+    const key = { foo: 'bar' };
+    const value = 'foo';
+    const fallback = 'bar';
+
+    await expect(cache.delete(key)).rejects.toEqual(new DOMException(message));
+    await expect(cache.set(key, value)).rejects.toEqual(
+      new DOMException(message)
+    );
+    await expect(
+      cache.get(key, () => Promise.resolve(fallback))
+    ).rejects.toEqual(new DOMException(message));
+  });
+
+  it('do throws localstorage exceptions after access', async () => {
+    const cache = createBrowserLocalStorageCache({
+      key: version,
+      localStorage: notAvailableStorage,
+    });
+    const key = { foo: 'bar' };
+    const value = 'foo';
+    const fallback = 'bar';
+    const message = 'Component is not available';
+
+    await expect(cache.delete(key)).rejects.toEqual(new Error(message));
+    await expect(cache.set(key, value)).rejects.toEqual(new Error(message));
+    await expect(
+      cache.get(key, () => Promise.resolve(fallback))
+    ).rejects.toEqual(new Error(message));
+  });
+
+  it('creates a namespace within local storage', async () => {
+    const cache = createBrowserLocalStorageCache({
+      key: version,
+    });
+    const key = { foo: 'bar' };
+    const value = 'foo';
+
+    expect(localStorage.getItem(`algolia-client-js-${version}`)).toBeNull();
+
+    await cache.set(key, value);
+
+    expect(localStorage.getItem(`algolia-client-js-${version}`)).toBe(
+      '{"{\\"foo\\":\\"bar\\"}":"foo"}'
+    );
+  });
+});

package/src/__tests__/cache/fallbackable-cache.test.ts

@@ -0,0 +1,126 @@
+import {
+  createBrowserLocalStorageCache,
+  createFallbackableCache,
+  createMemoryCache,
+  createNullCache,
+} from '../../cache';
+
+const version = 'foobar';
+const notAvailableStorage = new Proxy(window.localStorage, {
+  get() {
+    return (): void => {
+      throw new Error('Component is not available');
+    };
+  },
+});
+
+type DefaultValue = Promise<Record<number, number>>;
+
+describe('fallbackable cache', () => {
+  const key = { 1: 2 };
+  const value = { 3: 4 };
+  const defaultValue = (): DefaultValue => Promise.resolve({ 5: 6 });
+
+  it('always fallback in null cache', async () => {
+    const cache = createFallbackableCache({ caches: [] });
+
+    await cache.set(key, value);
+    expect(await cache.get(key, defaultValue)).toEqual({
+      5: 6,
+    });
+  });
+
+  describe('order', () => {
+    it('use memory cache', async () => {
+      const cache = createFallbackableCache({
+        caches: [createMemoryCache()],
+      });
+
+      await cache.set(key, value);
+
+      expect(await cache.get(key, defaultValue)).toEqual({
+        3: 4,
+      });
+    });
+
+    it('use null cache first', async () => {
+      const cache = createFallbackableCache({
+        caches: [createNullCache(), createMemoryCache()],
+      });
+
+      await cache.set(key, value);
+
+      expect(await cache.get(key, defaultValue)).toEqual({
+        5: 6,
+      });
+    });
+  });
+
+  describe('fallbacks', () => {
+    it('to memory cache', async () => {
+      const cache = createFallbackableCache({
+        caches: [
+          createBrowserLocalStorageCache({
+            key: version,
+            // @ts-expect-error this will make the cache fail, and normally we fallback on memory cache
+            localStorage: {},
+          }),
+          createMemoryCache(),
+        ],
+      });
+
+      await cache.set(key, value);
+
+      expect(await cache.get(key, defaultValue)).toEqual({
+        3: 4,
+      });
+    });
+
+    it('to null cache', async () => {
+      const cache = createFallbackableCache({
+        caches: [
+          createBrowserLocalStorageCache({
+            key: version,
+            // @ts-expect-error this will make the cache fail, and normally we fallback on memory cache
+            localStorage: {},
+          }),
+        ],
+      });
+
+      await cache.set(key, value);
+
+      expect(await cache.get(key, defaultValue)).toEqual({
+        5: 6,
+      });
+    });
+
+    it('to memory cache', async () => {
+      const cache = createFallbackableCache({
+        caches: [
+          createBrowserLocalStorageCache({
+            key: version,
+            // @ts-expect-error this will make the cache fail
+            localStorage: {},
+          }),
+          createBrowserLocalStorageCache({
+            key: version,
+            localStorage: notAvailableStorage, // this will make the cache fail due localStorage not available
+          }),
+          createMemoryCache(),
+        ],
+      });
+
+      await cache.set(key, value);
+
+      expect(await cache.get(key, defaultValue)).toEqual({
+        3: 4,
+      });
+
+      await cache.clear();
+
+      expect(await cache.get(key, defaultValue)).toEqual({
+        5: 6,
+      });
+    });
+  });
+});

package/src/__tests__/cache/memory-cache.test.ts

@@ -0,0 +1,90 @@
+import { createMemoryCache } from '../../cache';
+
+type DefaultValue = Promise<{ bar: number }>;
+
+describe('memory cache', () => {
+  const missMock = jest.fn();
+  const events = {
+    miss: (): Promise<any> => Promise.resolve(missMock()),
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('sets/gets values', async () => {
+    const cache = createMemoryCache();
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 1 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      {
+        bar: 1,
+      }
+    );
+
+    await cache.set({ key: 'foo' }, { foo: 2 });
+
+    expect(missMock.mock.calls.length).toBe(1);
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { foo: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('getted values do not have references to the value on cache', async () => {
+    const cache = createMemoryCache();
+    const key = { foo: 'bar' };
+    const obj = { 1: { 2: 'bar' } };
+    const defaultObj = { 1: { 2: 'too' } };
+
+    await cache.set(key, obj);
+    const gettedValue = await cache.get(key, () => Promise.resolve(defaultObj));
+    gettedValue[1][2] = 'foo';
+
+    expect(await cache.get(key, () => Promise.resolve(defaultObj))).toEqual({
+      1: { 2: 'bar' },
+    });
+  });
+
+  it('deletes keys', async () => {
+    const cache = createMemoryCache();
+
+    await cache.set({ key: 'foo' }, { bar: 1 });
+    await cache.delete({ key: 'foo' });
+
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 2 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { bar: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('can be cleared', async () => {
+    const cache = createMemoryCache();
+
+    await cache.set({ key: 'foo' }, { bar: 1 });
+    await cache.clear();
+
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 2 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { bar: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('do not force promise based api for clearing cache', async () => {
+    const cache = createMemoryCache();
+
+    cache.set({ key: 'foo' }, { bar: 1 });
+    cache.clear();
+
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 2 });
+
+    expect(await cache.get({ key: 'foo' }, defaultValue, events)).toMatchObject(
+      { bar: 2 }
+    );
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+});

package/src/__tests__/cache/null-cache.test.ts

@@ -0,0 +1,49 @@
+import { createNullCache } from '../../cache';
+
+type DefaultValue = Promise<{ bar: number }>;
+
+describe('null cache', () => {
+  const cache = createNullCache();
+  const missMock = jest.fn();
+  const events = {
+    miss: (): Promise<any> => Promise.resolve(missMock()),
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('does not set value', async () => {
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 12 });
+
+    await cache.set({ key: 'key' }, { foo: 10 });
+
+    expect(await cache.get({ key: 'key' }, defaultValue, events)).toMatchObject(
+      {
+        bar: 12,
+      }
+    );
+
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('returns default value', async () => {
+    const defaultValue = (): DefaultValue => Promise.resolve({ bar: 12 });
+
+    expect(await cache.get({ foo: 'foo' }, defaultValue, events)).toMatchObject(
+      {
+        bar: 12,
+      }
+    );
+
+    expect(missMock.mock.calls.length).toBe(1);
+  });
+
+  it('can be deleted', async () => {
+    await cache.delete('foo');
+  });
+
+  it('can be cleared', async () => {
+    await cache.clear();
+  });
+});

package/src/__tests__/create-retryable-promise.test.ts

@@ -0,0 +1,86 @@
+import { createRetryablePromise } from '../createRetryablePromise';
+
+describe('createRetryablePromise', () => {
+  it('resolves promise after some retries', async () => {
+    let calls = 0;
+    const promise = createRetryablePromise({
+      func: () => {
+        return new Promise((resolve) => {
+          calls += 1;
+          resolve(`success #${calls}`);
+        });
+      },
+      validate: () => calls >= 3,
+    });
+
+    await expect(promise).resolves.toEqual('success #3');
+    expect(calls).toBe(3);
+  });
+
+  it('gets the rejection of the given promise via reject', async () => {
+    let calls = 0;
+
+    const promise = createRetryablePromise({
+      func: () => {
+        return new Promise((resolve, reject) => {
+          calls += 1;
+          if (calls <= 3) {
+            resolve('okay');
+          } else {
+            reject(new Error('nope'));
+          }
+        });
+      },
+      validate: () => false,
+    });
+
+    await expect(promise).rejects.toEqual(
+      expect.objectContaining({ message: 'nope' })
+    );
+  });
+
+  it('gets the rejection of the given promise via throw', async () => {
+    let calls = 0;
+
+    const promise = createRetryablePromise({
+      func: () => {
+        return new Promise((resolve) => {
+          calls += 1;
+          if (calls <= 3) {
+            resolve('okay');
+          } else {
+            throw new Error('nope');
+          }
+        });
+      },
+      validate: () => false,
+    });
+
+    await expect(promise).rejects.toEqual(
+      expect.objectContaining({ message: 'nope' })
+    );
+  });
+
+  it('gets the rejection when it exceeds the max retries number', async () => {
+    const MAX_RETRIES = 3;
+    let calls = 0;
+
+    const promise = createRetryablePromise({
+      func: () => {
+        return new Promise((resolve) => {
+          calls += 1;
+          resolve('okay');
+        });
+      },
+      validate: () => false,
+      maxRetries: MAX_RETRIES,
+    });
+
+    await expect(promise).rejects.toEqual(
+      expect.objectContaining({
+        message: 'The maximum number of retries exceeded. (3/3)',
+      })
+    );
+    expect(calls).toBe(MAX_RETRIES);
+  });
+});

package/src/cache/createBrowserLocalStorageCache.ts

@@ -0,0 +1,74 @@
+import type { BrowserLocalStorageOptions, Cache, CacheEvents } from '../types';
+
+export function createBrowserLocalStorageCache(
+  options: BrowserLocalStorageOptions
+): Cache {
+  let storage: Storage;
+  // We've changed the namespace to avoid conflicts with v4, as this version is a huge breaking change
+  const namespaceKey = `algolia-client-js-${options.key}`;
+
+  function getStorage(): Storage {
+    if (storage === undefined) {
+      storage = options.localStorage || window.localStorage;
+    }
+
+    return storage;
+  }
+
+  function getNamespace<TValue>(): Record<string, TValue> {
+    return JSON.parse(getStorage().getItem(namespaceKey) || '{}');
+  }
+
+  return {
+    get<TValue>(
+      key: Record<string, any> | string,
+      defaultValue: () => Promise<TValue>,
+      events: CacheEvents<TValue> = {
+        miss: (): Promise<void> => Promise.resolve(),
+      }
+    ): Promise<TValue> {
+      return Promise.resolve()
+        .then(() => {
+          const keyAsString = JSON.stringify(key);
+          const value = getNamespace<TValue>()[keyAsString];
+
+          return Promise.all([value || defaultValue(), value !== undefined]);
+        })
+        .then(([value, exists]) => {
+          return Promise.all([value, exists || events.miss(value)]);
+        })
+        .then(([value]) => value);
+    },
+
+    set<TValue>(
+      key: Record<string, any> | string,
+      value: TValue
+    ): Promise<TValue> {
+      return Promise.resolve().then(() => {
+        const namespace = getNamespace();
+
+        namespace[JSON.stringify(key)] = value;
+
+        getStorage().setItem(namespaceKey, JSON.stringify(namespace));
+
+        return value;
+      });
+    },
+
+    delete(key: Record<string, any> | string): Promise<void> {
+      return Promise.resolve().then(() => {
+        const namespace = getNamespace();
+
+        delete namespace[JSON.stringify(key)];
+
+        getStorage().setItem(namespaceKey, JSON.stringify(namespace));
+      });
+    },
+
+    clear(): Promise<void> {
+      return Promise.resolve().then(() => {
+        getStorage().removeItem(namespaceKey);
+      });
+    },
+  };
+}

package/src/cache/createFallbackableCache.ts

@@ -0,0 +1,53 @@
+import type { FallbackableCacheOptions, Cache, CacheEvents } from '../types';
+
+import { createNullCache } from './createNullCache';
+
+export function createFallbackableCache(
+  options: FallbackableCacheOptions
+): Cache {
+  const caches = [...options.caches];
+  const current = caches.shift();
+
+  if (current === undefined) {
+    return createNullCache();
+  }
+
+  return {
+    get<TValue>(
+      key: Record<string, any> | string,
+      defaultValue: () => Promise<TValue>,
+      events: CacheEvents<TValue> = {
+        miss: (): Promise<void> => Promise.resolve(),
+      }
+    ): Promise<TValue> {
+      return current.get(key, defaultValue, events).catch(() => {
+        return createFallbackableCache({ caches }).get(
+          key,
+          defaultValue,
+          events
+        );
+      });
+    },
+
+    set<TValue>(
+      key: Record<string, any> | string,
+      value: TValue
+    ): Promise<TValue> {
+      return current.set(key, value).catch(() => {
+        return createFallbackableCache({ caches }).set(key, value);
+      });
+    },
+
+    delete(key: Record<string, any> | string): Promise<void> {
+      return current.delete(key).catch(() => {
+        return createFallbackableCache({ caches }).delete(key);
+      });
+    },
+
+    clear(): Promise<void> {
+      return current.clear().catch(() => {
+        return createFallbackableCache({ caches }).clear();
+      });
+    },
+  };
+}