@lafken/common 0.10.1

package/lib/types/output.types.d.ts

@@ -0,0 +1,55 @@
+export type OutputType = 'arn' | 'id';
+export type GetResourceValue<T = string, V = OutputType> = (value: T, type: V) => any;
+/**
+ * Common fields shared by all resource output definitions.
+ *
+ * The `value` field does not contain the final resolved AWS value. Instead, it declares
+ * which resource property should be exported by the resolver, such as an ARN, ID, URL,
+ * or any other attribute exposed by the resource implementation.
+ */
+export interface OutputBase<T> {
+    /**
+     * Export name.
+     *
+     * For `ssm` outputs this is the SSM parameter name.
+     * For `output` outputs this is the Terraform output name.
+     */
+    name: string;
+    /** Resource attribute key that should be exported. */
+    value: T;
+    /** Optional human-readable description for the generated output. */
+    description?: string;
+}
+/**
+ * Defines an output that will be persisted in AWS Systems Manager Parameter Store.
+ *
+ * Use this output type when a resource property must be consumed outside Terraform,
+ * for example by Lambda runtime code, other AWS services, external applications,
+ * or deployment processes that read values from Parameter Store.
+ */
+export interface SSMOutput<T> extends OutputBase<T> {
+    /** Output backend type discriminator. */
+    type: 'ssm';
+    /**
+     * Stores the parameter as `SecureString` when true.
+     * Defaults to a plain `String` when omitted.
+     */
+    secure?: boolean;
+}
+/**
+ * Defines an output that will be emitted as a Terraform output.
+ *
+ * Use this output type when the exported value should remain in Terraform state
+ * and be consumed through Terraform plans, remote state, or other Terraform workflows.
+ */
+export interface TerraformOutput<T> extends OutputBase<T> {
+    /** Output backend type discriminator. */
+    type: 'output';
+}
+/**
+ * Collection of outputs exposed by a resource.
+ *
+ * A resource can export one or more of its attributes through SSM Parameter Store,
+ * Terraform outputs, or both at the same time.
+ */
+export type ResourceOutputType<T> = (SSMOutput<T> | TerraformOutput<T>)[];

package/lib/types/output.types.js

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

package/lib/types/override-resources.types.d.ts

@@ -0,0 +1,35 @@
+import type { ResourceIdentifiers, ScopedResourceNames } from './utilities.types';
+export type ModuleGlobalReferenceNames = 'api' | 'auth' | 'bucket' | 'dynamo' | 'event-bus';
+export interface ModulesAvailable {
+}
+export interface AuthAvailable {
+}
+export interface BucketAvailable {
+}
+export interface ApiRestAvailable {
+}
+export interface ApiAuthorizerAvailable {
+}
+export interface EventBusAvailable {
+}
+export interface DynamoTableAvailable {
+}
+type ResourceNames<T> = keyof T | (string & {});
+type StackResourceName<T, S extends ModuleGlobalReferenceNames> = `${S}::${Extract<keyof T, string | number>}` | (string & {});
+export type ModuleNames = ResourceNames<ModulesAvailable>;
+export type AuthNames = ResourceNames<AuthAvailable>;
+export type AuthScopedNames = StackResourceName<AuthAvailable, 'auth'>;
+export type BucketNames = ResourceNames<BucketAvailable>;
+export type BucketScopedNames = StackResourceName<BucketAvailable, 'bucket'>;
+export type ApiRestNames = ResourceNames<ApiRestAvailable>;
+export type ApiRestScopedNames = StackResourceName<ApiRestAvailable, 'api'>;
+export type ApiAuthorizerNames = ResourceNames<ApiAuthorizerAvailable>;
+export type EventBusNames = ResourceNames<EventBusAvailable>;
+export type EventBusScopedNames = StackResourceName<EventBusAvailable, 'event-bus'>;
+export type DynamoTableNames = ResourceNames<DynamoTableAvailable>;
+export type DynamoTableScopedNames = StackResourceName<DynamoTableAvailable, 'dynamo'>;
+export type StateMachineNames = ResourceIdentifiers<ModulesAvailable, 'StateMachine'> | (string & {});
+export type StateMachineScopedNames = ScopedResourceNames<ModulesAvailable, 'StateMachine', 'state-machine'> | (string & {});
+export type QueueNames = ResourceIdentifiers<ModulesAvailable, 'Queue'> | (string & {});
+export type QueueScopedNames = ScopedResourceNames<ModulesAvailable, 'Queue', 'queue'> | (string & {});
+export {};

package/lib/types/override-resources.types.js

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

package/lib/types/resource.types.d.ts

