@lafken/bucket 0.10.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aníbal Emilio Jorquera Cornejo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# @lafken/bucket
+
+Define and manage Amazon S3 buckets using TypeScript decorators. `@lafken/bucket` lets you declare bucket configuration — versioning, ACL, lifecycle rules, transfer acceleration, and EventBridge integration — directly on a class. A built-in repository provides type-safe S3 operations at runtime.
+
+## Installation
+
+```bash
+npm install @lafken/bucket
+```
+
+## Getting Started
+
+Define a bucket class with `@Bucket`, register it in the `BucketResolver`, and use `createRepository` to interact with it:
+
+```typescript
+import { createApp } from '@lafken/main';
+import { BucketResolver } from '@lafken/bucket/resolver';
+import { Bucket } from '@lafken/bucket/main';
+import { createRepository } from '@lafken/bucket/service';
+
+// 1. Define the bucket
+@Bucket({ name: 'project-assets', versioned: true })
+export class AssetsBucket {}
+
+// 2. Create a repository for runtime operations
+export const assetsRepository = createRepository(AssetsBucket);
+
+// 3. Register the bucket in the resolver
+createApp({
+  name: 'my-app',
+  resolvers: [new BucketResolver([AssetsBucket])],
+});
+```
+
+## Features
+
+### Defining a Bucket
+
+Use the `@Bucket` decorator on a class to declare an S3 bucket. If `name` is omitted, the class name is used:
+
+```typescript
+import { Bucket } from '@lafken/bucket/main';
+
+@Bucket({
+  name: 'upload-storage',
+  versioned: true,
+  acl: 'private',
+  forceDestroy: true,
+  tags: { environment: 'production' },
+})
+export class UploadBucket {}
+```
+
+#### Bucket Options
+
+| Option                | Type                                          | Default      | Description                                               |
+| --------------------- | --------------------------------------------- | ------------ | --------------------------------------------------------- |
+| `name`                | `string`                                      | class name   | S3 bucket name                                            |
+| `versioned`           | `boolean`                                     | `false`      | Enable object versioning                                  |
+| `acl`                 | `'private' \| 'public-read' \| 'public-read-write'` | —     | Access control list                                       |
+| `forceDestroy`        | `boolean`                                     | `false`      | Delete all objects when the bucket is destroyed            |
+| `eventBridgeEnabled`  | `boolean`                                     | `false`      | Send bucket events to Amazon EventBridge                  |
+| `transferAcceleration`| `boolean`                                     | `false`      | Enable CloudFront-based transfer acceleration             |
+| `tracing`             | `boolean`                                     | `false`      | Enable AWS X-Ray tracing on repository operations         |
+| `tags`                | `Record<string, string>`                      | —            | Tags applied to the bucket resource                       |
+| `lifeCycleRules`      | `Record<string, KeyLifeCycleRule>`            | —            | Object lifecycle management rules                         |
+
+### Lifecycle Rules
+
+Define rules to automatically transition or expire objects based on age and size. Each key in `lifeCycleRules` represents an object prefix filter:
+
+```typescript
+@Bucket({
+  name: 'log-archive',
+  lifeCycleRules: {
+    'logs/': {
+      condition: {
+        objectSizeGreaterThan: 1024,
+      },
+      expiration: {
+        days: 90,
+      },
+      transitions: [
+        { days: 30, storage: 'standard_ia' },
+        { days: 60, storage: 'glacier' },
+      ],
+    },
+    'tmp/': {
+      expiration: {
+        days: 7,
+      },
+    },
+  },
+})
+export class LogBucket {}
+```
+
+#### Expiration Options
+
+| Option                       | Type      | Description                                       |
+| ---------------------------- | --------- | ------------------------------------------------- |
+| `days`                       | `number`  | Delete objects after this many days                |
+| `date`                       | `Date`    | Delete objects after a specific date               |
+| `expiredObjectDeleteMarker`  | `boolean` | Remove expired object delete markers               |
+
+> [!NOTE]
+> Only one expiration option can be set per rule.
+
+#### Condition Options
+
+| Option                   | Type     | Description                                   |
+| ------------------------ | -------- | --------------------------------------------- |
+| `objectSizeGreaterThan`  | `number` | Apply rule only to objects larger than (bytes) |
+| `objectSizeLessThan`     | `number` | Apply rule only to objects smaller than (bytes)|
+
+#### Available Storage Classes
+
+| Storage Class          | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `standard_ia`          | Infrequent access, lower cost                    |
+| `onezone_ia`           | Single-AZ infrequent access                      |
+| `intelligent_tiering`  | Automatic cost optimization by access patterns   |
+| `glacier`              | Long-term archive (minutes to hours retrieval)   |
+| `glacier_ir`           | Instant retrieval archive                        |
+| `deep_archive`         | Lowest cost (12+ hours retrieval)                |
+
+### EventBridge Integration
+
+Enable `eventBridgeEnabled` to send bucket events (object created, deleted, etc.) to Amazon EventBridge. Combine with `@lafken/event` to process these events:
+
+```typescript
+@Bucket({
+  name: 'document-uploads',
+  eventBridgeEnabled: true,
+})
+export class DocumentBucket {}
+```
+
+### Repository
+
+`createRepository` provides a type-safe API for S3 operations at runtime. The bucket name is automatically injected into every command:
+
+```typescript
+import { createRepository } from '@lafken/bucket/service';
+
+export const docsRepository = createRepository(DocumentBucket);
+```
+
+#### Put Object
+
+Upload an object to the bucket:
+
+```typescript
+await docsRepository.putObject({
+  Key: 'reports/monthly.json',
+  Body: JSON.stringify({ revenue: 50000 }),
+  ContentType: 'application/json',
+});
+```
+
+#### Get Object
+
+Retrieve an object from the bucket:
+
+```typescript
+const response = await docsRepository.getObject({
+  Key: 'reports/monthly.json',
+});
+
+const body = await response.Body?.transformToString();
+```
+
+#### Delete Object
+
+Remove an object from the bucket:
+
+```typescript
+await docsRepository.deleteObject({
+  Key: 'reports/old-report.json',
+});
+```
+
+#### Copy Object
+
+Copy an object within or across buckets:
+
+```typescript
+await docsRepository.copyObject({
+  Key: 'archive/monthly.json',
+  CopySource: 'document-uploads/reports/monthly.json',
+});
+```
+
+#### Move Object
+
+Copy an object to a new key and delete the original in a single operation:
+
+```typescript
+await docsRepository.moveObject({
+  Key: 'processed/monthly.json',
+  CopySource: 'document-uploads/reports/monthly.json',
+});
+```
+
+#### List Objects
+
+List all objects matching a prefix. Pagination is handled automatically:
+
+```typescript
+const result = await docsRepository.listObjects({
+  Prefix: 'reports/',
+});
+
+for (const object of result.Contents) {
+  console.log(object.Key, object.Size);
+}
+```
+
+### X-Ray Tracing
+
+Enable `tracing` in the `@Bucket` decorator to instrument all repository operations with AWS X-Ray:
+
+```typescript
+@Bucket({
+  name: 'traced-bucket',
+  tracing: true,
+})
+export class TracedBucket {}
+```
+
+### Global Configuration
+
+The `BucketResolver` accepts a second argument with global defaults applied to all buckets. Per-bucket options override global ones:
+
+```typescript
+new BucketResolver(
+  [AssetsBucket, LogBucket],
+  {
+    forceDestroy: true,
+    versioned: true,
+    tags: { team: 'platform' },
+  }
+);
+```
+
+### Extending Buckets
+
+Apply advanced CDKTN configuration to a bucket using the `extends` callback:
+
+```typescript
+new BucketResolver([
+  {
+    bucket: AssetsBucket,
+    extends: ({ bucket, scope }) => {
+      // Add CORS rules, policies, or any CDKTN construct
+    },
+  },
+]);
+```

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './main';
+export * from './resolver';
+export * from './service';

