@no-witness-labs/midday-sdk 0.1.2 → 0.2.0

package/dist/devnet/Cluster.d.ts

@@ -0,0 +1,282 @@
+/**
+ * DevNet cluster orchestration.
+ *
+ * Manages the lifecycle of a complete Midnight development environment
+ * consisting of a node, indexer, and proof server.
+ *
+ * ## API Design
+ *
+ * This module uses an **instance-based pattern**:
+ *
+ * - **Stateful**: A Cluster holds references to Docker containers
+ * - **Instance methods**: `cluster.start()`, `cluster.stop()`, etc.
+ * - **Effect-first**: Internal implementation uses Effect
+ * - **Promise wrapper**: `.effect` namespace exposes raw Effects
+ *
+ * ### Usage Patterns
+ *
+ * ```typescript
+ * // Promise user (majority)
+ * const cluster = await Cluster.make();
+ * await cluster.start();           // instance method
+ * const config = cluster.networkConfig;  // accessor
+ * await cluster.stop();
+ *
+ * // Effect user (composable)
+ * const cluster = yield* Cluster.effect.make();
+ * yield* cluster.effect.start();   // raw Effect access
+ *
+ * // Effect DI user (dependency injection)
+ * const cluster = yield* ClusterService;
+ * yield* cluster.effect.start();
+ * // provide with: Effect.provide(Cluster.Live) or Cluster.layer({ ... })
+ * ```
+ *
+ * @since 0.2.0
+ * @module
+ */
+import { Context, Effect, Layer } from 'effect';
+import type { NetworkConfig } from '../Config.js';
+import type { DevNetConfig, ResolvedDevNetConfig } from './Config.js';
+import * as Container from './Container.js';
+import { ClusterError } from './errors.js';
+/**
+ * Raw cluster data (containers and config).
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface ClusterData {
+    /** The Midnight node container */
+    readonly node: Container.Container;
+    /** The indexer container */
+    readonly indexer: Container.Container;
+    /** The proof server container */
+    readonly proofServer: Container.Container;
+    /** The resolved configuration */
+    readonly config: ResolvedDevNetConfig;
+}
+/**
+ * A DevNet cluster instance with lifecycle methods.
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface Cluster {
+    /** The Midnight node container */
+    readonly node: Container.Container;
+    /** The indexer container */
+    readonly indexer: Container.Container;
+    /** The proof server container */
+    readonly proofServer: Container.Container;
+    /** The resolved configuration */
+    readonly config: ResolvedDevNetConfig;
+    /** Network configuration for use with midday-sdk client */
+    readonly networkConfig: NetworkConfig;
+    /** Start the cluster */
+    readonly start: () => Promise<void>;
+    /** Stop the cluster */
+    readonly stop: () => Promise<void>;
+    /** Remove the cluster */
+    readonly remove: () => Promise<void>;
+    /** Check if the cluster is running */
+    readonly isRunning: () => Promise<boolean>;
+    readonly effect: {
+        /** Start the cluster (raw Effect) */
+        readonly start: () => Effect.Effect<void, ClusterError>;
+        /** Stop the cluster (raw Effect) */
+        readonly stop: () => Effect.Effect<void, ClusterError>;
+        /** Remove the cluster (raw Effect) */
+        readonly remove: () => Effect.Effect<void, ClusterError>;
+    };
+}
+declare const ClusterService_base: Context.TagClass<ClusterService, "ClusterService", Cluster>;
+/**
+ * Context.Tag for ClusterService dependency injection.
+ *
+ * Yields a Cluster instance directly. Use `Cluster.layer()` to provide
+ * with custom configuration.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
+ * import { Cluster, ClusterService } from '@no-witness-labs/midday-sdk/devnet';
+ *
+ * const program = Effect.gen(function* () {
+ *   const cluster = yield* ClusterService;
+ *   yield* cluster.effect.start();
+ *   return cluster.networkConfig;
+ * });
+ *
+ * // With default config
+ * await Effect.runPromise(program.pipe(Effect.provide(Cluster.Live)));
+ *
+ * // With custom config
+ * await Effect.runPromise(program.pipe(
+ *   Effect.provide(Cluster.layer({ clusterName: 'my-devnet' }))
+ * ));
+ * ```
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export declare class ClusterService extends ClusterService_base {
+}
+/**
+ * Create a new DevNet cluster instance.
+ *
+ * Returns a cluster with bound lifecycle methods.
+ * This creates the containers but does not start them.
+ *
+ * @example
+ * ```typescript
+ * import { Cluster } from '@no-witness-labs/midday-sdk/devnet';
+ *
+ * const cluster = await Cluster.make();
+ * await cluster.start();
+ *
+ * // Access network config directly
+ * const client = await Midday.Client.create({
+ *   networkConfig: cluster.networkConfig,
+ *   seed: 'your-wallet-seed',
+ * });
+ *
+ * // ... run tests ...
+ *
+ * await cluster.remove();
+ * ```
+ *
+ * @since 0.2.0
+ * @category constructors
+ */
+export declare const make: (config?: DevNetConfig) => Promise<Cluster>;
+/**
+ * Get the network configuration for use with midday-sdk client.
+ *
+ * @deprecated Prefer using `cluster.networkConfig` property instead.
+ *
+ * @since 0.2.0
+ * @category utilities
+ */
+export declare const toNetworkConfig: (cluster: Cluster | ClusterData) => NetworkConfig;
+/**
+ * Helper function to run code with an automatically managed cluster.
+ * The cluster is created, started, and cleaned up automatically.
+ *
+ * @example
+ * ```typescript
+ * import { Cluster } from '@no-witness-labs/midday-sdk/devnet';
+ *
+ * await Cluster.withCluster(async (cluster) => {
+ *   // Use cluster.networkConfig directly
+ *   const config = cluster.networkConfig;
+ *   // Your code here - cluster will be cleaned up automatically
+ *   return config;
+ * });
+ * ```
+ *
+ * @since 0.2.0
+ * @category utilities
+ */
+export declare const withCluster: <T>(fn: (cluster: Cluster) => Promise<T>, config?: DevNetConfig) => Promise<T>;
+/**
+ * Effect API for advanced users who want full composability,
+ * type-safe errors, retries, and other Effect benefits.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
+ * import { Cluster } from '@no-witness-labs/midday-sdk/devnet';
+ *
+ * const program = Effect.gen(function* () {
+ *   const cluster = yield* Cluster.effect.make();
+ *   yield* cluster.effect.start();  // Use instance method
+ *   return cluster;
+ * }).pipe(
+ *   Effect.retry({ times: 3 }),
+ *   Effect.timeout('5 minutes')
+ * );
+ *
+ * await Effect.runPromise(program);
+ * ```
+ *
+ * @since 0.2.0
+ * @category effect
+ */
+export declare const effect: {
+    /**
+     * Create a cluster instance (returns raw Effect).
+     *
+     * The returned cluster has an `.effect` namespace for lifecycle methods.
+     *
+     * @since 0.2.0
+     */
+    readonly make: (config?: DevNetConfig) => Effect.Effect<Cluster, ClusterError, never>;
+    /**
+     * Run code with an automatically managed cluster (returns raw Effect).
+     *
+     * @example
+     * ```typescript
+     * import { Effect } from 'effect';
+     * import { Cluster } from '@no-witness-labs/midday-sdk/devnet';
+     *
+     * const program = Cluster.effect.withCluster((cluster) =>
+     *   Effect.gen(function* () {
+     *     const config = cluster.networkConfig;
+     *     return config;
+     *   })
+     * );
+     *
+     * await Effect.runPromise(program);
+     * ```
+     *
+     * @since 0.2.0
+     */
+    readonly withCluster: <A, E, R>(fn: (cluster: Cluster) => Effect.Effect<A, E, R>, config?: DevNetConfig) => Effect.Effect<A, E | ClusterError, R>;
+};
+/**
+ * Create a Layer that provides ClusterService with custom configuration.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
+ * import { Cluster, ClusterService } from '@no-witness-labs/midday-sdk/devnet';
+ *
+ * const program = Effect.gen(function* () {
+ *   const cluster = yield* ClusterService;
+ *   yield* cluster.effect.start();
+ *   return cluster;
+ * });
+ *
+ * await Effect.runPromise(program.pipe(
+ *   Effect.provide(Cluster.layer({ clusterName: 'my-devnet' }))
+ * ));
+ * ```
+ *
+ * @since 0.2.0
+ * @category layer
+ */
+export declare const layer: (config?: DevNetConfig) => Layer.Layer<ClusterService, ClusterError>;
+/**
+ * Live Layer for ClusterService with default configuration.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
+ * import { Cluster, ClusterService } from '@no-witness-labs/midday-sdk/devnet';
+ *
+ * const program = Effect.gen(function* () {
+ *   const cluster = yield* ClusterService;
+ *   yield* cluster.effect.start();
+ *   return cluster;
+ * });
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(Cluster.Live)));
+ * ```
+ *
+ * @since 0.2.0
+ * @category layer
+ */
+export declare const Live: Layer.Layer<ClusterService, ClusterError>;
+export {};
+//# sourceMappingURL=Cluster.d.ts.map