@@ -0,0 +1,52 @@
+import type { GetResourceValue } from './output.types';
+import type { ApiRestScopedNames, AuthScopedNames, BucketScopedNames, DynamoTableScopedNames, EventBusScopedNames, QueueScopedNames, StateMachineScopedNames } from './override-resources.types';
+export interface ClassResource {
+    new (...args: any[]): {};
+}
+export interface GetResourceProps {
+    /**
+     * Retrieves an attribute value from a resource created by Lafken.
+     *
+     * Uses the format `'scope::resourceName'` to identify the resource,
+     * where `scope` corresponds to the resource type prefix (e.g., `dynamo`, `bucket`,
+     * `api`, `auth`, `event-bus`) or the module name (for queues and state machines).
+     *
+     * The second argument specifies the attribute to retrieve. Available attributes
+     * depend on the resource type and correspond to the Terraform registry attribute
+     * reference for each AWS resource.
+     *
+     * @param value - Resource identifier in `'scope::resourceName'` format.
+     * @param type - Attribute to retrieve (`'arn'` or `'id'`).
+     *
+     * @example
+     * // Get a DynamoDB table ID
+     * getResourceValue('dynamo::users', 'id')
+     *
+     * @example
+     * // Get a queue ARN
+     * getResourceValue('orders-module::queue::processOrder', 'id')
+     *
+     * @example
+     * // Get a bucket ARN
+     * getResourceValue('bucket::uploads', 'arn')
+     */
+    getResourceValue: GetResourceValue<DynamoTableScopedNames | AuthScopedNames | BucketScopedNames | ApiRestScopedNames | EventBusScopedNames | StateMachineScopedNames | QueueScopedNames>;
+    /**
+     * Retrieves a value from AWS Systems Manager Parameter Store.
+     *
+     * Resolves SSM parameter references at deployment time, allowing
+     * access to configuration values stored in Parameter Store.
+     *
+     * @param value - The SSM parameter path (e.g., `'/my-app/database-url'`).
+     * @param secure - When `true`, retrieves the parameter as a `SecureString`.
+     *
+     * @example
+     * // Get a plain text parameter
+     * getSSMValue('/my-app/api-key')
+     *
+     * @example
+     * // Get a secure parameter
+     * getSSMValue('/my-app/secret', true)
+     */
+    getSSMValue: (value: string, secure?: boolean) => string;
+}

package/lib/types/resource.types.js

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

package/lib/types/services.types.d.ts

@@ -0,0 +1,22 @@
+import type { GetResourceProps } from './resource.types';
+export type ServicesName = 'dynamodb' | 's3' | 'lambda' | 'cloudwatch' | 'sqs' | 'state_machine' | 'kms' | 'ssm' | 'event';
+interface PermissionService<T extends ServicesName | 'custom', P extends string> {
+    type: T;
+    permissions?: P[];
+    resources?: string[];
+}
+export type DynamoPermissions = 'Query' | 'Scan' | 'GetItem' | 'BatchGetItem' | 'PutItem' | 'DeleteItem' | 'UpdateItem' | 'ConditionCheckItem' | 'DescribeStream' | 'GetRecords' | 'GetShardIterator' | 'ListStreams';
+export type S3Permissions = 'AbortMultipartUpload' | 'CreateBucket' | 'DeleteBucket' | 'DeleteObject' | 'DeleteObjectTagging' | 'DeleteObjectVersion' | 'DeleteObjectVersionTagging' | 'GetBucketTagging' | 'GetBucketVersioning' | 'GetObject' | 'GetObjectAttributes' | 'GetObjectTagging' | 'GetObjectVersion' | 'GetObjectVersionAttributes' | 'GetObjectVersionTagging' | 'ListAllMyBuckets' | 'ListBucket' | 'ListBucketMultipartUploads' | 'ListBucketVersions' | 'ListMultipartUploadParts' | 'PutObject' | 'PutObjectTagging' | 'PutObjectVersionTagging' | 'ReplicateDelete' | 'ReplicateObject' | 'ReplicateTags' | 'RestoreObject';
+export type LambdaPermissions = 'InvokeFunction';
+export type LogsPermission = 'CreateLogGroup' | 'CreateLogStream' | 'PutLogEvents';
+export type SQSPermissions = 'DeleteMessage' | 'GetQueueUrl' | 'ReceiveMessage' | 'ReceiveMessage' | 'SendMessage' | 'GetQueueAttributes';
+export type StateMachinePermissions = 'InvokeHTTPEndpoint' | 'DescribeExecution' | 'StartExecution' | 'StopExecution' | 'DescribeExecution' | 'GetExecutionHistory';
+export type KMSPermissions = 'Decrypt' | 'DescribeKey' | 'Encrypt' | 'GenerateDataKey' | 'GenerateRandom' | 'GetPublicKey' | 'Sign' | 'Verify';
+export type SSMPermissions = 'DescribeParameters' | 'GetDocument' | 'GetParameter' | 'GetParameters' | 'GetParametersByPath' | 'ListDocuments' | 'PutParameter';
+export type EventPermissions = 'DescribeEventRule' | 'DescribeEventBus' | 'DescribeRule' | 'PutEvents' | 'PutRule';
+export type Services = ServicesName | PermissionService<'dynamodb', DynamoPermissions> | PermissionService<'s3', S3Permissions> | PermissionService<'lambda', LambdaPermissions> | PermissionService<'cloudwatch', LogsPermission> | PermissionService<'sqs', SQSPermissions> | PermissionService<'state_machine', StateMachinePermissions> | PermissionService<'kms', KMSPermissions> | PermissionService<'ssm', SSMPermissions> | PermissionService<'event', EventPermissions> | (PermissionService<'custom', string> & {
+    serviceName: string;
+});
+export type ServiceFunction = (props: GetResourceProps) => Services[];
+export type ServicesValues = Services[] | ServiceFunction;
+export {};