package/lib/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./main"), exports);
+__exportStar(require("./resolver"), exports);
+__exportStar(require("./service"), exports);

package/lib/main/bucket/bucket.d.ts

@@ -0,0 +1,30 @@
+import { type BucketProps } from './bucket.types';
+/**
+ * Class decorator that registers a class as an S3 bucket resource.
+ *
+ * The decorated class represents an Amazon S3 bucket and its configuration.
+ * Options such as versioning, lifecycle rules, ACL, transfer acceleration,
+ * and EventBridge integration can be set through the decorator props.
+ *
+ * @param props - Optional bucket configuration. If omitted, defaults are used
+ *                and the class name becomes the bucket resource name.
+ *
+ * @example
+ * ```ts
+ * @Bucket({ versioned: true, acl: 'private' })
+ * export class UserUploadsBucket {}
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Bucket({
+ *   lifeCycleRules: {
+ *     'tmp/': {
+ *       expiration: { days: 7 },
+ *     },
+ *   },
+ * })
+ * export class TempFilesBucket {}
+ * ```
+ */
+export declare const Bucket: (props?: BucketProps) => (target: Function) => void;

package/lib/main/bucket/bucket.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bucket = void 0;
+const bucket_types_1 = require("./bucket.types");
+/**
+ * Class decorator that registers a class as an S3 bucket resource.
+ *
+ * The decorated class represents an Amazon S3 bucket and its configuration.
+ * Options such as versioning, lifecycle rules, ACL, transfer acceleration,
+ * and EventBridge integration can be set through the decorator props.
+ *
+ * @param props - Optional bucket configuration. If omitted, defaults are used
+ *                and the class name becomes the bucket resource name.
+ *
+ * @example
+ * ```ts
+ * @Bucket({ versioned: true, acl: 'private' })
+ * export class UserUploadsBucket {}
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Bucket({
+ *   lifeCycleRules: {
+ *     'tmp/': {
+ *       expiration: { days: 7 },
+ *     },
+ *   },
+ * })
+ * export class TempFilesBucket {}
+ * ```
+ */
+const Bucket = (props = {}) => (target) => {
+    const { name = target.name } = props;
+    Reflect.defineMetadata(bucket_types_1.BucketMetadataKeys.bucket, {
+        name,
+        ...props,
+    }, target);
+};
+exports.Bucket = Bucket;

