sui-effect 0.1.0

package/examples/extension-template/src/extension.ts

@@ -0,0 +1,63 @@
+/**
+ * The Promise face, derived rather than maintained.
+ *
+ * `SuiExtension.fromService` walks the service interface once: `Effect` members
+ * become Promise methods, `Stream` members become `AsyncIterable`s, nested
+ * namespaces are mapped recursively, plain values pass through, and a rejection
+ * is the same tagged error instance an Effect caller would have caught, so a
+ * Promise consumer can still switch on `_tag`.
+ *
+ * There is no second implementation to keep in step, which is the whole point.
+ */
+import { SuiExtension } from "sui-effect/extension"
+import type { EscrowOptions } from "./Escrow.ts"
+import { Escrow } from "./Escrow.ts"
+
+/** What a `$extend` registration needs beyond what the layer does. */
+export interface EscrowRegistrationOptions extends EscrowOptions {
+  /**
+   * The chain identifier the node must be on, as `getChainIdentifier` reports
+   * it.
+   *
+   * **Required on `devnet`, `localnet` and any custom network**, because a
+   * `warm` registration takes the chain id rather than asking for it and there
+   * is no built-in entry for those; `register` throws without it. On `mainnet`
+   * and `testnet` the built-in table answers and this is optional.
+   *
+   * Give the same id to **every** registration on one client. The base `Sui`,
+   * its transport and its sender-lock map are shared per client **per chain
+   * id**, so two registrations that disagree get two of everything and two
+   * `Tx.run`s for one address stop serializing.
+   */
+  readonly chainId?: string
+}
+
+/**
+ * The registration a Promise consumer passes to `client.$extend(...)`.
+ *
+ * ```ts
+ * const client = new SuiGrpcClient({ network: "testnet", baseUrl }).$extend(escrow(options))
+ * const info = await client.escrow.get(id)
+ * for await (const item of client.escrow.owned.stream(owner)) console.log(item.id)
+ * await client.escrow.dispose()
+ * ```
+ *
+ * It is registered `warm`, like `platform` in `Platform.ts`: the service has
+ * synchronous members — `packageId`, the `claim` recipe fragment, the codecs —
+ * and a consumer that reads one the moment it registers should get the value
+ * rather than a placeholder that throws `ExtensionNotReady`. Neither layer
+ * touches the network at build, which is what `warm` requires.
+ *
+ * The runtime is built inside `register`, over `SuiCore.layerFromClient(client)`,
+ * a `Sui` pinned to `options.chainId` and `Escrow.layer`, so the extension and
+ * the consumer share one transport, one chain identity and one sender-lock map.
+ *
+ * Throws out of `register` when the network has no built-in chain identifier
+ * and `options.chainId` was not given.
+ */
+export const escrow = (options: EscrowRegistrationOptions) =>
+  SuiExtension.fromService(Escrow, {
+    name: "escrow",
+    layer: Escrow.layer(options),
+    warm: options.chainId === undefined ? {} : { chainId: options.chainId }
+  })