package/lib/types/services.types.js

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

package/lib/types/time.types.d.ts

@@ -0,0 +1,8 @@
+export interface Time {
+    type: 'days' | 'minutes' | 'seconds';
+    duration: number;
+}
+/**
+ * Time in seconds or Time object
+ */
+export type Duration = number | Time;

package/lib/types/time.types.js

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

package/lib/types/utilities.types.d.ts

@@ -0,0 +1,37 @@
+export type KeyOfClass<E extends Function> = keyof E['prototype'];
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+export type OnlyNumberString<T> = {
+    [key in keyof T as T[key] extends string | number ? key : never]: T[key];
+};
+export type OnlyNumber<T> = {
+    [key in keyof T as T[key] extends number ? key : never]: T[key];
+};
+export type Join<K, P> = K extends string ? P extends string ? `${K}::${P}` : never : never;
+export type FlattenStacksByResource<TStacks, TResource extends string> = {
+    [StackName in keyof TStacks]: TResource extends keyof TStacks[StackName] ? Join<TResource, Join<StackName & string, keyof TStacks[StackName][TResource] & string>> : never;
+}[keyof TStacks];
+export type ResourceIdentifiers<TStacks, TResource extends string> = {
+    [K in keyof TStacks]: TResource extends keyof TStacks[K] ? keyof TStacks[K][TResource] : never;
+}[keyof TStacks] & string;
+export type ScopedResourceNames<TStacks, TResource extends string, TMiddle extends string = Lowercase<TResource>> = {
+    [StackName in keyof TStacks]: TResource extends keyof TStacks[StackName] ? Join<Join<StackName & string, TMiddle>, keyof TStacks[StackName][TResource] & string> : never;
+}[keyof TStacks];
+export type OnlyOne<T> = {
+    [K in keyof T]: Required<Pick<T, K>> & Partial<Record<Exclude<keyof T, K>, never>>;
+}[keyof T];
+export type OnlyOneKey<T> = {
+    [K in keyof T]: {
+        [P in K]: T[P];
+    } & {
+        [P in Exclude<keyof T, K>]?: never;
+    };
+}[keyof T];
+export type StripReadonly<T> = {
+    -readonly [P in keyof T]: StripReadonly<T[P]>;
+};
+export type Primitive = string | number | boolean[];
+export type OnlyTypeKeys<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];

package/lib/types/utilities.types.js

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

package/lib/utils/build-env.utils.d.ts

@@ -0,0 +1,2 @@
+export declare const enableBuildEnvVariable: () => void;
+export declare const isBuildEnvironment: () => boolean;

package/lib/utils/build-env.utils.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBuildEnvironment = exports.enableBuildEnvVariable = void 0;
+const env_constants_1 = require("../constants/env.constants");
+const enableBuildEnvVariable = () => {
+    process.env[env_constants_1.LAFKEN_CONTEXT] = env_constants_1.LAFKEN_CONTEXT_VALUE;
+};
+exports.enableBuildEnvVariable = enableBuildEnvVariable;
+const isBuildEnvironment = () => {
+    return process.env[env_constants_1.LAFKEN_CONTEXT] === env_constants_1.LAFKEN_CONTEXT_VALUE;
+};
+exports.isBuildEnvironment = isBuildEnvironment;

package/lib/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './build-env.utils';
+export * from './path.utils';
+export * from './resource.utils';
+export * from './string.utils';

package/lib/utils/index.js