package/lib/main/bucket/bucket.types.d.ts

@@ -0,0 +1,237 @@
+import type { BucketNames, OnlyOne, ResourceOutputType } from '@lafken/common';
+import 'reflect-metadata';
+export declare enum BucketMetadataKeys {
+    bucket = "s3:bucket"
+}
+export type TransitionStorage = 'glacier' | 'standard_ia' | 'onezone_ia' | 'intelligent_tiering' | 'deep_archive' | 'glacier_ir';
+export type BucketOutputAttributes = 'id' | 'arn' | 'bucketDomainName' | 'bucketRegionalDomainName';
+export interface Transition {
+    /**
+     * Target storage class for the transition.
+     *
+     * This defines the S3 storage class to which the objects will be moved.
+     */
+    storage: TransitionStorage;
+    /**
+     * Number of days after object creation when the transition occurs.
+     *
+     * The object will be moved to the specified storage class after this
+     * number of days.
+     */
+    days: number;
+}
+export interface Expiration {
+    days?: number;
+    date?: Date;
+    expiredObjectDeleteMarker?: boolean;
+}
+export interface KeyLifeCycleRule {
+    /**
+     * Defines the expiration configuration for objects stored in the S3 bucket.
+     *
+     * This property specifies when the objects that match the lifecycle rule
+     * should be automatically deleted by Amazon S3.
+     * @example
+     * ```
+     * // one of
+     * {
+     *   expiration: {
+     *     days: 10
+     *   }
+     * }
+     * // or
+     * {
+     *   expiration: {
+     *     date: new Date()
+     *   }
+     * }
+     * // or
+     * {
+     *   expiration: {
+     *     expiredObjectDeleteMarker: true
+     *   }
+     * }
+     * ```
+     */
+    expiration?: OnlyOne<Expiration>;
+    /**
+     * Optional conditions to apply the lifecycle rule only to objects
+     * that match certain size thresholds.
+     *
+     * @example
+     * ```
+     * {
+     *   condition: {
+     *     objectSizeGreaterThan: 10000,
+     *     objectSizeLessThan: 100
+     *   }
+     * }
+     * ```
+     */
+    condition?: {
+        /**
+         * Minimum object size in bytes for the lifecycle rule to apply.
+         *
+         * The rule will only apply to objects larger than this value.
+         */
+        objectSizeGreaterThan?: number;
+        /**
+         * Maximum object size in bytes for the lifecycle rule to apply.
+         *
+         * The rule will only apply to objects smaller than this value.
+         */
+        objectSizeLessThan?: number;
+    };
+    /**
+     * Transition rules that define how and when objects are moved
+     * to different S3 storage classes (e.g., GLACIER, INTELLIGENT_TIERING).
+     *
+     * @example
+     * ```
+     * {
+     *   transitions: [
+     *     {
+     *       storage: 'standard_ia'
+     *       days: 10,
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    transitions?: Transition[];
+}
+export interface BaseBucketProps {
+    /**
+     * Bucket resource name.
+     *
+     * Defines the logical name of the bucket resource.
+     * If not specified, the name of the decorated class will be used.
+     */
+    name?: BucketNames;
+    /**
+     * Enable X-Ray tracing.
+     *
+     * When enabled, AWS X-Ray tracing is activated for the bucket-related
+     * operations. This allows you to trace and analyze requests as they
+     * pass through AWS services, useful for debugging and performance
+     * monitoring.
+     */
+    tracing?: boolean;
+}
+export interface InternalBucketProps extends BaseBucketProps {
+    isExternal?: never;
+    /**
+     * Enable EventBridge events.
+     *
+     * When enabled, Amazon S3 automatically sends events for this bucket
+     * to Amazon EventBridge. This allows you to capture S3 bucket events
+     * (such as object created, deleted, etc.).
+     */
+    eventBridgeEnabled?: boolean;
+    /**
+     * Defines the Access Control List (ACL) configuration for the S3 bucket.
+     *
+     * This property determines the default access level applied to all objects
+     * within the bucket unless overridden at the object level.
+     *
+     * - `'private'`: Grants access only to the bucket owner. This is the most secure option
+     *   and the default behavior in most cases.
+     * - `'public-read'`: Allows anyone on the internet to read objects in the bucket,
+     *   but only the bucket owner can write or modify them.
+     * - `'public-read-write'`: Grants both read and write access to everyone.
+     *   This setting is **not recommended** for production use, as it exposes your bucket
+     *   to public writes and potential misuse.
+     */
+    acl?: 'private' | 'public-read' | 'public-read-write';
+    /**
+     * Enable transfer acceleration for the S3 bucket.
+     *
+     * Transfer acceleration leverages Amazon CloudFront's globally distributed
+     * edge locations to accelerate data transfers between clients and the bucket.
+     * This reduces latency and improves throughput, particularly when
+     * users are geographically distant from the bucket's AWS region.
+     */
+    transferAcceleration?: boolean;
+    /**
+     * Enable versioning for the S3 bucket.
+     *
+     * When enabled, the bucket keeps multiple versions of an object,
+     * allowing recovery from accidental overwrites or deletions.
+     * Versioning provides a safeguard for data protection and
+     * can also be used for auditing and historical tracking.
+     */
+    versioned?: boolean;
+    /**
+     * Lifecycle rules for the S3 bucket.
+     *
+     * Defines rules to automatically manage the lifecycle of objects in the bucket,
+     * such as transitioning them to different storage classes, expiring them after
+     * a given time, or cleaning up incomplete multipart uploads.
+     *
+     * @example
+     * ```
+     * {
+     *   lifeCycleRules: {
+     *      'key-path': { // represents an object in the bucket
+     *        expiration: {
+     *          days: 20,
+     *        },
+     *        condition: {
+     *          objectSizeGreaterThan: 2024 // value in bytes
+     *        }
+     *      }
+     *   }
+     * }
+     * ```
+     */
+    lifeCycleRules?: Record<string, KeyLifeCycleRule>;
+    /**
+     * Indicates all objects from bucket should be deleted when bucket is destroyed
+     */
+    forceDestroy?: boolean;
+    /**
+     * tags.
+     *
+     * Specifies a set of tags that will be applied to s3 bucket.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Defines which S3 Bucket attributes should be exported.
+     *
+     * Supported attributes are based on Terraform `aws_s3_bucket`
+     * exported attributes and currently include:
+     * - `id`: Name of the bucket.
+     * - `arn`: ARN of the bucket (`arn:aws:s3:::bucketname`).
+     * - `bucketDomainName`: Bucket domain name (`bucketname.s3.amazonaws.com`).
+     * - `bucketRegionalDomainName`: Region-specific bucket domain name.
+     *
+     * Each selected attribute can be exported through SSM Parameter Store (`type: 'ssm'`)
+     * or Terraform outputs (`type: 'output'`).
+     *
+     * @example
+     * {
+     *   outputs: [
+     *     { type: 'ssm', name: '/my-bucket/arn', value: 'arn' },
+     *     { type: 'output', name: 'bucket_regional_domain', value: 'bucketRegionalDomainName' }
+     *   ]
+     * }
+     */
+    outputs?: ResourceOutputType<BucketOutputAttributes>;
+}
+export interface ExternalBucketProps extends BaseBucketProps {
+    /**
+     * Marks the bucket as an external resource.
+     *
+     * When set to `true`, the bucket is not created by the framework.
+     * Instead, it references an existing S3 bucket using the provided `name`.
+     */
+    isExternal: true;
+}
+export type BucketProps = InternalBucketProps | ExternalBucketProps;
+export interface InternalBucketMetadataProps extends Omit<InternalBucketProps, 'name'> {
+    name: string;
+}
+export interface ExternalBucketMetadataProps extends Omit<ExternalBucketProps, 'name'> {
+    name: string;
+}
+export type BucketMetadata = InternalBucketMetadataProps | ExternalBucketMetadataProps;

