DOC-9740 - Use refactored shared partials (#190)

https://issues.couchbase.com/browse/DOC-9740

[Page Preview](https://maria-robobug.github.io/DOC-9740/nodejs-sdk/DOC-9740/howtos/distributed-acid-transactions-from-the-sdk.html)

* Use the changes made in [docs-sdk-common](couchbase/docs-sdk-common#45).

* Included the `:page-toclevels: 2` attribute to improve UI (there are
  alot of sections in this doc, seems helpful for the user).

* Added `acid-transactions-attributes.adoc` for SDK specific attributes (used by docs-sdk-common partials).

Other SDKs to follow...

Author: maria-robobug

modules/howtos/examples/transactions-example.ts

@@ -68,7 +68,7 @@ async function main() {
     await cluster.transactions().run(async (ctx) => {
       // 'ctx' is a TransactionAttemptContext which permits getting, inserting,
       // removing and replacing documents, performing N1QL queries, etc.
-      // … Your transction logic here …
+      // … Your transaction logic here …
       // Committing is implicit at the end of the lambda.
     })
   } catch (error) {
@@ -320,8 +320,8 @@ async function queryInsert() {
   let collection = await getCollection()
   // tag::queryInsert[]
   cluster.transactions().run(async (ctx) => {
-    ctx.query("INSERT INTO `default` VALUES ('doc', {'hello':'world'})")
-    const st = "SELECT `default`.* FROM `default` WHERE META().id = 'doc'"
+    ctx.query("INSERT INTO `default` VALUES ('doc', {'hello':'world'})") // <1>
+    const st = "SELECT `default`.* FROM `default` WHERE META().id = 'doc'" // <2>
     const qr = await ctx.query(st)
   })
   // end::queryInsert[]

modules/howtos/pages/distributed-acid-transactions-from-the-sdk.adoc

@@ -3,8 +3,10 @@
 :navtitle: ACID Transactions
 :page-partial:
 :page-topic-type: howto
+:page-toclevels: 2
 
 include::project-docs:partial$attributes.adoc[]
+include::partial$acid-transactions-attributes.adoc[]
 
 [abstract]
 {description}
@@ -37,30 +39,24 @@ include::example$transactions-example.ts[tag=config,indent=0]
 
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=config]
 
-// TODO: this partial needs to change a bit, owing to library references.
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=creating]
 
 [source,typescript]
 ----
 include::example$transactions-example.ts[tag=create,indent=0]
 ----
 
-// TODO: this partial may need to be reviewed
-// TODO: see https://docs.couchbase.com/java-sdk/current/howtos/distributed-acid-transactions-from-the-sdk.html#:~:text=The%20lambda%20gets%20passed%20an%20AttemptContext%20object%2C%20generally%20referred%20to%20as%20ctx%20here.
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=lambda-ctx]
 
-== Examples
-A code example is worth a thousand words, so here is a quick summary of the main transaction operations.
-They are described in more detail below. 
+// Examples
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=examples-intro]
 
 [source,typescript]
 ----
 include::example$transactions-example.ts[tag=examples,indent=0]
 ----
 
-// TODO: this partial references things that are Java implmentation specific
-//       like a Transactions object
-include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=mechanics]
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=mechanics;!library-cleanup-process]
 
 
 == Key-Value Mutations
@@ -103,7 +99,7 @@ From a transaction context you may get a document:
 include::example$transactions-example.ts[tag=get,indent=0]
 ----
 
-`get` will cause the transaction to fail with `TransactionFailed` (after rolling back any changes, of course).
+`get` will cause the transaction to fail with `TransactionFailedError` (after rolling back any changes, of course).
 It is provided as a convenience method so the developer does not have to check the `Optional` if the document must exist for the transaction to succeed.
 
 Gets will 'read your own writes', e.g. this will succeed:
@@ -113,15 +109,16 @@ Gets will 'read your own writes', e.g. this will succeed:
 include::example$transactions-example.ts[tag=getReadOwnWrites,indent=0]
 ----
 
-include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=query-intro]
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=query-intro;!library-begin-transaction]
 
 === Using N1QL
+
 If you already use N1QL from the Node.js SDK, then its use in transactions is very similar.
-it returns the same `QueryResult` you are used to, and takes most of the same options.
+It returns the same `QueryResult` you are used to, and takes most of the same options.
 
 You must take care to write `ctx.query()` inside the lambda however, rather than `cluster.query()` or `scope.query()`.
 
-An example of SELECTing some rows from the `travel-sample` bucket:
+An example of selecting some rows from the `travel-sample` bucket:
 
 [source,typescript]
 ----
@@ -152,53 +149,63 @@ include::example$transactions-example.ts[tag=queryExamplesComplex,indent=0]
 ----
 
 === Read Your Own Writes
+
 As with Key-Value operations, N1QL queries support Read Your Own Writes.
 
-This example shows INSERTing a document and then SELECTing it again.
+This example shows inserting a document and then selecting it again.
 
 [source,typescript]
 ----
 include::example$transactions-example.ts[tag=queryInsert,indent=0]
 ----
+
 <1> The inserted document is only staged at this point. as the transaction has not yet committed.
 Other transactions, and other non-transactional actors, will not be able to see this staged insert yet.
 <2> But the SELECT can, as we are reading a mutation staged inside the same transaction.
 
 === Mixing Key-Value and N1QL
+
 Key-Value operations and queries can be freely intermixed, and will interact with each other as you would expect.
 
 In this example we insert a document with Key-Value, and read it with a SELECT.
+
 [source,typescript]
 ----
 include::example$transactions-example.ts[tag=queryRyow,indent=0]
 ----
+
 <1> As with the 'Read Your Own Writes' example, here the insert is only staged, and so it is not visible to other transactions or non-transactional actors.
 <2> But the SELECT can view it, as the insert was in the same transaction.
 
 === Query Options
-Query options can be provided via `TransactionsQueryOptions`, which provides a subset of the options in the Node.js SDK's `QueryOptions`.
+
+Query options can be provided via `TransactionQueryOptions`, which provides a subset of the options in the Node.js SDK's `QueryOptions`.
 
 [source,typescript]
 ----
 include::example$transactions-example.ts[tag=queryOptions,indent=0]
 ----
 
-// TODO: check this partial to see if it matches up across SDKs.  otherwise, make it a table?
-include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=query-options]
+The supported options are:
+
+* parameters 
+* scanConsistency 
+* clientContextId
+* scanWait
+* scanCap
+* pipelineBatch
+* pipelineCap
+* profile
+* readOnly
+* adhoc
+* raw
 
 // TODO: this does not seem to exist for Node.js.  should it?
 //See the xref:howtos:n1ql-queries-with-sdk.adoc#query-options[QueryOptions documentation] for details on these.
+// Remove the API link below when we have the query options page available.
+See the https://docs.couchbase.com/sdk-api/couchbase-node-client/interfaces/TransactionQueryOptions.html[API reference] for more details on these.
 
-// TODO: Replace the section below with this when we ensure that the shared partials in common are truly generic.
-// include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=query-perf]
-=== Query Performance Advice
-This section is optional reading, and only for those looking to maximize transactions performance.
-
-After the first query statement in a transaction, subsequent Key-Value operations in the lambda are converted into N1QL and executed by the query service rather than the Key-Value data service.
-The operation will behave identically, and this implementation detail can largely be ignored, except for this caveat:
-
-* These converted Key-Value operations are likely to be slightly slower, as the query service is optimised for statements involving multiple documents.
-Those looking for the maximum possible performance are recommended to put Key-Value operations before the first query in the lambda, if possible.
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=query-perf]
 
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=query-single]
 
@@ -207,6 +214,7 @@ include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=query-si
 include::example$transactions-example.ts[tag=querySingle,indent=0]
 ----
 
+// TODO: Add the below when this is implemented for Node.js transactions.
 // You can also run a single query transaction against a particular `Scope` (these examples will exclude the full error handling for brevity):
 //
 // [source,typescript]
@@ -240,16 +248,11 @@ An asynchronous cleanup process ensures that once the transaction reaches the co
 // == A Full Transaction Example
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=example]
 
-// TODO: need to create this
-// A complete version of this example is available on our https://github.com/couchbaselabs/couchbase-transactions-nodejs-examples[GitHub transactions examples page].
-
 [source,typescript]
 ----
 include::example$transactions-example.ts[tag=full,indent=0]
 ----
 
-// TODO: this partial has some Java specific things in it
-// concurrency
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=concurrency]
 
 // TODO: this is to identify violations of cooperative, not known if this is available in node/cb++
@@ -264,7 +267,7 @@ include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=concurre
 
 == Rollback
 
-If an exception is thrown, either by the application from the lambda, or by the transactions library, then that attempt is rolled back.
+If an exception is thrown, either by the application from the lambda, or by the transaction internally, then that attempt is rolled back.
 The transaction logic may or may not be retried, depending on the exception.
 //- see link:#error-handling[Error handling and logging].
 