package/examples/extension-template/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@your-org/example-extension`: the public surface.
+ *
+ * One service, its layers, its errors, its schemas, and the derived Promise
+ * registration. Nothing from `upstream.ts` is re-exported: upstream types are
+ * narrowed to sui-effect schemas inside the service and never reach a consumer.
+ */
+export {
+  DEPLOYMENTS,
+  Escrow,
+  type ClaimForError,
+  type EscrowDeployment,
+  type EscrowFields,
+  type EscrowObject,
+  type EscrowOptions,
+  type EscrowService
+} from "./Escrow.ts"
+export { EscrowNotFound, EscrowSettlementUnknown, EscrowUnsupportedNetwork } from "./errors.ts"
+export { escrow, type EscrowRegistrationOptions } from "./extension.ts"
+export {
+  Platform,
+  platform,
+  type PlatformOptions,
+  type PlatformRegistrationOptions,
+  type PlatformService
+} from "./Platform.ts"
+export {
+  ESCROW_PACKAGE,
+  EscrowContent,
+  escrowType,
+  receiptType,
+  Settlement,
+  SettlementContent
+} from "./schema.ts"

package/examples/extension-template/src/schema.ts

@@ -0,0 +1,158 @@
+/**
+ * The Move layouts this package reads, bridged into `Schema`.
+ *
+ * `SuiSchema.bcs(layout, type)` is a `Schema.Codec<T, Uint8Array>` that also
+ * records the Move type, so `sui.getObject(id, { schema })` checks the object's
+ * type tag before it parses a single byte and a mismatch is a `DecodeError`
+ * naming both types rather than a confusing parse failure.
+ */
+import { bcs } from "@mysten/sui/bcs"
+import { DateTime, Effect, Schema, SchemaIssue, SchemaTransformation } from "effect"
+import { ObjectId, SuiAddress, SuiSchema } from "sui-effect"
+
+/**
+ * The package the template's example type lives in, and the default this
+ * release ships. Replace it with yours.
+ */
+export const ESCROW_PACKAGE = "0x0000000000000000000000000000000000000000000000000000000000000002"
+
+/** The BCS layout of `escrow::Escrow`, which is the same whatever it was published to. */
+const EscrowBcs = bcs.struct("Escrow", {
+  id: bcs.Address,
+  owner: bcs.Address,
+  amount: bcs.u64()
+})
+
+/** The Move type of an escrow, under a given type origin. */
+export const escrowType = (typeOrigin: string): string =>
+  `${typeOrigin}::escrow::Escrow`
+
+/** The Move type of a claim receipt, which `claimFor` expects to be created. */
+export const receiptType = (typeOrigin: string): string =>
+  `${typeOrigin}::escrow::Receipt`
+
+/**
+ * `escrow::Escrow`, the object this extension reads, **as a function of the
+ * package it lives in**.
+ *
+ * A Move type name contains its package id, so a codec built from a hard-coded
+ * constant checks the wrong type the moment a consumer configures a different
+ * package: `getObject(id, { schema })` compares the object's tag before it
+ * parses a byte, and a correctly encoded object under the configured package
+ * fails with `DecodeError`. Every type-shaped constant in an extension takes
+ * the package id the service was built with, and the service passes its own.
+ *
+ * **Which package id.** The one that appears in a type name is the **type
+ * origin**: the package the type was *first* published in. Upgrading a package
+ * gives it a new id for *calls*, and the type origin does not move. So an
+ * extension over an upgraded package carries two ids — `packageId` for
+ * `moveCall` targets, `typeOrigin` for codecs, filters and receipt types — and
+ * they are the same value until the first upgrade. `Escrow.layer` takes both.
+ */
+export const EscrowContent = (typeOrigin: string) => SuiSchema.bcs(
+  EscrowBcs,
+  escrowType(typeOrigin)
+)
+
+/**
+ * The Move layout of `escrow::Settlement`, whose fields are `snake_case`
+ * because Move's are.
+ */
+const SettlementBcs = bcs.struct("Settlement", {
+  escrow_id: bcs.Address,
+  settled_at_ms: bcs.u64(),
+  claimed_by: bcs.Address
+})
+
+/**
+ * The domain type a consumer of this package sees: `camelCase`, branded ids,
+ * a `DateTime` instead of a string of milliseconds.
+ *
+ * The mapping lives in `Schema.decodeTo`, never in a custom `parse`: the bridge
+ * needs a real `BcsType` so it can re-serialize what it parsed and reject
+ * trailing bytes, and a domain type is not a BCS layout.
+ */
+export class Settlement extends Schema.Class<Settlement>("Settlement")({
+  escrowId: ObjectId,
+  settledAt: Schema.DateTimeUtc,
+  claimedBy: SuiAddress
+}) {}
+
+/**
+ * The halfway shape the transformation produces: the domain field names, before
+ * `Settlement`'s own schema brands the ids.
+ */
+interface SettlementParts {
+  readonly escrowId: string
+  readonly settledAt: DateTime.Utc
+  readonly claimedBy: string
+}
+
+/**
+ * The composed codec: BCS bytes to `Settlement`, and back.
+ *
+ * `SuiSchema.bcs(...)` decodes the bytes into the Move shape;
+ * `Schema.decodeTo(Settlement, SchemaTransformation.transform({ decode, encode }))`
+ * renames the fields, and `Settlement` itself does the rest — branding the ids
+ * and checking them. The Move type the bridge recorded survives the
+ * composition, so
+ * `sui.getObject(id, { schema: SettlementContent })` still checks the object's
+ * type tag before parsing a byte.
+ *
+ * Two details worth copying:
+ *
+ * - **`decode` produces the target's field shape, not an instance.** `decodeTo`
+ *   sits between the source type and the target schema, which is what lets the
+ *   target's own checks — the `ObjectId` and `SuiAddress` brands here — run
+ *   afterwards.
+ * - **`encode` is the inverse mapper and is not optional.** A codec that cannot
+ *   encode is one `Schema.encodeUnknownEffect` fails on, and the compiler asks
+ *   for it here rather than at the call site.
+ * - **A mapping that can fail uses `transformOrFail`.** `transform` is for total
+ *   mappings; a body that throws produces a defect, and a byte that was wrong on
+ *   the wire deserves a failure.
+ *
+ * A failure *inside* this transform — an id that is not an address, a timestamp
+ * that is not a time — is still a `DecodeError` from `SuiSchema.decode` and
+ * `sui.getObject`, with the same fields: the domain mapping is part of the
+ * boundary, not a step after it.
+ */
+export const SettlementContent = (typeOrigin: string) =>
+  SuiSchema.bcs(
+    SettlementBcs,
+    `${typeOrigin}::escrow::Settlement`
+  ).pipe(
+    Schema.decodeTo(
+      Settlement,
+      SchemaTransformation.transformOrFail<SettlementParts, typeof SettlementBcs.$inferType>({
+        decode: (fields, options) =>
+          // `transformOrFail`, not `transform`, because one of these mappings can
+          // fail: a `u64` of milliseconds is not necessarily a time. A `transform`
+          // whose body throws is a **defect**, which is not what a bad byte on the
+          // wire should be; failing with a `SchemaIssue` here is what makes it a
+          // `DecodeError` like any other.
+          Effect.map(
+            Effect.fromOption(
+              DateTime.make(Number(fields.settled_at_ms)),
+              () =>
+                new SchemaIssue.InvalidValue(
+                  { message: `settled_at_ms ${fields.settled_at_ms} is not a time` },
+                  fields,
+                  options
+                )
+            ),
+            (settledAt): SettlementParts => ({
+              escrowId: fields.escrow_id,
+              settledAt,
+              claimedBy: fields.claimed_by
+            })
+          ),
+        encode: (settlement) =>
+          Effect.succeed({
+            escrow_id: settlement.escrowId,
+            settled_at_ms: String(DateTime.toEpochMillis(settlement.settledAt)),
+            claimed_by: settlement.claimedBy
+          })
+      })
+    )
+  )

package/examples/extension-template/src/upstream.ts

@@ -0,0 +1,66 @@
+/**
+ * A stand-in for the third-party Promise package an extension wraps.
+ *
+ * In a real extension this file does not exist: it is an `import` of the
+ * upstream SDK (`@some-org/escrow-sdk`), and everything below is its surface.
+ * It is here so the guide's "wrapping an upstream Promise package" section has
+ * real code to point at: one helper that needs the SDK client object, and one
+ * that does not.
+ *
+ * Note what it is not: it is not exported from `src/index.ts`. Upstream types
+ * never reach a consumer of this package; they are narrowed to sui-effect
+ * schemas first.
+ */
+import type { ClientWithCoreApi } from "@mysten/sui/client"
+
+/** What the operator's settlement service answers with. Untyped on purpose: upstream JSON. */
+export interface SettlementResponse {
+  readonly status: string
+  readonly [key: string]: unknown
+}
+
+/** The upstream client surface. */
+export interface SettlementApi {
+  /**
+   * Tells the operator that a claim landed. Needs no Sui client: a pure
+   * Promise helper, which is the `Effect.tryPromise` case.
+   */
+  readonly notifyClaim: (
+    input: { readonly escrowId: string; readonly digest: string },
+    signal?: AbortSignal
+  ) => Promise<SettlementResponse>
+  /**
+   * Reads the fee collector the package was published with. Needs the SDK
+   * client object, which is the `SuiCore.use` case.
+   */
+  readonly resolveFeeCollector: (
+    client: ClientWithCoreApi,
+    packageId: string,
+    signal?: AbortSignal
+  ) => Promise<unknown>
+}
+
+/** The upstream constructor: a base URL and an API key. */
+export const settlementApi = (options: {
+  readonly url: string
+  readonly apiKey: string
+}): SettlementApi => ({
+  notifyClaim: async (input, signal) => {
+    const response = await fetch(`${options.url}/claims`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${options.apiKey}` },
+      body: JSON.stringify(input),
+      ...(signal === undefined ? {} : { signal })
+    })
+    if (!response.ok) throw new Error(`settlement service answered ${response.status}`)
+    return await response.json() as SettlementResponse
+  },
+  resolveFeeCollector: async (client, packageId, signal) => {
+    const { object } = await client.core.getObject({
+      objectId: packageId,
+      ...(signal === undefined ? {} : { signal })
+    })
+    const owner = object.owner
+    return owner.$kind === "AddressOwner" ? owner.AddressOwner : null
+  }
+})