package/lib/main/bucket/bucket.types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BucketMetadataKeys = void 0;
+require("reflect-metadata");
+var BucketMetadataKeys;
+(function (BucketMetadataKeys) {
+    BucketMetadataKeys["bucket"] = "s3:bucket";
+})(BucketMetadataKeys || (exports.BucketMetadataKeys = BucketMetadataKeys = {}));

package/lib/main/bucket/index.d.ts

@@ -0,0 +1,2 @@
+export * from './bucket';
+export * from './bucket.types';

package/lib/main/bucket/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./bucket"), exports);
+__exportStar(require("./bucket.types"), exports);

package/lib/main/index.d.ts

@@ -0,0 +1 @@
+export * from './bucket';

package/lib/main/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./bucket"), exports);

package/lib/resolver/bucket/bucket.types.d.ts

@@ -0,0 +1,10 @@
+import type { ClassResource } from '@lafken/common';
+import type { InternalBucketProps as MainInternalBucketProps } from '../../main';
+export interface BucketGlobalConfig extends Omit<MainInternalBucketProps, 'name' | 'tracing'> {
+}
+export interface InternalBucketProps extends BucketGlobalConfig {
+    classResource: ClassResource;
+}
+export interface ExternalBucketProps {
+    classResource: ClassResource;
+}

