docs: lot of guides (#4355)

Co-authored-by: Morgan Leroi <[email protected]>
Co-authored-by: Pierre Millot <[email protected]>
Co-authored-by: Thomas Raffray <[email protected]>

Author: 4 people

clients/algoliasearch-client-csharp/algoliasearch/Utils/SearchClientExtensions.cs

@@ -176,6 +176,18 @@ public partial interface ISearchClient
   /// <inheritdoc cref="SaveObjectsAsync{T}(string, IEnumerable{T}, RequestOptions, CancellationToken)"/>
   List<BatchResponse> SaveObjects<T>(string indexName, IEnumerable<T> objects, bool waitForTasks = false, int batchSize = 1000, RequestOptions options = null, CancellationToken cancellationToken = default) where T : class;
 
+  /// <summary>
+  /// Helper: Saves the given array of objects in the given index. The `chunkedBatch` helper is used under the hood, which creates a `batch` requests with at most 1000 objects in it.
+  /// </summary>
+  /// <param name="indexName">The index in which to perform the request.</param>
+  /// <param name="objects">The list of `objects` to store in the given Algolia `indexName`.</param>
+  /// <param name="options">Add extra http header or query parameters to Algolia.</param>
+  /// <param name="cancellationToken">Cancellation Token to cancel the request.</param>
+  /// <typeparam name="T"></typeparam>
+  Task<List<BatchResponse>> SaveObjectsAsync<T>(string indexName, IEnumerable<T> objects, RequestOptions options, CancellationToken cancellationToken = default) where T : class;
+  /// <inheritdoc cref="SaveObjectsAsync{T}(string, IEnumerable{T}, RequestOptions, CancellationToken)"/>
+  List<BatchResponse> SaveObjects<T>(string indexName, IEnumerable<T> objects, RequestOptions options, CancellationToken cancellationToken = default) where T : class;
+
   /// <summary>
   /// Helper: Deletes every records for the given objectIDs. The `chunkedBatch` helper is used under the hood, which creates a `batch` requests with at most 1000 objectIDs in it.
   /// </summary>
@@ -598,6 +610,19 @@ public List<BatchResponse> SaveObjects<T>(string indexName, IEnumerable<T> objec
     CancellationToken cancellationToken = default) where T : class =>
     AsyncHelper.RunSync(() => SaveObjectsAsync(indexName, objects, waitForTasks, batchSize, options, cancellationToken));
 
+  /// <inheritdoc/>
+  public async Task<List<BatchResponse>> SaveObjectsAsync<T>(string indexName, IEnumerable<T> objects,
+    RequestOptions options,
+    CancellationToken cancellationToken = default) where T : class
+  {
+    return await SaveObjectsAsync(indexName, objects, false, 1000, options, cancellationToken).ConfigureAwait(false);
+  }
+
+  /// <inheritdoc/>
+  public List<BatchResponse> SaveObjects<T>(string indexName, IEnumerable<T> objects, RequestOptions options,
+    CancellationToken cancellationToken = default) where T : class =>
+    AsyncHelper.RunSync(() => SaveObjectsAsync(indexName, objects, options, cancellationToken));
+
   /// <inheritdoc/>
   public async Task<List<BatchResponse>> DeleteObjectsAsync(string indexName, IEnumerable<String> objectIDs,
     bool waitForTasks = false,

generators/src/main/java/com/algolia/codegen/cts/AlgoliaCTSGenerator.java

@@ -100,6 +100,7 @@ protected Builder<String, Lambda> addMustacheLambdas() {
     lambdas.put("escapeDollar", new EscapeDollarLambda());
     lambdas.put("escapeQuotes", new EscapeQuotesLambda());
     lambdas.put("escapeSlash", new EscapeSlashLambda());
+    lambdas.put("escapeJSON", new EscapeJSONLambda());
     lambdas.put("replaceBacktick", new ReplaceBacktickLambda());
 
     return lambdas;

generators/src/main/java/com/algolia/codegen/cts/lambda/EscapeJSONLambda.java

@@ -0,0 +1,15 @@
+package com.algolia.codegen.cts.lambda;
+
+import com.samskivert.mustache.Mustache;
+import com.samskivert.mustache.Template;
+import java.io.IOException;
+import java.io.Writer;
+
+public class EscapeJSONLambda implements Mustache.Lambda {
+
+  @Override
+  public void execute(Template.Fragment fragment, Writer writer) throws IOException {
+    String text = fragment.execute();
+    writer.write(text.replace("\\", "\\\\").replace("\"", "\\\""));
+  }
+}

generators/src/main/java/com/algolia/codegen/cts/lambda/EscapeQuotesLambda.java

@@ -10,6 +10,7 @@ public class EscapeQuotesLambda implements Mustache.Lambda {
   @Override
   public void execute(Template.Fragment fragment, Writer writer) throws IOException {
     String text = fragment.execute();
-    writer.write(text.replace("\"", "\\\""));
+    // replaces all occurrences of " that are not preceded by a backslash with \"
+    writer.write(text.replaceAll("(?<!\\\\)\"", "\\\\\""));
   }
 }

generators/src/main/java/com/algolia/codegen/cts/lambda/EscapeSlashLambda.java

@@ -10,6 +10,7 @@ public class EscapeSlashLambda implements Mustache.Lambda {
   @Override
   public void execute(Template.Fragment fragment, Writer writer) throws IOException {
     String text = fragment.execute();
-    writer.write(text.replace("\\", "\\\\"));
+    // replace all backslashes with double backslashes, unless they are followed by a $
+    writer.write(text.replaceAll("\\\\(?!\\$)", "\\\\\\\\"));
   }
 }

generators/src/main/java/com/algolia/codegen/cts/tests/ParametersWithDataType.java

@@ -145,7 +145,7 @@ private Map<String, Object> traverseParams(
     }
 
     testOutput.put("key", paramName);
-    testOutput.put("useAnonymousKey", !paramName.matches("(.*)_[0-9]$") && depth != 0);
+    testOutput.put("useAnonymousKey", !paramName.matches("(.*)_[0-9]+$") && depth != 0);
     testOutput.put("parent", parent);
     testOutput.put("isRoot", "".equals(parent));
     testOutput.put("objectName", getObjectNameForLanguage(baseType));
@@ -191,7 +191,7 @@ private Map<String, Object> traverseParams(
   private Map<String, Object> traverseParamsWithoutSpec(String paramName, Object param, String parent, int depth) throws CTSException {
     Map<String, Object> testOutput = createDefaultOutput();
     testOutput.put("key", paramName);
-    testOutput.put("useAnonymousKey", !paramName.matches("(.*)_[0-9]$") && depth != 0);
+    testOutput.put("useAnonymousKey", !paramName.matches("(.*)_[0-9]+$") && depth != 0);
     testOutput.put("parent", parent);
     testOutput.put("isRoot", "".equals(parent));
     // try to infer the type
@@ -326,7 +326,7 @@ private void handleModel(
       } else {
         while (current.getItems() != null) {
           current = current.getItems();
-          typeName += "Of" + getTypeName(current);
+          typeName += "Of" + Helpers.capitalize(getTypeName(current));
           isList = true;
         }
       }
@@ -492,11 +492,16 @@ private void handlePrimitive(Object param, Map<String, Object> testOutput, IJson
   }
 
   private String getTypeName(IJsonSchemaValidationProperties param) {
+    String typeName = param.getDataType();
     if (param instanceof CodegenModel parameter) {
-      return parameter.classname;
+      typeName = parameter.classname;
     }
 
-    return param.getDataType();
+    if (language.equals("scala") && typeName.equals("List")) {
+      typeName = "Seq";
+    }
+
+    return typeName;
   }
 
   private boolean isString(IJsonSchemaValidationProperties param) {
@@ -592,6 +597,8 @@ private String inferDataType(Object param, CodegenParameter spec, Map<String, Ob
           spec.setIsArray(true);
           // This is just to find the correct path in `handlePrimitive`, but it's not always the
           // real type
+          // FIXME: this set voluntarily the type to string, which will fail
+          // We need to infer the real type
           CodegenProperty baseItems = new CodegenProperty();
           baseItems.dataType = "String";
           spec.setItems(baseItems);
@@ -702,6 +709,10 @@ private IJsonSchemaValidationProperties findMatchingOneOf(Object param, CodegenM
       return maybeMatch;
     }
 
+    if (model == null || model.interfaceModels == null) {
+      return maybeMatch;
+    }
+
     for (CodegenModel oneOf : model.interfaceModels) {
       // Somehow the dataType can be in lower case?
       if (oneOf.dataType.equalsIgnoreCase(paramType)) {

generators/src/main/java/com/algolia/codegen/cts/tests/TestsClient.java

@@ -206,6 +206,8 @@ public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation>
                 }
               }
               stepOut.put("match", paramsType.enhanceParameter(step.expected.match));
+            } else if (!step.type.equals("createClient")) {
+              stepOut.put("useEchoRequester", false);
             }
             steps.add(stepOut);
           }

playground/javascript/node/search.ts

@@ -17,15 +17,13 @@ console.log('version', apiClientVersion, 'requests', requests);
 
 async function testSearch() {
   try {
-    const res = await client.search({
-      requests: 
-      [
-        { indexName: 'foo', hitsPerPage: 2 }
-      ]
-    });
-
-    // @ts-ignore
-    console.log(`[OK]`, res.results[0].hits);
+    const req = await client.setSettings({
+      indexName: 'theIndexName',
+      indexSettings: { distinct: true },
+    })
+
+
+    console.log(`[OK]`, req);
   } catch (e: any) {
     // Instance of
     if (e instanceof ApiError) {

scripts/cts/testServer/algoliaMock.ts

@@ -0,0 +1,24 @@
+import type { Server } from 'http';
+
+import type { Express, Request, Response } from 'express';
+
+import { setupServer } from './index.ts';
+
+// Checks that the client sends a different API key after the first request.
+function addRoutes(app: Express): void {
+  app.post('/1/indexes/:indexName/batch', (req: Request, res: Response) => {
+    res.json({
+      taskID: 333,
+      objectIDs: ['1', '2'],
+    });
+  });
+  app.get('/1/indexes/:indexName/task/:taskID', (req, res) => {
+    res.json({
+      status: 'published',
+    });
+  });
+}
+
+export function algoliaMockServer(): Promise<Server> {
+  return setupServer('algoliaMock', 6686, addRoutes);
+}

scripts/cts/testServer/index.ts

@@ -7,6 +7,7 @@ import { createSpinner } from '../../spinners.ts';
 import type { CTSType } from '../runCts.ts';
 
 import { expect } from 'chai';
+import { algoliaMockServer } from './algoliaMock.ts';
 import { apiKeyServer } from './apiKey.ts';
 import { benchmarkServer } from './benchmark.ts';
 import { chunkWrapperServer } from './chunkWrapper.ts';
@@ -31,6 +32,7 @@ export async function startTestServer(suites: Record<CTSType, boolean>): Promise
       chunkWrapperServer(),
       waitForApiKeyServer(),
       apiKeyServer(),
+      algoliaMockServer(),
     );
   }
   if (suites.benchmark) {