@unconfirmed/sui-effect 0.1.1 → 0.1.3

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

@@ -213,7 +213,7 @@ const make = (
         Effect.flatMap((raw) =>
           decodeAddress(raw).pipe(
             Effect.mapError((issue) =>
-              new DecodeError({ expectedType: "SuiAddress", issue: issue.message })
+              new DecodeError({ expectedType: "SuiAddress", kind: "shape", issue: issue.message })
             )
           )
         ),

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

@@ -10,6 +10,14 @@
  *
  * The tags are prefixed with the package name because `EscrowNotFound` is a
  * name two packages could plausibly both want.
+ *
+ * And every one of them has a real `.message`. `Schema.TaggedError` leaves it
+ * empty, so an error that supplies neither an `override get message()` nor a
+ * `message` schema field surfaces an empty string everywhere a consumer
+ * catches it, and `SuiError.toJson` emits no `message` key at all. The getter
+ * is the usual answer — it stays out of the encoding, so it costs nothing at
+ * the constructor — and a `message` schema field is for the case where the
+ * sentence comes from somewhere else, as `EscrowSettlementUnknown`'s does.
  */
 import { Schema } from "effect"
 import { Digest, type Outcome, ObjectId } from "@unconfirmed/sui-effect"
@@ -25,6 +33,18 @@ export class EscrowNotFound extends Schema.TaggedError<EscrowNotFound>()(
   { escrowId: ObjectId }
 ) {
   readonly outcome: Outcome = "not_applied"
+
+  /**
+   * `Schema.TaggedError` leaves `.message` empty, so anything surfacing
+   * `error.message` — a log line, a `catch` in a consumer's UI,
+   * `SuiError.toJson` — shows nothing unless the class supplies one. This is
+   * the idiom sui-effect's own errors use, and the reason every error here has
+   * one: define a getter over the fields, never a `message` schema field you
+   * then have to pass to every constructor.
+   */
+  override get message(): string {
+    return `no escrow ${this.escrowId}`
+  }
 }
 
 /**
@@ -34,6 +54,10 @@ export class EscrowNotFound extends Schema.TaggedError<EscrowNotFound>()(
  * This is the case the `outcome` field exists for: the transaction applied, the
  * operation as a whole did not finish, and the only safe next step is to
  * reconcile rather than to retry. A script that fails with this exits 3.
+ *
+ * Its `message` is a **schema field** rather than a getter, because the
+ * sentence comes from the settlement service rather than from these fields.
+ * Either way `.message` is a real string and `SuiError.toJson` carries it.
  */
 export class EscrowSettlementUnknown extends Schema.TaggedError<EscrowSettlementUnknown>()(
   "escrow/EscrowSettlementUnknown",
@@ -58,4 +82,9 @@ export class EscrowUnsupportedNetwork extends Schema.TaggedError<EscrowUnsupport
   { network: Schema.String }
 ) {
   readonly outcome: Outcome = "not_applied"
+
+  /** See {@link EscrowNotFound.message}: a getter, not a schema field. */
+  override get message(): string {
+    return `this release bundles no escrow deployment for ${this.network}`
+  }
 }

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

@@ -72,22 +72,12 @@ const SettlementBcs = bcs.struct("Settlement", {
  * 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")({
+export class Settlement extends Schema.Class<Settlement>("escrow/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.
  *
@@ -101,10 +91,11 @@ interface SettlementParts {
  *
  * 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.
+ * - **`decode` produces the target's `Encoded` side, not an instance.**
+ *   `typeof Settlement.Encoded` is exactly that shape, so nothing has to be
+ *   written out by hand and nothing can drift. `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.
@@ -124,7 +115,7 @@ export const SettlementContent = (typeOrigin: string) =>
   ).pipe(
     Schema.decodeTo(
       Settlement,
-      SchemaTransformation.transformOrFail<SettlementParts, typeof SettlementBcs.$inferType>({
+      SchemaTransformation.transformOrFail<typeof Settlement.Encoded, 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`
@@ -141,7 +132,7 @@ export const SettlementContent = (typeOrigin: string) =>
                   options
                 )
             ),
-            (settledAt): SettlementParts => ({
+            (settledAt): typeof Settlement.Encoded => ({
               escrowId: fields.escrow_id,
               settledAt,
               claimedBy: fields.claimed_by

package/examples/extension-template/test/escrow.test.ts

@@ -268,6 +268,15 @@ describe("Settlement: a domain class over the BCS bridge", () => {
     claimed_by: bcs.Address
   })
 
+  // The identifier is the class's stable runtime marker and its JSON-Schema
+  // `$ref` key, so it follows the guide's `"<package>/<Name>"` rule: two
+  // extensions with a `Settlement` class must not collide in one document.
+  test("the class identifier is scoped to the package", () => {
+    expect(JSON.stringify(Schema.toJsonSchemaDocument(Settlement))).toContain(
+      "escrow/Settlement"
+    )
+  })
+
   test("snake_case Move fields decode into the camelCase domain class", async () => {
     const bytes = SettlementBcs.serialize({
       escrow_id: ESCROW_ID,
@@ -645,4 +654,39 @@ describe("the errors", () => {
     expect(json["outcome"]).toBe("unknown")
     expect(json["outcome"]).toBe(SuiError.outcome(error))
   })
+
+  /**
+   * `Schema.TaggedError` leaves `.message` empty, so an error that defines
+   * neither a getter nor a `message` schema field logs as an empty string and
+   * `SuiError.toJson` emits no `message` key at all. Every error here defines
+   * one, and the guide promises a reader that they will.
+   */
+  test("every error has a real message, and toJson carries it", () => {
+    const errors = [
+      new EscrowNotFound({ escrowId: ESCROW_ID }),
+      new EscrowSettlementUnknown({
+        escrowId: ESCROW_ID,
+        digest: "1".repeat(32) as never,
+        message: "the operator never confirmed"
+      }),
+      new EscrowUnsupportedNetwork({ network: "devnet" })
+    ]
+    for (const error of errors) {
+      expect([error._tag, error.message.length > 0]).toEqual([error._tag, true])
+      expect([error._tag, SuiError.toJson(error)["message"]]).toEqual([
+        error._tag,
+        error.message
+      ])
+    }
+    // The getter reads the error's own fields, so the sentence names the thing
+    // that failed rather than repeating the tag.
+    expect(new EscrowNotFound({ escrowId: ESCROW_ID }).message).toBe(`no escrow ${ESCROW_ID}`)
+    expect(new EscrowUnsupportedNetwork({ network: "devnet" }).message).toBe(
+      "this release bundles no escrow deployment for devnet"
+    )
+    // And a getter stays out of the encoding, so it is not a constructor
+    // argument: only `EscrowSettlementUnknown` takes a `message`.
+    expect(Object.keys(SuiError.toJson(new EscrowUnsupportedNetwork({ network: "devnet" }))))
+      .toEqual(["_tag", "network", "outcome", "message"])
+  })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unconfirmed/sui-effect",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "An opinionated Effect v4 layer over @mysten/sui: two client tiers, closed error unions, and a typed transaction lifecycle.",
   "license": "MIT",
   "type": "module",