package/dist/devnet/Cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cluster.d.ts","sourceRoot":"","sources":["../../src/devnet/Cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC;IACnC,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC;IACtC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,SAAS,CAAC;IAC1C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC;IACnC,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC;IACtC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,SAAS,CAAC;IAC1C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAGtC,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAG3C,QAAQ,CAAC,MAAM,EAAE;QACf,qCAAqC;QACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QACxD,oCAAoC;QACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QACvD,sCAAsC;QACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;KAC1D,CAAC;CACH;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAe,SAAQ,mBAGjC;CAAG;AA6QN;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,YAAY,KAAG,OAAO,CAAC,OAAO,CACrB,CAAC;AAgBxC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,OAAO,GAAG,WAAW,KAAG,aAK7D,CAAC;AAEL;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EACjC,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,EACpC,SAAS,YAAY,KACpB,OAAO,CAAC,CAAC,CAQX,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,MAAM;IACjB;;;;;;OAMG;6BAjYuB,YAAY;IAoYtC;;;;;;;;;;;;;;;;;;;OAmBG;2BACW,CAAC,EAAE,CAAC,EAAE,CAAC,MACf,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,WACvC,YAAY,KACpB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,CAAC;CAQhC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,KAAK,GAChB,SAAS,YAAY,KACpB,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,YAAY,CACO,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,YAAY,CAAW,CAAC"}