Представим, что мне нужно купить сыр чеддер к ужину. Для этого иду в магазин.

Успешным результатом похода в магазин будет сыр.

Но есть высокая вероятность, что его не будет в первом магазине.. Или продавец даст слишком маленький кусок сыра. Возможных ошибок существует множество; они являются естественными, и на них нужно реагировать.

В случае, если в магазине нет сыра, не беда, принимаем решение идти в другой магазин. Если в другом магазине нет нужного размера, то можем попросить кусок побольше или взять похожий сорт сыра. Варианты принятия решений зависят от человека.

Если на улице будет гололед, то я могу подскользнуться и подвернуть ногу. В этом случае, поход к сыру закончится, и его не купить сегодня, потому что в магазин на руках не пойдешь. Это пример дефекта и с него уже не восстановишься как в случае возможных ошибок.

import { S3 } from "@aws-sdk/client-s3"

const client = new S3()

client.putObject({
  Bucket: "foo",
  Key: "bar",
  Body: "my content"
})

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"

const client = new S3Client()

client.send(new PutObjectCommand({
  Bucket: "foo",
  Key: "bar",
  Body: "my content"
}))

Кодогенератор, который создает такие файлы, пишет огромные JSDoс. Я почистил JSDoc для этой статьи, удалил примеры и документацию, оставил только значимое

