@algolia/wizard 0.5.0 → 0.6.0-rc.51.22

package/docs/algolia-sdk/save-records-scala.md

@@ -0,0 +1,68 @@
+# Save records (algoliasearch-scala v2)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+sbt (`%%` appends the Scala binary version, resolving to
+`com.algolia:algoliasearch-scala_2.13` on Scala 2.13):
+
+```scala
+libraryDependencies += "com.algolia" %% "algoliasearch-scala" % "2.22.0"
+```
+
+The object MUST be `AlgoliaWizardIngest` with an explicit `main` (not `extends
+App`), in the **default package** (no `package` statement) — the wizard runs
+`sbt "runMain AlgoliaWizardIngest"`.
+
+```scala
+import algoliasearch.api.SearchClient
+import algoliasearch.extension.SearchClientExtensions // brings saveObjects into scope
+import scala.concurrent.Await
+import scala.concurrent.ExecutionContext.Implicits.global
+import scala.concurrent.duration.Duration
+
+object AlgoliaWizardIngest {
+  def main(args: Array[String]): Unit = {
+    val indexName = "products"
+    val records: Seq[Map[String, Any]] = Seq(Map("objectID" -> "1", "name" -> "Hot 100"))
+
+    val client = SearchClient(
+      appId = sys.env("ALGOLIA_APPLICATION_ID"),
+      apiKey = sys.env("ALGOLIA_WRITE_API_KEY")
+    )
+    try {
+      Await.result(client.saveObjects(indexName, records), Duration(120, "sec"))
+      println(s"ALGOLIA_WIZARD_RECORD_COUNT=${records.size}")
+    } finally client.close() // else okhttp's non-daemon threads hang the JVM
+  }
+}
+```
+
+Future-based API: a script must `Await.result` with a generous timeout, and an
+implicit `ExecutionContext` must be in scope.
+
+```scala
+// objects: Seq[Map[String, Any]] or case classes, each carrying an objectID
+def saveObjects(indexName: String, objects: Seq[Any], waitForTasks: Boolean = false,
+    batchSize: Int = 1000, requestOptions: Option[RequestOptions] = None)(
+    implicit ec: ExecutionContext): Future[Seq[BatchResponse]]
+```
+
+Yields one `BatchResponse` (`taskID`, `objectIDs`) per batch of 1,000, not per record.
+
+Read records from a JSON file (json4s ships with the client):
+
+```scala
+import algoliasearch.search.JsonSupport
+import org.json4s.native.JsonMethods
+import org.json4s.jvalue2extractable
+import scala.io.Source
+import scala.util.Using
+
+implicit val formats: org.json4s.Formats = JsonSupport.format // required by extract
+val records = JsonMethods
+  .parse(Using(Source.fromFile("records.json"))(_.mkString).get)
+  .extract[Seq[Map[String, Any]]]
+```
+
+After a successful ingest print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` (n = records
+read, not the returned `Seq` size) as the last stdout line.

package/docs/algolia-sdk/save-records-swift.md

@@ -0,0 +1,88 @@
+# Save records (algoliasearch-client-swift v9)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+The generated script is a standalone SwiftPM executable package at
+`.algolia-wizard/Ingest` (`Package.swift` + `Sources/Ingest/main.swift`), run with
+`swift run --package-path .algolia-wizard/Ingest`.
+
+```swift
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "Ingest",
+    platforms: [.macOS(.v13)],
+    products: [.executable(name: "Ingest", targets: ["Ingest"])],
+    dependencies: [
+        .package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "9.0.0"),
+    ],
+    targets: [
+        .executableTarget(name: "Ingest", dependencies: [
+            .product(name: "AlgoliaSearch", package: "algoliasearch-client-swift"),
+            .product(name: "AlgoliaCore", package: "algoliasearch-client-swift"),
+        ]),
+    ]
+)
+```
+
+Exactly one executable product, so `swift run --package-path` needs no target name.
+`platforms:` must be declared (the client requires macOS 11+); it is ignored on
+Linux. `package:` is the repo name, not the manifest's `AlgoliaSearchClient`.
+
+`main.swift` top-level code can't propagate a thrown error — wrap calls in `do`/`catch`.
+
+```swift
+import Foundation
+#if canImport(AlgoliaCore)
+    import AlgoliaCore
+#endif
+import AlgoliaSearch
+
+let env = ProcessInfo.processInfo.environment
+guard let appID = env["ALGOLIA_APPLICATION_ID"],
+      let writeKey = env["ALGOLIA_WRITE_API_KEY"]
+else {
+    FileHandle.standardError.write(Data("missing Algolia credentials\n".utf8))
+    exit(1)
+}
+let indexName = "products"
+
+do {
+    let client = try SearchClient(appID: appID, apiKey: writeKey)
+    let records: [AnyCodable] = [
+        ["objectID": "1", "name": "Adam"],
+        ["objectID": "2", "name": "Benoit"],
+    ]
+    let responses = try await client.saveObjects(
+        indexName: indexName, objects: records, waitForTasks: true
+    )
+    FileHandle.standardError.write(Data("batches: \(responses.count)\n".utf8))
+    print("ALGOLIA_WIZARD_RECORD_COUNT=\(records.count)")
+} catch {
+    FileHandle.standardError.write(Data("\(error)\n".utf8))
+    exit(1)
+}
+```
+
+```swift
+func saveObjects(
+    indexName: String, objects: [some Encodable], waitForTasks: Bool = false,
+    batchSize: Int = 1000, requestOptions: RequestOptions? = nil
+) async throws -> [BatchResponse]
+```
+
+Records need an `objectID`; batching in 1,000s is automatic. Returns an **array**
+of `BatchResponse` (`taskID`, `objectIDs`), one per batch. `objects` is
+`[some Encodable]` — one homogeneous element type, so use `[AnyCodable]` (from
+`AlgoliaCore`) for arbitrary JSON records.
+
+Read records from a JSON file:
+
+```swift
+let data = try Data(contentsOf: URL(fileURLWithPath: "records.json"))
+let records = try JSONDecoder().decode([AnyCodable].self, from: data)
+```
+
+After a successful ingest, print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` as the last
+stdout line; send all other logging to stderr so nothing follows it on stdout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.5.0",
+  "version": "0.6.0-rc.51.22",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {