@attocash/commons-test 6.3.2 → 6.5.0

package/README.md

@@ -0,0 +1,169 @@
+# @attocash/commons-test
+
+[![npm version](https://img.shields.io/npm/v/@attocash/commons-test.svg)](https://www.npmjs.com/package/@attocash/commons-test)
+[![license](https://img.shields.io/github/license/attocash/commons.svg)](https://github.com/attocash/commons/blob/main/LICENSE)
+
+Test utilities for Atto JavaScript and TypeScript integrations.
+
+`@attocash/commons-test` provides local mock services for applications that use `@attocash/commons-js`. It starts a real Atto node container with a MySQL container and a real Work Server container, then exposes their mapped URLs so your tests can use the normal node, worker, wallet, and monitor clients.
+
+## Install
+
+```sh
+npm install --save-dev @attocash/commons-test
+npm install @attocash/commons-js
+```
+
+This package is published as ESM and includes TypeScript declarations.
+
+## Requirements
+
+- Node.js 18 or newer is recommended.
+- Docker or Podman must be installed and running.
+- The test process must be allowed to pull and run containers.
+- Use ESM imports. In Node.js files, use `.mjs` or set `"type": "module"`.
+
+Node.js examples that use the Atto clients should expose `require` for the underlying runtime:
+
+```js
+import { createRequire } from 'node:module'
+
+globalThis.require = createRequire(import.meta.url)
+```
+
+## What It Provides
+
+- `AttoNodeMockAsyncBuilder`: starts a local Atto node backed by MySQL.
+- `AttoWorkerMockAsyncBuilder`: starts a local Work Server.
+- `baseUrl` properties that plug directly into `AttoNodeClientAsyncBuilder` and `AttoWorkerAsyncBuilder`.
+- A generated local genesis transaction so tests can start with a funded account.
+- Builder options for container names, images, MySQL settings, and custom genesis transactions.
+
+## Quick Example
+
+```js
+import { createRequire } from 'node:module'
+import {
+  AttoAmount,
+  AttoMnemonic,
+  AttoNodeClientAsyncBuilder,
+  AttoUnit,
+  AttoWalletAsyncBuilder,
+  AttoWorkerAsyncBuilder,
+  toAttoIndex,
+  toPrivateKey,
+  toSeedAsync,
+} from '@attocash/commons-js'
+import {
+  AttoNodeMockAsyncBuilder,
+  AttoWorkerMockAsyncBuilder,
+} from '@attocash/commons-test'
+
+globalThis.require = createRequire(import.meta.url)
+
+const mnemonic = AttoMnemonic.generate()
+const seed = await toSeedAsync(mnemonic)
+const genesisPrivateKey = toPrivateKey(seed, toAttoIndex(0))
+
+const nodeMock = await new AttoNodeMockAsyncBuilder(genesisPrivateKey).build()
+const workerMock = await new AttoWorkerMockAsyncBuilder().build()
+
+try {
+  await nodeMock.start()
+  await workerMock.start()
+
+  const nodeClient = new AttoNodeClientAsyncBuilder(nodeMock.baseUrl).build()
+  const worker = new AttoWorkerAsyncBuilder(workerMock.baseUrl).build()
+
+  const wallet = new AttoWalletAsyncBuilder(nodeClient, worker)
+    .signerProviderSeed(seed)
+    .build()
+
+  const sender = toAttoIndex(0)
+  const receiver = toAttoIndex(1)
+
+  await wallet.openAccount(sender)
+  await wallet.openAccount(receiver)
+
+  const receiverAddress = await wallet.getAddress(receiver)
+  const amount = AttoAmount.from(AttoUnit.ATTO, '1')
+  const transaction = await wallet.sendByIndex(sender, receiverAddress, amount, null)
+
+  console.log(`Published ${transaction.hash}`)
+} finally {
+  nodeMock.close()
+  workerMock.close()
+}
+```
+
+## Custom Images and Names
+
+Use builder methods when a test suite needs pinned images, isolated container names, or custom MySQL settings.
+
+```js
+const nodeMock = await new AttoNodeMockAsyncBuilder(genesisPrivateKey)
+  .name('atto-node-test')
+  .image('ghcr.io/attocash/node:live')
+  .mysqlImage('mysql:8.4')
+  .dbName('node')
+  .dbUser('root')
+  .dbPassword('root')
+  .build()
+
+const workerMock = await new AttoWorkerMockAsyncBuilder()
+  .name('atto-worker-test')
+  .image('ghcr.io/attocash/work-server:cpu')
+  .build()
+```
+
+## Lifecycle
+
+Always close mocks in `finally` or your test framework's teardown hook.
+
+```js
+let nodeMock
+let workerMock
+
+beforeAll(async () => {
+  nodeMock = await new AttoNodeMockAsyncBuilder(genesisPrivateKey).build()
+  workerMock = await new AttoWorkerMockAsyncBuilder().build()
+
+  await nodeMock.start()
+  await workerMock.start()
+})
+
+afterAll(() => {
+  nodeMock?.close()
+  workerMock?.close()
+})
+```
+
+`baseUrl` is available only after `start()` has completed.
+
+## Full Example
+
+The repository includes a runnable JavaScript example that uses `@attocash/commons-test` with `@attocash/commons-js` to start mock services, create a wallet, open accounts, send transactions, and listen to monitors:
+
+- [examples/js-client](https://github.com/attocash/commons/tree/main/examples/js-client)
+
+## API Summary
+
+| Export | Purpose |
+| --- | --- |
+| `AttoNodeMockAsyncBuilder` | Builds a node mock backed by an Atto node container and a MySQL container. |
+| `AttoNodeMockAsync` | Starts, closes, and exposes the node mock `baseUrl` and `genesisTransaction`. |
+| `AttoWorkerMockAsyncBuilder` | Builds a Work Server mock container. |
+| `AttoWorkerMockAsync` | Starts, closes, and exposes the worker mock `baseUrl`. |
+| `AttoNodeMockConfiguration` | Configuration object for lower-level Kotlin/JVM use. |
+
+## Documentation
+
+- [Atto documentation](https://atto.cash/docs)
+- [Integration overview](https://atto.cash/docs/integration)
+- [Node integration](https://atto.cash/docs/integration/node)
+- [Work Server integration](https://atto.cash/docs/integration/work-server)
+- [Atto Commons repository](https://github.com/attocash/commons)
+
+## License
+
+[BSD 3-Clause](https://github.com/attocash/commons/blob/main/LICENSE)

package/commons-commons-test.d.mts

@@ -10,7 +10,9 @@ export declare namespace KtMap {
     function fromJsMap<K, V>(map: ReadonlyMap<K, V>): KtMap<K, V>;
 }
 /** @deprecated  */
-export declare const initHook: { get(): any; };
+export declare const initHook: {
+    get(): any;
+};
 export declare class AttoAccount implements HeightSupport, AddressSupport {
     constructor(publicKey: AttoPublicKey, network: AttoNetwork, version: AttoVersion, algorithm: AttoAlgorithm, height: AttoHeight, balance: AttoAmount, lastTransactionHash: AttoHash, lastTransactionTimestamp: AttoInstant, representativeAlgorithm: AttoAlgorithm, representativePublicKey: AttoPublicKey);
     get publicKey(): AttoPublicKey;
@@ -29,7 +31,7 @@ export declare class AttoAccount implements HeightSupport, AddressSupport {
     toString(): string;
     hashCode(): number;
     equals(other: Nullable<any>): boolean;
-    readonly __doNotUseOrImplementIt: HeightSupport["__doNotUseOrImplementIt"] & AddressSupport["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: AddressSupport["__doNotUseOrImplementIt"] & HeightSupport["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoAccount {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -66,7 +68,7 @@ export declare class AttoAccountEntry implements HeightSupport, AddressSupport {
     toString(): string;
     hashCode(): number;
     equals(other: Nullable<any>): boolean;
-    readonly __doNotUseOrImplementIt: HeightSupport["__doNotUseOrImplementIt"] & AddressSupport["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: AddressSupport["__doNotUseOrImplementIt"] & HeightSupport["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoAccountEntry {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -117,14 +119,14 @@ export declare abstract class AttoAlgorithm {
         get name(): "V1";
         get ordinal(): 0;
     };
+    static values(): [typeof AttoAlgorithm.V1];
+    static valueOf(value: string): AttoAlgorithm;
     get name(): "V1";
     get ordinal(): 0;
     get code(): any/* UByte */;
     get privateKeySize(): number;
     get publicKeySize(): number;
     get hashSize(): number;
-    static values(): Array<AttoAlgorithm>;
-    static valueOf(value: string): AttoAlgorithm;
 }
 export declare namespace AttoAlgorithm {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -153,11 +155,11 @@ export declare abstract class AttoUnit {
         get name(): "RAW";
         get ordinal(): 1;
     };
+    static values(): [typeof AttoUnit.ATTO, typeof AttoUnit.RAW];
+    static valueOf(value: string): AttoUnit;
     get name(): "ATTO" | "RAW";
     get ordinal(): 0 | 1;
     get prefix(): string;
-    static values(): Array<AttoUnit>;
-    static valueOf(value: string): AttoUnit;
 }
 export declare namespace AttoUnit {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -218,10 +220,10 @@ export declare abstract class AttoBlockType {
         get name(): "CHANGE";
         get ordinal(): 4;
     };
+    static values(): [typeof AttoBlockType.UNKNOWN, typeof AttoBlockType.OPEN, typeof AttoBlockType.RECEIVE, typeof AttoBlockType.SEND, typeof AttoBlockType.CHANGE];
+    static valueOf(value: string): AttoBlockType;
     get name(): "UNKNOWN" | "OPEN" | "RECEIVE" | "SEND" | "CHANGE";
     get ordinal(): 0 | 1 | 2 | 3 | 4;
-    static values(): Array<AttoBlockType>;
-    static valueOf(value: string): AttoBlockType;
 }
 export declare namespace AttoBlockType {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -266,7 +268,7 @@ export declare interface AttoBlock extends HeightSupport, AddressSupport, AttoHa
     isValid(): boolean;
     readonly __doNotUseOrImplementIt: {
         readonly "cash.atto.commons.AttoBlock": unique symbol;
-    } & HeightSupport["__doNotUseOrImplementIt"] & AddressSupport["__doNotUseOrImplementIt"] & AttoHashable["__doNotUseOrImplementIt"] & AttoSerializable["__doNotUseOrImplementIt"];
+    } & AttoSerializable["__doNotUseOrImplementIt"] & AttoHashable["__doNotUseOrImplementIt"] & AddressSupport["__doNotUseOrImplementIt"] & HeightSupport["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoBlock {
     abstract class Companion extends KtSingleton<Companion.$metadata$.constructor>() {
@@ -326,7 +328,7 @@ export declare class AttoSendBlock implements AttoBlock, PreviousSupport {
     equals(other: Nullable<any>): boolean;
     isValid(): boolean;
     toByteArray(): Int8Array;
-    readonly __doNotUseOrImplementIt: AttoBlock["__doNotUseOrImplementIt"] & PreviousSupport["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: PreviousSupport["__doNotUseOrImplementIt"] & AttoBlock["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoSendBlock {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -367,7 +369,7 @@ export declare class AttoReceiveBlock implements AttoBlock, PreviousSupport, Rec
     validate(): AttoValidation;
     isValid(): boolean;
     toByteArray(): Int8Array;
-    readonly __doNotUseOrImplementIt: AttoBlock["__doNotUseOrImplementIt"] & PreviousSupport["__doNotUseOrImplementIt"] & ReceiveSupport["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: ReceiveSupport["__doNotUseOrImplementIt"] & PreviousSupport["__doNotUseOrImplementIt"] & AttoBlock["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoReceiveBlock {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -410,7 +412,7 @@ export declare class AttoOpenBlock implements AttoBlock, ReceiveSupport, Represe
     validate(): AttoValidation;
     isValid(): boolean;
     toByteArray(): Int8Array;
-    readonly __doNotUseOrImplementIt: AttoBlock["__doNotUseOrImplementIt"] & ReceiveSupport["__doNotUseOrImplementIt"] & RepresentativeSupport["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: RepresentativeSupport["__doNotUseOrImplementIt"] & ReceiveSupport["__doNotUseOrImplementIt"] & AttoBlock["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoOpenBlock {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -452,7 +454,7 @@ export declare class AttoChangeBlock implements AttoBlock, PreviousSupport, Repr
     validate(): AttoValidation;
     isValid(): boolean;
     toByteArray(): Int8Array;
-    readonly __doNotUseOrImplementIt: AttoBlock["__doNotUseOrImplementIt"] & PreviousSupport["__doNotUseOrImplementIt"] & RepresentativeSupport["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: RepresentativeSupport["__doNotUseOrImplementIt"] & PreviousSupport["__doNotUseOrImplementIt"] & AttoBlock["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoChangeBlock {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -657,12 +659,12 @@ export declare abstract class AttoNetwork {
         get name(): "UNKNOWN";
         get ordinal(): 4;
     };
+    static values(): [typeof AttoNetwork.LIVE, typeof AttoNetwork.BETA, typeof AttoNetwork.DEV, typeof AttoNetwork.LOCAL, typeof AttoNetwork.UNKNOWN];
+    static valueOf(value: string): AttoNetwork;
     get name(): "LIVE" | "BETA" | "DEV" | "LOCAL" | "UNKNOWN";
     get ordinal(): 0 | 1 | 2 | 3 | 4;
     get code(): any/* UByte */;
     get thresholdIncreaseFactor(): bigint;
-    static values(): Array<AttoNetwork>;
-    static valueOf(value: string): AttoNetwork;
 }
 export declare namespace AttoNetwork {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -846,7 +848,7 @@ export declare class AttoTransaction implements HeightSupport, AddressSupport, A
     hashCode(): number;
     equals(other: Nullable<any>): boolean;
     toByteArray(): Int8Array;
-    readonly __doNotUseOrImplementIt: HeightSupport["__doNotUseOrImplementIt"] & AddressSupport["__doNotUseOrImplementIt"] & AttoSerializable["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: AttoSerializable["__doNotUseOrImplementIt"] & AddressSupport["__doNotUseOrImplementIt"] & HeightSupport["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoTransaction {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -903,7 +905,7 @@ export declare class AttoVote implements AttoHashable, AttoSerializable {
     hashCode(): number;
     equals(other: Nullable<any>): boolean;
     toByteArray(): Int8Array;
-    readonly __doNotUseOrImplementIt: AttoHashable["__doNotUseOrImplementIt"] & AttoSerializable["__doNotUseOrImplementIt"];
+    readonly __doNotUseOrImplementIt: AttoSerializable["__doNotUseOrImplementIt"] & AttoHashable["__doNotUseOrImplementIt"];
 }
 export declare namespace AttoVote {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -1085,18 +1087,24 @@ export declare class AttoNodeClientAsync /* implements AutoCloseable */ {
     get client(): any/* AttoNodeClient */;
     accountByPublicKey(publicKey: AttoPublicKey): Promise<Nullable<AttoAccount>>;
     accountByAddresses(addresses: Array<AttoAddress>): Promise<Array<AttoAccount>>;
+    onAccountAll(onAccount: (p0: AttoAccount) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onAccountByPublicKey(publicKey: AttoPublicKey, onAccount: (p0: AttoAccount) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onAccountByAddresses(addresses: Array<AttoAddress>, onAccount: (p0: AttoAccount) => void, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onReceivableByPublicKey(publicKey: AttoPublicKey, minAmount: AttoAmount | undefined, onReceivable: (p0: AttoReceivable) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onReceivableByAddresses(addresses: Array<AttoAddress>, minAmount: AttoAmount | undefined, onReceivable: (p0: AttoReceivable) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     accountEntry(hash: AttoHash): Promise<AttoAccountEntry>;
+    onAccountEntryAll(onAccountEntry: (p0: AttoAccountEntry) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
+    onAccountEntryByHash(hash: AttoHash, onAccountEntry: (p0: AttoAccountEntry) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onAccountEntryByPublicKey(publicKey: AttoPublicKey, fromHeight: AttoHeight | undefined, toHeight: Nullable<AttoHeight> | undefined, onAccountEntry: (p0: AttoAccountEntry) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onAccountEntryByHeightSearch(heightSearch: HeightSearch, onAccountEntry: (p0: AttoAccountEntry) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     transaction(hash: AttoHash): Promise<AttoTransaction>;
+    onTransactionAll(onTransaction: (p0: AttoTransaction) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
+    onTransactionByHash(hash: AttoHash, onTransaction: (p0: AttoTransaction) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onTransactionByPublicKey(publicKey: AttoPublicKey, fromHeight: AttoHeight | undefined, toHeight: Nullable<AttoHeight> | undefined, onTransaction: (p0: AttoTransaction) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onTransactionByHeightSearch(heightSearch: HeightSearch, onTransaction: (p0: AttoTransaction) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     now(): Promise<AttoInstant>;
     publish(transaction: AttoTransaction): Promise<void>;
+    voterWeight(address: AttoAddress): Promise<any/* AttoVoterWeight */>;
 }
 export declare namespace AttoNodeClientAsync {
     /** @deprecated $metadata$ is used for internal purposes, please don't use it in your code, because it can be removed at any moment */
@@ -1121,6 +1129,7 @@ export declare class AttoAccountMonitorAsync /* implements AutoCloseable */ {
     monitorAddressArray(addresses: Array<AttoAddress>): Promise<void>;
     monitorAddress(address: AttoAddress): Promise<void>;
     getAccounts(): Promise<Array<AttoAccount>>;
+    onAccount(onAccount: (p0: AttoAccount) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
     onReceivable(minAmount: AttoAmount | undefined, onReceivable: (p0: AttoReceivable) => any, onCancel: (p0: Nullable<Error>/* Nullable<Exception> */) => any): any/* AttoJob */;
 }
 export declare namespace AttoAccountMonitorAsync {