import { Command as $Command } from "@smithy/smithy-client";
import { MetadataBearer as __MetadataBearer, StreamingBlobPayloadInputTypes } from "@smithy/types";
import { PutObjectOutput, PutObjectRequest } from "../models/models_1";
import { S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../S3Client";

/**
 *
 * @param PutObjectCommandInput - {@link PutObjectCommandInput}
 * @returns {@link PutObjectCommandOutput}
 * @see {@link PutObjectCommandInput} for command's `input` shape.
 * @see {@link PutObjectCommandOutput} for command's `response` shape.
 * @see {@link S3ClientResolvedConfig | config} for S3Client's `config` shape.
 *
 * @throws {@link EncryptionTypeMismatch} (client fault)

 * @throws {@link InvalidRequest} (client fault)
 *
 * @throws {@link InvalidWriteOffset} (client fault)
 *
 * @throws {@link TooManyParts} (client fault)
 *
 * @throws {@link S3ServiceException}
 *
 */
export declare class PutObjectCommand extends PutObjectCommand_base {
    /** @internal type navigation helper, not in runtime. */
    protected static __types: {
        api: {
            input: PutObjectRequest;
            output: PutObjectOutput;
        };
        sdk: {
            input: PutObjectCommandInput;
            output: PutObjectCommandOutput;
        };
    };
}

JSDoc для throws написан не так как это указано в спецификации, поэтому пришлось использовать регулярное выражение чтобы найти все ошибки (а так бы ts-morph помог)

• @throws free-form description

• @throws {<type>}

• @throws {<type>} free-form description

Функция get фильтрует все классы и выбирает те, которые оканчиваются на Command. И извлекает имена классов ошибок и кладет в exceptions

import { pipe, String, Array, Option, Order } from "effect";

const get = (
  input: Pick<ScannedSdkShape, "classes">
) =>
  pipe(
    input.classes,
    Array.filterMap(cls => {
      let originName = cls.getName();
      if (!originName?.endsWith("Command")) return Option.none();
      originName = originName.slice(0, originName.length - 7);
      const methodName = makePrettyOperationName(originName);
      const comment = cls.getLeadingCommentRanges().flatMap(_ => _.getText()).join("\n");
      const exceptions = [] as string[];
      const matched = comment.matchAll(throwsRegex);

      if (matched) {
        exceptions.push(...matched.map(_ => _.at(1)!));
      }

      return Option.some({
        methodName, originName,
        inputClassName: String.snakeToPascal(originName),
        throws: exceptions
      });
    }),
    Array.dedupeWith((a, b) => a.methodName == b.methodName),
    Array.sortWith(_ => _.methodName, Order.string)
  );

export type S3Api = {
  abort_multipart_upload: [
    Sdk.AbortMultipartUploadCommandInput,
    Sdk.AbortMultipartUploadCommandOutput,
    never
  ]
  complete_multipart_upload: [
    Sdk.CompleteMultipartUploadCommandInput,
    Sdk.CompleteMultipartUploadCommandOutput,
    never
  ]
  copy_object: [
    Sdk.CopyObjectCommandInput,
    Sdk.CopyObjectCommandOutput,
    {
      "ObjectNotInActiveTierError": Sdk.ObjectNotInActiveTierError
    }
  ]
  create_bucket: [
    Sdk.CreateBucketCommandInput,
    Sdk.CreateBucketCommandOutput,
    {
      "BucketAlreadyExists": Sdk.BucketAlreadyExists,
      "BucketAlreadyOwnedByYou": Sdk.BucketAlreadyOwnedByYou
    }
  ]
  create_bucket_metadata_table_configuration: [
    Sdk.CreateBucketMetadataTableConfigurationCommandInput,
    Sdk.CreateBucketMetadataTableConfigurationCommandOutput,
    never
  ]
  // и другие действия S3 сервиса
}

export const S3CommandFactory: Record<keyof S3Api, new (args: any) => any> = {
  abort_multipart_upload: AbortMultipartUploadCommand,
  complete_multipart_upload: CompleteMultipartUploadCommand,
  copy_object: CopyObjectCommand,
  // и другие действия
}

Тут Micro это тот же самый Effect, только его облегченная версия для библиотек использующий Effect вместо Promise.

export function s3<M extends keyof S3Api>(actionName: M, actionInput: S3Api[M][0]) {

  return Micro.gen(function*() {

    const client = yield* Micro.service(S3Client);

    const command = new S3CommandFactory[actionName](actionInput);

    return yield* Micro.tryPromise({
      try: () => {
        console.debug("S3", { actionName });
        return client.send(command) as Promise<S3Api[M][1]>
      },
      catch: error => {
        if (error instanceof _ServiceBaseError) {
          return new S3Error(error, actionName);
        } else {
          return { _tag: "#Defect", error } as const;
        }
      }
    }).pipe(
      Micro.catchTag("#Defect", _ => Micro.die(_)),
      Micro.tap((result) => {
        console.debug("S3, success", {
          actionName,
          statusCode: result.$metadata.httpStatusCode
        });
      }),
      Micro.tapError(error => {
        console.debug("S3, error", {
          actionName,
          name: error.cause.name,
          message: error.cause.message,
          statusCode: error.cause.$metadata.httpStatusCode
        });
        return Micro.void;
      })
    );

  })

}

export class S3Client extends
  Context.Reference<S3Client>()(
    "S3Client",
    {
      defaultValue() {
        return makeS3Client({}).pipe(Micro.runSync);
      }
    }
  )
{
}

export function makeS3Client(config: Sdk.S3ClientConfig) {

  return Micro.try({
    try: () => new _SdkClient(config),
    catch: _ => _
  }).pipe(
    Micro.orDie
  )

}

export class S3Error<C extends keyof S3Api, E extends _ServiceBaseError = _ServiceBaseError> {
  readonly _tag = "S3Error";

  constructor(
    readonly cause: E,
    readonly command: C
  ) { }

  $is<N extends keyof S3Api[C][2]>(
    name: N
  ): this is S3Error<C, S3Api[C][2][N] & _ServiceBaseError> {
    return this.cause.name == name;
  }

  is<N extends keyof S3Errors>(
    name: N
  ): this is S3Error<C, S3Errors[N]> {
    return this.cause.name == name;
  }

}

Методы $is и is возвращают тип ошибки по строковому названию этой ошибки. По сути это type guard. Разница между этими методами в том, что $is принимает названия ошибок которые указаны в JSDoc (не везде они указаны), а is принимает названия ошибок всех классов наследуемых от ServiceException

import { lambda } from "./generated/lambda.js";
import { iam } from "./generated/iam.js";
import { readFile } from "fs/promises";
import { Effect, pipe } from "effect";

const getRole = 
  Effect.gen(function* () {

    const existing =
      yield* pipe(
        iam("get_role", { RoleName: "Function1" }),
        Effect.andThen(_ => _.Role),
        Effect.catchIf(_ => _.$is("NoSuchEntityException"), () => {

          const create =
            iam("create_role", {
              RoleName: "Function1",
              AssumeRolePolicyDocument: JSON.stringify({
                "Version": "2012-10-17",
                "Statement": [
                  {
                    "Effect": "Allow",
                    "Principal": {
                      "Service": "lambda.amazonaws.com"
                    },
                    "Action": "sts:AssumeRole"
                  }
                ]
              })
            }).pipe(
              Effect.andThen(_ => _.Role)
            );

          return create;

        }),
        Effect.andThen(_ => _?.Arn),
        Effect.filterOrFail(_ => _ != null),
      );

    return existing;

  });

// const getRole: Effect.Effect<string, IAMError<"get_role", IAMServiceException> | IAMError<"create_role", IAMServiceException> | NoSuchElementException, never>

const createFunction =
  Effect.gen(function* () {

    const code = yield* Effect.tryPromise(() => readFile("example.zip"));

    const fnName = "hello-effect";

    const fn = yield* lambda("create_function", {
      Role: yield* getRole,
      Code: {
        ZipFile: code
      },
      Runtime: "nodejs22.x",
      FunctionName: fnName,
      Handler: "index.handler"
    }).pipe(
      Effect.catchIf(_ => _.$is("ResourceConflictException"), () =>
        lambda("update_function_code", {
          FunctionName: fnName,
          ZipFile: code
        })
      )
    );

  }).pipe(
    Effect.tapBoth({
      onSuccess: () => Effect.logInfo("created"),
      onFailure: (error) => Effect.logError("Error", error)
    })
  )