@@ -284,18 +287,21 @@ After a transaction is rolled back, it cannot be committed, no further operation
 //  Error Handling
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=error]
 
+There are three errors that Couchbase transactions can raise to the application: `TransactionFailedError`, `TransactionExpiredError` and `TransactionCommitAmbiguousError`.
 
-// TODO: this partial below has a lot of Java specifics in it
-//  txnfailed
-//include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=txnfailed]
+// txnfailed
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=txnfailed]
 
+// TODO: Need an equivalent typescript snippet for the below
 //[source,java]
 //----
 //include::example$TransactionsExample.java[tag=config-expiration,indent=0]
 //----
 
-//include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=txnfailed1]
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=txnfailed1]
 
+// TODO: Double check if this will be added in future.
+// Doesn't seem to be available for the Node SDK.
 //Similar to `TransactionResult`, `SingleQueryTransactionResult` also has an `unstagingComplete()` method.
 
 === Full Error Handling Example
@@ -307,14 +313,27 @@ Pulling all of the above together, this is the suggested best practice for error
 include::example$transactions-example.ts[tag=full-error-handling,indent=0]
 ----
 
-// TODO: this partial below has reference to a Transactions object, which is no longer the case going forward
-// include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=cleanup]
+// Asynchronous Cleanup
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=cleanup;!library-cleanup-buckets]
+
+[#tuning-cleanup]
+=== Configuring Cleanup
+
+The cleanup settings can be configured as so:
+
+[options="header"]
+|===
+|Setting|Default|Description
+|`cleanupWindow`|60 seconds|This determines how long a cleanup 'run' is; that is, how frequently this client will check its subset of ATR documents.  It is perfectly valid for the application to change this setting, which is at a conservative default.  Decreasing this will cause expiration transactions to be found more swiftly (generally, within this cleanup window), with the tradeoff of increasing the number of reads per second used for the scanning process.
+|`disableLostAttemptCleanup`|true|This is the thread that takes part in the distributed cleanup process described above, that cleans up expired transactions created by any client.  It is strongly recommended that it is left enabled.
+|`disableClientAttemptCleanup`|true|This thread is for cleaning up transactions created just by this client.  The client will preferentially aim to send any transactions it creates to this thread, leaving transactions for the distributed cleanup process only when it is forced to (for example, on an application crash).  It is strongly recommended that it is left enabled.
+|===
 
 === Monitoring Cleanup
 
 To monitor cleanup, increase the verbosity on the logging.
 
-//TODO: once events are available, re-add the below
+//TODO: once events are available, re-add the below with relevant examples
 //[source,java]
 //----
 //include::example$TransactionsExample.java[tag=cleanup-events,indent=0]
@@ -380,7 +399,7 @@ There are two rules the application needs to follow:
 
 * The first mutation must be performed alone, in serial.
 This is because the first mutation also triggers the creation of metadata for the transaction.
-* All concurrent operations must be allowed to complete fully, so the transaction library can track which operations need to be rolled back in the event of failure.
+* All concurrent operations must be allowed to complete fully, so the transaction can track which operations need to be rolled back in the event of failure.
 This means the application must 'swallow' the error, but record that an error occurred, and then at the end of the concurrent operations, if an error occurred, throw an error to cause the transaction to retry.
 
 // TODO: update this for node
@@ -437,5 +456,4 @@ This means the application must 'swallow' the error, but record that an error oc
 //The transaction expiry timer (which is configurable) will begin ticking once the transaction starts, and is not paused while the transaction is in a deferred state.
 
 
-// TODO: this partial points to the java examples repo
 include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=further]

modules/howtos/partials/acid-transactions-attributes.adoc

@@ -0,0 +1,23 @@
+// These attributes are used in sdk::shared:partial$acid-transactions.adoc 
+
+// intro
+:durability-exception: pass:q[`DurabilityImpossibleError`]
+
+
+// creating
+:lambda-attempt-ctx: pass:q[a `TransactionAttemptContext`]
+:collection-insert: pass:q[`collection.insert()`]
+:ctx-insert: pass:q[`ctx.insert()`]
+
+
+// error
+:ctx-get: pass:q[`ctx.get()`]
+:error-unstaging-complete: pass:q[`TransactionResult.unstagingComplete` property]
+
+
+// txnfailed
+:transaction-failed: TransactionFailedError
+:transaction-expired: TransactionExpiredError
+:transaction-config: TransactionsConfig
+:transaction-commit-ambiguous: TransactionCommitAmbiguous
+:txnfailed-unstaging-complete: TransactionResult.unstagingComplete