package/lib/resolver/bucket/bucket.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/resolver/bucket/external/external.d.ts

@@ -0,0 +1,14 @@
+import { DataAwsS3Bucket } from '@cdktn/provider-aws/lib/data-aws-s3-bucket';
+import type { Construct } from 'constructs';
+import type { ExternalBucketMetadataProps } from '../../../main';
+declare const ExternalBucket_base: (new (...args: any[]) => {
+    isGlobal(module: import("@lafken/common").ModuleGlobalReferenceNames | (string & {}), id: string): void;
+    isDependent(resolveDependency: () => void): void;
+    readonly node: import("constructs").Node;
+    with(...mixins: import("constructs").IMixin[]): import("constructs").IConstruct;
+    toString(): string;
+}) & typeof DataAwsS3Bucket;
+export declare class ExternalBucket extends ExternalBucket_base {
+    constructor(scope: Construct, props: ExternalBucketMetadataProps);
+}
+export {};

package/lib/resolver/bucket/external/external.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalBucket = void 0;
+const data_aws_s3_bucket_1 = require("@cdktn/provider-aws/lib/data-aws-s3-bucket");
+const resolver_1 = require("@lafken/resolver");
+class ExternalBucket extends resolver_1.lafkenResource.make(data_aws_s3_bucket_1.DataAwsS3Bucket) {
+    constructor(scope, props) {
+        const { name } = props;
+        super(scope, `${name}-bucket`, {
+            bucket: name,
+        });
+        this.isGlobal('bucket', name);
+    }
+}
+exports.ExternalBucket = ExternalBucket;

package/lib/resolver/bucket/internal/internal.d.ts

@@ -0,0 +1,14 @@
+import { S3Bucket } from '@cdktn/provider-aws/lib/s3-bucket';
+import type { Construct } from 'constructs';
+import type { InternalBucketMetadataProps } from '../../../main';
+declare const InternalBucket_base: (new (...args: any[]) => {
+    isGlobal(module: import("@lafken/common").ModuleGlobalReferenceNames | (string & {}), id: string): void;
+    isDependent(resolveDependency: () => void): void;
+    readonly node: import("constructs").Node;
+    with(...mixins: import("constructs").IMixin[]): import("constructs").IConstruct;
+    toString(): string;
+}) & typeof S3Bucket;
+export declare class InternalBucket extends InternalBucket_base {
+    constructor(scope: Construct, props: InternalBucketMetadataProps);
+}
+export {};