@@ -0,0 +1,20 @@
+"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("./build-env.utils"), exports);
+__exportStar(require("./path.utils"), exports);
+__exportStar(require("./resource.utils"), exports);
+__exportStar(require("./string.utils"), exports);

package/lib/utils/path.utils.d.ts

@@ -0,0 +1 @@
+export declare const getCallerFileName: (fileIndex?: number) => string;

package/lib/utils/path.utils.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCallerFileName = void 0;
+const getStacks = () => {
+    const originalPrepareStackTrace = Error.prepareStackTrace;
+    Error.prepareStackTrace = (_, stack) => stack;
+    const err = new Error();
+    const stacks = err.stack;
+    Error.prepareStackTrace = originalPrepareStackTrace;
+    return stacks;
+};
+const getCallerFileName = (fileIndex = 5) => {
+    const stacks = getStacks();
+    return stacks[fileIndex].getFileName();
+};
+exports.getCallerFileName = getCallerFileName;

package/lib/utils/resource.utils.d.ts

@@ -0,0 +1,6 @@
+import { type LambdaMetadata, type ResourceMetadata } from '../decorators';
+import type { ClassResource } from '../types';
+export declare const getResourceMetadata: <T = ResourceMetadata>(classResource: ClassResource) => T;
+export declare const getResourceHandlerMetadata: <T = LambdaMetadata>(classResource: ClassResource) => T[];
+export declare const getMetadataByKey: <T>(classResource: ClassResource, key: string) => T;
+export declare const getMetadataPrototypeByKey: <T>(classResource: ClassResource, key: string) => T;

package/lib/utils/resource.utils.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetadataPrototypeByKey = exports.getMetadataByKey = exports.getResourceHandlerMetadata = exports.getResourceMetadata = void 0;
+const decorators_1 = require("../decorators");
+const getResourceMetadata = (classResource) => {
+    return Reflect.getMetadata(decorators_1.ResourceReflectKeys.resource, classResource);
+};
+exports.getResourceMetadata = getResourceMetadata;
+const getResourceHandlerMetadata = (classResource) => {
+    return Reflect.getMetadata(decorators_1.LambdaReflectKeys.handlers, classResource.prototype) || [];
+};
+exports.getResourceHandlerMetadata = getResourceHandlerMetadata;
+const getMetadataByKey = (classResource, key) => {
+    return Reflect.getMetadata(key, classResource);
+};
+exports.getMetadataByKey = getMetadataByKey;
+const getMetadataPrototypeByKey = (classResource, key) => {
+    return Reflect.getMetadata(key, classResource.prototype);
+};
+exports.getMetadataPrototypeByKey = getMetadataPrototypeByKey;

package/lib/utils/string.utils.d.ts

@@ -0,0 +1,5 @@
+export declare const capitalize: (str: string) => string;
+export declare const kebabCase: (str: string) => string;
+export declare const cleanString: (str: string) => string;
+export declare const cleanTemplateString: (str: string) => string;
+export declare const cleanAndCapitalize: (str: string) => string;

package/lib/utils/string.utils.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanAndCapitalize = exports.cleanTemplateString = exports.cleanString = exports.kebabCase = exports.capitalize = void 0;
+const capitalize = (str) => {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+};
+exports.capitalize = capitalize;
+const kebabCase = (str) => {
+    if (str === str.toUpperCase()) {
+        return str.toLocaleLowerCase();
+    }
+    return str
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+};
+exports.kebabCase = kebabCase;
+const cleanString = (str) => {
+    return str.replace(/[^a-zA-Z0-9]/g, '');
+};
+exports.cleanString = cleanString;
+const cleanTemplateString = (str) => {
+    return str
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .join(' ');
+};
+exports.cleanTemplateString = cleanTemplateString;
+const cleanAndCapitalize = (str) => {
+    return str
+        .split(/[^a-zA-Z0-9]+/)
+        .map((word) => (0, exports.capitalize)(word))
+        .join('');
+};
+exports.cleanAndCapitalize = cleanAndCapitalize;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lafken/common",
+  "version": "0.10.1",
+  "private": false,
+  "description": "Lafken utilities - TypeScript decorator factories and metadata reflection for infrastructure-as-code decorators",
+  "keywords": [
+    "aws",
+    "serverless",
+    "lafken",
+    "decorators",
+    "metadata",
+    "reflection",
+    "typescript",
+    "utility"
+  ],
+  "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/common"
+  },
+  "license": "MIT",
+  "author": "Aníbal Jorquera",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "reflect-metadata": "0.2.2"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.15.21",
+    "@swc/helpers": "^0.5.20",
+    "@vitest/runner": "^4.1.2",
+    "cdktn-vitest": "^1.0.0",
+    "typescript": "6.0.2",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.2"
+  },
+  "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"
+  }
+}