feat(javascript): add logger-console package from v4

Author: shortcuts

clients/algoliasearch-client-javascript/packages/algoliasearch/__tests__/algoliasearch.browser.test.ts

@@ -1,14 +1,35 @@
-import { test, expect } from 'vitest';
+/* eslint no-console: 0 */
 
-import { algoliasearch, apiClientVersion } from '../builds/browser';
+import { vi, test, expect } from 'vitest';
 
-const client = algoliasearch('APP_ID', 'API_KEY');
+import { LogLevelEnum } from '../../client-common/src/types';
+import { createConsoleLogger } from '../../logger-console/src/logger';
+import { algoliasearch, apiClientVersion } from '../builds/browser';
 
 test('sets the ua', () => {
+  const client = algoliasearch('APP_ID', 'API_KEY');
+
   expect(client.transporter.algoliaAgent).toEqual({
     add: expect.any(Function),
     value: expect.stringContaining(
       `Algolia for JavaScript (${apiClientVersion}); Search (${apiClientVersion}); Browser`,
     ),
   });
 });
+
+test('with logger', () => {
+  vi.spyOn(console, 'debug');
+  vi.spyOn(console, 'info');
+  vi.spyOn(console, 'error');
+
+  const client = algoliasearch('APP_ID', 'API_KEY', {
+    logger: createConsoleLogger(LogLevelEnum.Debug),
+  });
+
+  expect(async () => {
+    await client.setSettings({ indexName: 'foo', indexSettings: {} });
+    expect(console.debug).toHaveBeenCalledTimes(1);
+    expect(console.info).toHaveBeenCalledTimes(1);
+    expect(console.error).toHaveBeenCalledTimes(1);
+  }).not.toThrow();
+});

clients/algoliasearch-client-javascript/packages/algoliasearch/__tests__/algoliasearch.common.test.ts

@@ -103,6 +103,11 @@ describe('api', () => {
           url: 'APP_ID-2.algolianet.com',
         },
       ]),