package/lib/resolver/bucket/internal/internal.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternalBucket = void 0;
+const s3_bucket_1 = require("@cdktn/provider-aws/lib/s3-bucket");
+const s3_bucket_accelerate_configuration_1 = require("@cdktn/provider-aws/lib/s3-bucket-accelerate-configuration");
+const s3_bucket_acl_1 = require("@cdktn/provider-aws/lib/s3-bucket-acl");
+const s3_bucket_lifecycle_configuration_1 = require("@cdktn/provider-aws/lib/s3-bucket-lifecycle-configuration");
+const s3_bucket_notification_1 = require("@cdktn/provider-aws/lib/s3-bucket-notification");
+const s3_bucket_versioning_1 = require("@cdktn/provider-aws/lib/s3-bucket-versioning");
+const common_1 = require("@lafken/common");
+const resolver_1 = require("@lafken/resolver");
+class InternalBucket extends resolver_1.lafkenResource.make(s3_bucket_1.S3Bucket) {
+    constructor(scope, props) {
+        const { name, eventBridgeEnabled, acl, forceDestroy, transferAcceleration, versioned, lifeCycleRules, tags, } = props;
+        super(scope, `${name}-bucket`, {
+            bucket: name,
+            forceDestroy: forceDestroy ?? props.forceDestroy,
+            tags: tags ?? {
+                ...(tags || {}),
+                ...(props.tags || {}),
+            },
+        });
+        this.isGlobal('bucket', name);
+        if (eventBridgeEnabled ?? props.eventBridgeEnabled) {
+            new s3_bucket_notification_1.S3BucketNotification(this, `${name}-notification`, {
+                bucket: this.id,
+                eventbridge: true,
+            });
+        }
+        if (acl || props.acl) {
+            new s3_bucket_acl_1.S3BucketAcl(this, `${name}-acl`, {
+                bucket: this.id,
+                acl: acl || props.acl,
+            });
+        }
+        if (versioned ?? props.versioned) {
+            new s3_bucket_versioning_1.S3BucketVersioningA(this, `${name}-versioned`, {
+                bucket: this.id,
+                versioningConfiguration: {
+                    status: 'Enabled',
+                },
+            });
+        }
+        if (transferAcceleration ?? props.transferAcceleration) {
+            new s3_bucket_accelerate_configuration_1.S3BucketAccelerateConfiguration(this, `${name}-accelerate-config`, {
+                bucket: this.id,
+                status: 'Enabled',
+            });
+        }
+        const lifeCycle = lifeCycleRules || props.lifeCycleRules || {};
+        if (Object.keys(lifeCycle).length > 0) {
+            new s3_bucket_lifecycle_configuration_1.S3BucketLifecycleConfiguration(this, `${name}-lifecycle`, {
+                bucket: this.id,
+                rule: Object.keys(lifeCycle).map((key) => {
+                    const rule = lifeCycle[key];
+                    return {
+                        id: `${name}-lc-rule-${(0, common_1.cleanString)(key)}`,
+                        status: 'Enabled',
+                        filter: [
+                            {
+                                prefix: key,
+                                objectSizeGreaterThan: rule.condition?.objectSizeGreaterThan,
+                                objectSizeLessThan: rule.condition?.objectSizeLessThan,
+                            },
+                        ],
+                        expiration: rule.expiration
+                            ? [
+                                {
+                                    days: rule.expiration.days,
+                                    date: rule.expiration.date
+                                        ? rule.expiration.date
+                                            .toLocaleDateString('en-GB', {
+                                            day: '2-digit',
+                                            month: '2-digit',
+                                            year: 'numeric',
+                                        })
+                                            .replace(/\//g, '-')
+                                        : undefined,
+                                    expiredObjectDeleteMarker: rule.expiration.expiredObjectDeleteMarker,
+                                },
+                            ]
+                            : undefined,
+                        transition: (rule.transitions || []).map((transition) => ({
+                            days: transition.days,
+                            storageClass: transition.storage,
+                        })),
+                    };
+                }),
+            });
+        }
+        new resolver_1.ResourceOutput(this, props.outputs);
+    }
+}
+exports.InternalBucket = InternalBucket;

package/lib/resolver/index.d.ts

@@ -0,0 +1 @@
+export * from './resolver';

package/lib/resolver/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./resolver"), exports);

package/lib/resolver/resolver.d.ts

@@ -0,0 +1,14 @@
+import type { ClassResource } from '@lafken/common';
+import type { AppModule, AppStack, ResolverType } from '@lafken/resolver';
+import type { BucketGlobalConfig } from './bucket/bucket.types';
+import type { ClassResourceExtends } from './resolver.types';
+export declare class BucketResolver implements ResolverType {
+    private buckets;
+    private config;
+    type: string;
+    private extensibleBuckets;
+    constructor(buckets: (ClassResource | ClassResourceExtends)[], config?: BucketGlobalConfig);
+    beforeCreate(scope: AppModule): void;
+    create(): void;
+    afterCreate(scope: AppStack): void;
+}

package/lib/resolver/resolver.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BucketResolver = void 0;
+const main_1 = require("../main");
+const external_1 = require("./bucket/external/external");
+const internal_1 = require("./bucket/internal/internal");
+class BucketResolver {
+    buckets;
+    config;
+    type = 'BUCKET';
+    extensibleBuckets = [];
+    constructor(buckets, config = {}) {
+        this.buckets = buckets;
+        this.config = config;
+    }
+    beforeCreate(scope) {
+        for (const bucket of this.buckets) {
+            const isExtensible = 'bucket' in bucket;
+            const bucketProps = Reflect.getMetadata(main_1.BucketMetadataKeys.bucket, isExtensible ? bucket.bucket : bucket);
+            let bucketResource;
+            if (bucketProps.isExternal) {
+                bucketResource = new external_1.ExternalBucket(scope, {
+                    ...bucketProps,
+                });
+            }
+            else {
+                bucketResource = new internal_1.InternalBucket(scope, {
+                    ...bucketProps,
+                    ...this.config,
+                });
+            }
+            if (isExtensible) {
+                this.extensibleBuckets.push({
+                    bucket: bucketResource,
+                    extends: bucket.extends,
+                });
+            }
+        }
+    }
+    create() {
+        throw new Error('It is not possible to parse this service');
+    }
+    afterCreate(scope) {
+        for (const extendBucket of this.extensibleBuckets) {
+            extendBucket.extends({
+                scope,
+                bucket: extendBucket.bucket,
+            });
+        }
+    }
+}
+exports.BucketResolver = BucketResolver;

package/lib/resolver/resolver.types.d.ts

@@ -0,0 +1,13 @@
+import type { DataAwsS3Bucket } from '@cdktn/provider-aws/lib/data-aws-s3-bucket';
+import type { S3Bucket } from '@cdktn/provider-aws/lib/s3-bucket';
+import type { ClassResource } from '@lafken/common';
+import type { AppStack } from '@lafken/resolver';
+interface ExtendProps {
+    scope: AppStack;
+    bucket: S3Bucket | DataAwsS3Bucket;
+}
+export interface ClassResourceExtends {
+    bucket: ClassResource;
+    extends: (props: ExtendProps) => void;
+}
+export {};

package/lib/resolver/resolver.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/service/client/client.d.ts

@@ -0,0 +1,3 @@
+import { S3Client } from '@aws-sdk/client-s3';
+export declare const client: S3Client;
+export declare const getClientWithXRay: () => S3Client;

package/lib/service/client/client.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClientWithXRay = exports.client = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const aws_xray_sdk_1 = require("aws-xray-sdk");
+exports.client = new client_s3_1.S3Client();
+const getClientWithXRay = () => {
+    return (0, aws_xray_sdk_1.captureAWSv3Client)(exports.client);
+};
+exports.getClientWithXRay = getClientWithXRay;

package/lib/service/index.d.ts

@@ -0,0 +1 @@
+export * from './repository';

package/lib/service/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./repository"), exports);

package/lib/service/repository/index.d.ts

@@ -0,0 +1,3 @@
+export * from './repository';
+export * from './repository.types';
+export * from './repository.utils';

package/lib/service/repository/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./repository"), exports);
+__exportStar(require("./repository.types"), exports);
+__exportStar(require("./repository.utils"), exports);

package/lib/service/repository/repository.d.ts

@@ -0,0 +1,3 @@
+import type { ClassResource } from '@lafken/common';
+import type { RepositoryReturn } from './repository.types';
+export declare const createRepository: <E extends ClassResource>(bucket: E) => RepositoryReturn<E>;

package/lib/service/repository/repository.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRepository = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const client_1 = require("../client/client");
+const repository_utils_1 = require("./repository.utils");
+const createRepository = (bucket) => {
+    const { name, tracing } = (0, repository_utils_1.getBucketInformation)(bucket);
+    const bucketClient = tracing ? (0, client_1.getClientWithXRay)() : client_1.client;
+    return {
+        putObject(props) {
+            const command = new client_s3_1.PutObjectCommand({
+                Bucket: name,
+                ...props,
+            });
+            return bucketClient.send(command);
+        },
+        getObject(props) {
+            const command = new client_s3_1.GetObjectCommand({
+                Bucket: name,
+                ...props,
+            });
+            return bucketClient.send(command);
+        },
+        deleteObject(props) {
+            const command = new client_s3_1.DeleteObjectCommand({
+                Bucket: name,
+                ...props,
+            });
+            return bucketClient.send(command);
+        },
+        copyObject(props) {
+            const command = new client_s3_1.CopyObjectCommand({
+                Bucket: name,
+                ...props,
+            });
+            return bucketClient.send(command);
+        },
+        async moveObject(props) {
+            await this.copyObject(props);
+            await this.deleteObject({
+                Key: props.Key,
+            });
+        },
+        async listObjects(props) {
+            let allContents = [];
+            let nextToken;
+            do {
+                const command = new client_s3_1.ListObjectsV2Command({
+                    Bucket: name,
+                    ...props,
+                    ContinuationToken: nextToken,
+                });
+                const response = await bucketClient.send(command);
+                allContents = [...allContents, ...(response.Contents || [])];
+                nextToken = response.IsTruncated ? response.ContinuationToken : undefined;
+            } while (nextToken);
+            return { Contents: allContents };
+        },
+    };
+};
+exports.createRepository = createRepository;

package/lib/service/repository/repository.types.d.ts

@@ -0,0 +1,13 @@
+import type { _Object, CopyObjectCommandInput, CopyObjectCommandOutput, DeleteObjectCommandInput, DeleteObjectCommandOutput, GetObjectCommandInput, GetObjectCommandOutput, ListObjectsV2CommandInput, PutObjectCommandInput, PutObjectCommandOutput } from '@aws-sdk/client-s3';
+import type { ClassResource } from '@lafken/common';
+export type InputWithoutBucket<T> = Omit<T, 'Bucket'>;
+export type RepositoryReturn<_E extends ClassResource> = {
+    putObject(props: InputWithoutBucket<PutObjectCommandInput>): Promise<PutObjectCommandOutput>;
+    getObject(props: InputWithoutBucket<GetObjectCommandInput>): Promise<GetObjectCommandOutput>;
+    deleteObject(props: InputWithoutBucket<DeleteObjectCommandInput>): Promise<DeleteObjectCommandOutput>;
+    copyObject(props: InputWithoutBucket<CopyObjectCommandInput>): Promise<CopyObjectCommandOutput>;
+    moveObject(props: InputWithoutBucket<CopyObjectCommandInput>): Promise<void>;
+    listObjects(props: InputWithoutBucket<ListObjectsV2CommandInput>): Promise<{
+        Contents: _Object[];
+    }>;
+};

package/lib/service/repository/repository.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/service/repository/repository.utils.d.ts

@@ -0,0 +1,2 @@
+import type { ClassResource } from '@lafken/common';
+export declare const getBucketInformation: <T>(bucket: ClassResource) => T;

package/lib/service/repository/repository.utils.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBucketInformation = void 0;
+const bucket_1 = require("../../main/bucket");
+const getBucketInformation = (bucket) => {
+    const bucketProps = Reflect.getMetadata(bucket_1.BucketMetadataKeys.bucket, bucket);
+    return bucketProps;
+};
+exports.getBucketInformation = getBucketInformation;

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@lafken/bucket",
+  "version": "0.10.1",
+  "private": false,
+  "description": "Define S3 buckets using TypeScript decorators - automatic infrastructure generation with Lafken",
+  "keywords": [
+    "aws",
+    "s3",
+    "storage",
+    "object storage",
+    "serverless",
+    "typescript",
+    "decorators",
+    "lafken"
+  ],
+  "homepage": "https://github.com/Hero64/lafken#readme",
+  "bugs": "https://github.com/Hero64/lafken/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hero64/lafken",
+    "directory": "packages/bucket"
+  },
+  "license": "MIT",
+  "author": "Aníbal Jorquera",
+  "exports": {
+    "./main": {
+      "types": "./lib/main/index.d.ts",
+      "import": "./lib/main/index.js",
+      "require": "./lib/main/index.js"
+    },
+    "./service": {
+      "types": "./lib/service/index.d.ts",
+      "import": "./lib/service/index.js",
+      "require": "./lib/service/index.js"
+    },
+    "./resolver": {
+      "types": "./lib/resolver/index.d.ts",
+      "import": "./lib/resolver/index.js",
+      "require": "./lib/resolver/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "main": [
+        "./lib/main/index.d.ts"
+      ],
+      "service": [
+        "./lib/service/index.d.ts"
+      ],
+      "resolver": [
+        "./lib/resolver/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "aws-xray-sdk": "^3.12.0",
+    "reflect-metadata": "^0.2.2",
+    "@lafken/resolver": "0.10.1"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1020.0",
+    "@cdktn/provider-aws": "^23.5.0",
+    "@swc/core": "^1.15.21",
+    "@swc/helpers": "^0.5.20",
+    "@vitest/runner": "^4.1.2",
+    "cdktn": "^0.22.1",
+    "cdktn-vitest": "^1.0.0",
+    "constructs": "^10.6.0",
+    "typescript": "6.0.2",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.2",
+    "@lafken/common": "0.10.1"
+  },
+  "peerDependencies": {
+    "@cdktn/provider-aws": ">=23.0.0",
+    "cdktn": ">=0.22.0",
+    "constructs": "^10.4.5",
+    "@lafken/common": "0.10.1"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc -p ./tsconfig.build.json",
+    "check-types": "tsc --noEmit -p ./tsconfig.build.json",
+    "clean": "rm -rf ./lib",
+    "dev": "tsc -w",
+    "test": "vitest"
+  }
+}