+      logger: {
+        debug: expect.any(Function),
+        error: expect.any(Function),
+        info: expect.any(Function),
+      },
       hostsCache: {
         clear: expect.any(Function),
         delete: expect.any(Function),

clients/algoliasearch-client-javascript/packages/algoliasearch/__tests__/algoliasearch.fetch.test.ts

@@ -1,21 +1,42 @@
-import { test, expect } from 'vitest';
+/* eslint no-console: 0 */
 
-import { algoliasearch, apiClientVersion } from '../builds/fetch';
+import { vi, test, expect } from 'vitest';
 
-const client = algoliasearch('APP_ID', 'API_KEY');
+import { LogLevelEnum } from '../../client-common/src/types';
+import { createConsoleLogger } from '../../logger-console/src/logger';
+import { algoliasearch, apiClientVersion } from '../builds/fetch';
 
 test('sets the ua', () => {
+  const client = algoliasearch('APP_ID', 'API_KEY');
   expect(client.transporter.algoliaAgent).toEqual({
     add: expect.any(Function),
     value: expect.stringContaining(`Algolia for JavaScript (${apiClientVersion}); Search (${apiClientVersion}); Fetch`),
   });
 });
 
 test('forwards node search helpers', () => {
+  const client = algoliasearch('APP_ID', 'API_KEY');
   expect(client.generateSecuredApiKey).not.toBeUndefined();
   expect(client.getSecuredApiKeyRemainingValidity).not.toBeUndefined();
   expect(() => {
     const resp = client.generateSecuredApiKey({ parentApiKey: 'foo', restrictions: { validUntil: 200 } });
     client.getSecuredApiKeyRemainingValidity({ securedApiKey: resp });
   }).not.toThrow();
 });
+
+test('with logger', () => {
+  vi.spyOn(console, 'debug');
+  vi.spyOn(console, 'info');
+  vi.spyOn(console, 'error');
+
+  const client = algoliasearch('APP_ID', 'API_KEY', {
+    logger: createConsoleLogger(LogLevelEnum.Debug),
+  });
+
+  expect(async () => {
+    await client.setSettings({ indexName: 'foo', indexSettings: {} });
+    expect(console.debug).toHaveBeenCalledTimes(1);
+    expect(console.info).toHaveBeenCalledTimes(1);
+    expect(console.error).toHaveBeenCalledTimes(1);
+  }).not.toThrow();
+});

clients/algoliasearch-client-javascript/packages/algoliasearch/__tests__/algoliasearch.node.test.ts

@@ -1,10 +1,13 @@
-import { test, expect } from 'vitest';
+/* eslint no-console: 0 */
 
-import { algoliasearch, apiClientVersion } from '../builds/node';
+import { vi, test, expect } from 'vitest';
 
-const client = algoliasearch('APP_ID', 'API_KEY');
+import { LogLevelEnum } from '../../client-common/src/types';
+import { createConsoleLogger } from '../../logger-console/src/logger';
+import { algoliasearch, apiClientVersion } from '../builds/node';
 
 test('sets the ua', () => {
+  const client = algoliasearch('APP_ID', 'API_KEY');
   expect(client.transporter.algoliaAgent).toEqual({
     add: expect.any(Function),
     value: expect.stringContaining(
@@ -14,10 +17,28 @@ test('sets the ua', () => {
 });
 
 test('forwards node search helpers', () => {
+  const client = algoliasearch('APP_ID', 'API_KEY');
   expect(client.generateSecuredApiKey).not.toBeUndefined();
   expect(client.getSecuredApiKeyRemainingValidity).not.toBeUndefined();
   expect(() => {
     const resp = client.generateSecuredApiKey({ parentApiKey: 'foo', restrictions: { validUntil: 200 } });
     client.getSecuredApiKeyRemainingValidity({ securedApiKey: resp });
   }).not.toThrow();
 });
+
+test('with logger', () => {
+  vi.spyOn(console, 'debug');
+  vi.spyOn(console, 'info');
+  vi.spyOn(console, 'error');
+
+  const client = algoliasearch('APP_ID', 'API_KEY', {
+    logger: createConsoleLogger(LogLevelEnum.Debug),
+  });
+
+  expect(async () => {
+    await client.setSettings({ indexName: 'foo', indexSettings: {} });
+    expect(console.debug).toHaveBeenCalledTimes(1);
+    expect(console.info).toHaveBeenCalledTimes(1);
+    expect(console.error).toHaveBeenCalledTimes(1);
+  }).not.toThrow();
+});

clients/algoliasearch-client-javascript/packages/client-common/index.ts

@@ -1,8 +1,9 @@
-export * from './src/createAuth';
-export * from './src/createIterablePromise';
 export * from './src/cache';
-export * from './src/transporter';
+export * from './src/constants';
 export * from './src/createAlgoliaAgent';
+export * from './src/createAuth';
+export * from './src/createIterablePromise';
 export * from './src/getAlgoliaAgent';
+export * from './src/logger';
+export * from './src/transporter';
 export * from './src/types';
-export * from './src/constants';

clients/algoliasearch-client-javascript/packages/client-common/src/__tests__/logger/null-logger.test.ts

@@ -0,0 +1,24 @@
+/* eslint no-console: 0 */
+
+import { vi, describe, test, expect } from 'vitest';
+
+import { createNullLogger } from '../../logger';
+
+describe('null logger', () => {
+  test('has a null behavior', async () => {
+    vi.resetAllMocks();
+    vi.spyOn(console, 'debug');
+    vi.spyOn(console, 'info');
+    vi.spyOn(console, 'error');
+
+    const logger = createNullLogger();
+
+    await logger.debug('foo', {});
+    await logger.info('foo', {});
+    await logger.error('foo', {});
+
+    expect(console.debug).toHaveBeenCalledTimes(0);
+    expect(console.info).toHaveBeenCalledTimes(0);
+    expect(console.error).toHaveBeenCalledTimes(0);
+  });
+});

clients/algoliasearch-client-javascript/packages/client-common/src/logger/createNullLogger.ts

@@ -0,0 +1,15 @@
+import type { Logger } from '../types/logger';
+
+export function createNullLogger(): Logger {
+  return {
+    debug(_message: string, _args?: any): Promise<void> {
+      return Promise.resolve();
+    },
+    info(_message: string, _args?: any): Promise<void> {
+      return Promise.resolve();
+    },
+    error(_message: string, _args?: any): Promise<void> {
+      return Promise.resolve();
+    },
+  };
+}

clients/algoliasearch-client-javascript/packages/client-common/src/logger/index.ts

@@ -0,0 +1 @@
+export * from './createNullLogger';

clients/algoliasearch-client-javascript/packages/client-common/src/transporter/createTransporter.ts

@@ -25,6 +25,7 @@ export function createTransporter({
   hosts,
   hostsCache,
   baseHeaders,
+  logger,
   baseQueryParameters,
   algoliaAgent,
   timeouts,
@@ -174,8 +175,7 @@ export function createTransporter({
          * the end user to debug / store stack frames even
          * when a retry error does not happen.
          */
-        // eslint-disable-next-line no-console -- this will be fixed by exposing a `logger` to the transporter
-        console.log('Retryable failure', stackFrameWithoutCredentials(stackFrame));
+        logger.info('Retryable failure', stackFrameWithoutCredentials(stackFrame));
 
         /**
          * We also store the state of the host in failure cases. If the host, is
@@ -304,6 +304,7 @@ export function createTransporter({
     hostsCache,
     requester,
     timeouts,
+    logger,
     algoliaAgent,
     baseHeaders,
     baseQueryParameters,

clients/algoliasearch-client-javascript/packages/client-common/src/types/index.ts

@@ -2,5 +2,6 @@ export * from './cache';
 export * from './createClient';
 export * from './createIterablePromise';
 export * from './host';
+export * from './logger';
 export * from './requester';
 export * from './transporter';

clients/algoliasearch-client-javascript/packages/client-common/src/types/logger.ts

@@ -0,0 +1,24 @@
+export const LogLevelEnum: Readonly<Record<string, LogLevelType>> = {
+  Debug: 1,
+  Info: 2,
+  Error: 3,
+};
+
+export type LogLevelType = 1 | 2 | 3;
+
+export type Logger = {
+  /**
+   * Logs debug messages.
+   */
+  debug: (message: string, args?: any) => Promise<void>;
+
+  /**
+   * Logs info messages.
+   */
+  info: (message: string, args?: any) => Promise<void>;
+
+  /**
+   * Logs error messages.
+   */
+  error: (message: string, args?: any) => Promise<void>;
+};

clients/algoliasearch-client-javascript/packages/client-common/src/types/transporter.ts

@@ -1,5 +1,6 @@
 import type { Cache } from './cache';
 import type { Host } from './host';
+import type { Logger } from './logger';
 import type { Request, Requester, EndRequest, Response } from './requester';
 
 export type Headers = Record<string, string>;
@@ -87,6 +88,11 @@ export type TransporterOptions = {
    */
   hostsCache: Cache;
 
+  /**
+   * The logger instance to send events of the transporter.
+   */
+  logger: Logger;
+
   /**
    * The underlying requester used. Should differ
    * depending of the environment where the client

clients/algoliasearch-client-javascript/packages/client-common/vitest.workspace.ts

@@ -8,6 +8,7 @@ export default defineWorkspace([
         'src/__tests__/cache/null-cache.test.ts',
         'src/__tests__/cache/memory-cache.test.ts',
         'src/__tests__/create-iterable-promise.test.ts',
+        'src/__tests__/logger/null-logger.test.ts',
       ],
       name: 'node',
       environment: 'node',
@@ -20,6 +21,7 @@ export default defineWorkspace([
         'src/__tests__/cache/fallbackable-cache.test.ts',
         'src/__tests__/cache/null-cache.test.ts',
         'src/__tests__/create-iterable-promise.test.ts',
+        'src/__tests__/logger/null-logger.test.ts',
       ],
       name: 'jsdom',
       environment: 'jsdom',

clients/algoliasearch-client-javascript/yarn.lock

@@ -139,6 +139,22 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@algolia/logger-console@npm:5.5.3, @algolia/logger-console@workspace:packages/logger-console":
+  version: 0.0.0-use.local
+  resolution: "@algolia/logger-console@workspace:packages/logger-console"
+  dependencies:
+    "@algolia/client-common": "npm:5.5.3"
+    "@arethetypeswrong/cli": "npm:0.16.4"
+    "@types/node": "npm:22.5.5"
+    jsdom: "npm:25.0.0"
+    publint: "npm:0.2.11"
+    ts-node: "npm:10.9.2"
+    tsup: "npm:8.3.0"
+    typescript: "npm:5.6.2"
+    vitest: "npm:2.1.1"
+  languageName: unknown
+  linkType: soft
+
 "@algolia/monitoring@workspace:packages/monitoring":
   version: 0.0.0-use.local
   resolution: "@algolia/monitoring@workspace:packages/monitoring"
@@ -2082,6 +2098,7 @@ __metadata:
     "@algolia/client-common": "npm:5.5.3"
     "@algolia/client-personalization": "npm:5.5.3"
     "@algolia/client-search": "npm:5.5.3"
+    "@algolia/logger-console": "npm:5.5.3"
     "@algolia/recommend": "npm:5.5.3"
     "@algolia/requester-browser-xhr": "npm:5.5.3"
     "@algolia/requester-fetch": "npm:5.5.3"

templates/javascript/clients/client/api/imports.mustache

@@ -1,6 +1,7 @@
 import {
   createAuth,
   createTransporter,
+  createNullLogger,
   getAlgoliaAgent,
   shuffle,
   {{#isSearchClient}}

templates/javascript/clients/client/builds/browser.mustache

@@ -11,6 +11,7 @@ export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<t
       read: DEFAULT_READ_TIMEOUT_BROWSER,
       write: DEFAULT_WRITE_TIMEOUT_BROWSER,
     },
+    logger: createNullLogger(),
     requester: createXhrRequester(),
     algoliaAgents: [{ segment: 'Browser' }],
     authMode: 'WithinQueryParameters',

templates/javascript/clients/client/builds/definition.mustache

@@ -1,7 +1,7 @@
 import { createXhrRequester } from '@algolia/requester-browser-xhr';
 import { createHttpRequester } from '@algolia/requester-node-http';
 import { createFetchRequester } from '@algolia/requester-fetch';
-import { createMemoryCache, createFallbackableCache, createBrowserLocalStorageCache, createNullCache,  ClientOptions, serializeQueryParameters, DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_WRITE_TIMEOUT_NODE, DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_BROWSER } from '@algolia/client-common';
+import { createNullLogger, createMemoryCache, createFallbackableCache, createBrowserLocalStorageCache, createNullCache,  ClientOptions, serializeQueryParameters, DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_WRITE_TIMEOUT_NODE, DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_BROWSER } from '@algolia/client-common';
 
 import { create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}, apiClientVersion } from '../src/{{apiName}}';
 

templates/javascript/clients/client/builds/fetch.mustache

@@ -12,6 +12,7 @@ export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<t
         read: DEFAULT_READ_TIMEOUT_NODE,
         write: DEFAULT_WRITE_TIMEOUT_NODE,
       },
+      logger: createNullLogger(),
       algoliaAgents: [{ segment: 'Fetch' }],
       requester: createFetchRequester(),
       responsesCache: createNullCache(),

templates/javascript/clients/client/builds/liteNode.mustache

@@ -11,6 +11,7 @@ export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<t
       read: DEFAULT_READ_TIMEOUT_NODE,
       write: DEFAULT_WRITE_TIMEOUT_NODE,
     },
+    logger: createNullLogger(),
     requester: createHttpRequester(),
     algoliaAgents: [{ segment: 'Node.js', version: process.versions.node }],
     responsesCache: createNullCache(),

templates/javascript/clients/client/builds/node.mustache

@@ -12,6 +12,7 @@ export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<t
         read: DEFAULT_READ_TIMEOUT_NODE,
         write: DEFAULT_WRITE_TIMEOUT_NODE,
       },
+      logger: createNullLogger(),
       requester: createHttpRequester(),
       algoliaAgents: [{ segment: 'Node.js', version: process.versions.node }],
       responsesCache: createNullCache(),