@lafken/common

@lafken/common is the core utility package for the Lafken framework. It provides the decorator factory functions, metadata reflection utilities, and shared types that power every @lafken/* package. If a Lafken package defines a decorator or reads infrastructure metadata, it depends on @lafken/common.

Installation

pnpm add @lafken/common

Overview

Lafken uses TypeScript decorators to declare infrastructure. This package provides the factories that create those decorators and the utilities that read the metadata they produce:

| Factory | Level | Purpose | | -------------------------- | ------ | -------------------------------------------- | | createResourceDecorator | Class | Mark a class as a deployable resource | | createLambdaDecorator | Method | Mark a method as a Lambda handler | | createEventDecorator | Param | Bind a method parameter to the Lambda event | | createFieldDecorator | Prop | Describe a typed field inside a payload class | | createPayloadDecorator | Class | Define a named payload schema |

Decorator Factories

createResourceDecorator

Creates a class-level decorator that marks a class as an infrastructure resource. The factory automatically captures the resource name, the file path and folder (used for Lambda bundling), and any custom metadata you define.

import { createResourceDecorator } from '@lafken/common';

export const RESOURCE_TYPE = 'MY_SERVICE' as const;

export interface MyServiceProps {
  name?: string;
  retryCount?: number;
}

export const MyService = createResourceDecorator<MyServiceProps>({
  type: RESOURCE_TYPE,
  callerFileIndex: 5,                       // Stack-trace index to resolve caller file
  getMetadata: (props) => ({                // Optional — transform props before storing
    ...props,
    retryCount: props.retryCount ?? 3,
  }),
});

Usage:

@MyService({ name: 'notifications', retryCount: 5 })
export class NotificationService { ... }

Captured metadata (ResourceMetadata):

| Field | Description | | -------------- | ---------------------------------------- | | type | Resolver identifier (MY_SERVICE) | | name | Explicit name or the class name | | foldername | Directory of the decorated file | | filename | File name (without .js extension) | | originalName | Original class name (for asset naming) | | minify | Whether to minify the bundle (true) |

createLambdaDecorator

Creates a method-level decorator that registers a method as a Lambda handler. It stores handler metadata and rewrites the method descriptor so the framework can inject arguments (@Event, @Context) at runtime.

import { createLambdaDecorator } from '@lafken/common';
import type { LambdaMetadata } from '@lafken/common';

export interface PublishProps {
  name: string;
  lambda?: LambdaProps;
}

export interface PublishMetadata extends PublishProps {
  name: string;
}

export const Publish = (props: PublishProps) =>
  createLambdaDecorator<PublishProps, PublishMetadata>({
    getLambdaMetadata: (props, methodName) => ({
      ...props,
      name: methodName,
    }),
  })(props);

Usage:

class NotificationService {
  @Publish({ name: 'send-email' })
  sendEmail(@Event() event: EmailPayload) {
    // handler logic
  }
}

LambdaProps — Optional Lambda-level configuration available through the lambda property:

| Property | Type | Description | | ------------- | ------------------- | --------------------------------------------- | | timeout | number | Execution timeout in seconds | | memory | number | Memory allocation in MB | | runtime | 24 \| 22 \| 20 | Node.js runtime version | | services | ServicesValues | IAM service permissions | | env | EnvironmentValue | Environment variables (static or dynamic) | | tags | Record<string, string> | Resource tags | | enableTrace | boolean | Enable AWS X-Ray tracing |

createEventDecorator

Creates a parameter-level decorator that binds a method parameter to the incoming Lambda event. It works with createFieldDecorator to map typed payload classes onto the raw event.

import { createEventDecorator } from '@lafken/common';

export const Event = createEventDecorator({
  prefix: 'my-service',
  enableInLambdaInvocation: false,  // Only capture metadata during build
});

Usage:

class NotificationService {
  @Publish({ name: 'send-email' })
  sendEmail(@Event(EmailPayload) event: EmailPayload) { ... }
}

Context

A built-in parameter decorator that injects the Lambda execution context:

import { Context } from '@lafken/common';

class MyService {
  @Handler()
  process(@Event(Input) event: Input, @Context() ctx: any) {
    console.log(ctx.functionName);
  }
}

createFieldDecorator

Creates a property-level decorator that describes a typed field inside a payload class. The field metadata is collected by resolvers to build event schemas (e.g., Step Functions input/output, API request bodies).

Supported types: String, Number, Boolean, nested classes, and arrays.

import { createFieldDecorator } from '@lafken/common';

export const Field = createFieldDecorator({
  prefix: 'my-service',
  getMetadata: () => ({}),
});

Usage:

class Address {
  @Field()
  street: string;

  @Field()
  city: string;
}

class UserPayload {
  @Field({ name: 'user_name' })   // Rename the field in the schema
  name: string;

  @Field()
  age: number;

  @Field({ type: Address })        // Nested object
  address: Address;

  @Field({ type: [String] })       // Array of primitives
  tags: string[];
}

createPayloadDecorator

Creates a class-level decorator that gives a payload class a name and optional metadata. This identity is used when resolvers reference the payload in generated infrastructure.

import { createPayloadDecorator } from '@lafken/common';

export const Payload = createPayloadDecorator({
  prefix: 'my-service',
  createUniqueId: true,   // Append a counter if names collide
});

Usage:

@Payload({ name: 'CreateUserInput' })
class CreateUserInput {
  @Field()
  email: string;
}

Metadata Utilities

Resolvers use these functions to read the metadata produced by the decorators above.

getResourceMetadata

Returns the ResourceMetadata stored on a class by createResourceDecorator:

import { getResourceMetadata } from '@lafken/common';

const metadata = getResourceMetadata(NotificationService);
// { type: 'MY_SERVICE', name: 'notifications', foldername: '...', ... }

getResourceHandlerMetadata

Returns an array of handler metadata stored by createLambdaDecorator:

import { getResourceHandlerMetadata } from '@lafken/common';

const handlers = getResourceHandlerMetadata<PublishMetadata>(NotificationService);
// [{ name: 'sendEmail', ... }]

getMetadataByKey / getMetadataPrototypeByKey

Low-level helpers to read any Reflect metadata by key from a class or its prototype:

import { getMetadataByKey, getMetadataPrototypeByKey } from '@lafken/common';

const payload = getMetadataByKey<PayloadMetadata>(MyClass, 'my-service:lafken:payload');
const fields  = getMetadataPrototypeByKey<FieldMetadata[]>(MyClass, 'my-service:lafken:field');

Build Environment

Decorators only capture metadata when the build environment flag is set. This prevents metadata side-effects during normal runtime execution.

• isBuildEnvironment() — Returns true when the LAFKEN_CONTEXT environment variable equals BUILD.
• enableBuildEnvVariable() — Sets the flag. Required in tests before declaring any decorated class.

import { enableBuildEnvVariable } from '@lafken/common';

describe('My resolver', () => {
  enableBuildEnvVariable();

  @MyService({ name: 'test' })
  class TestResource { ... }

  it('should capture metadata', () => {
    const meta = getResourceMetadata(TestResource);
    expect(meta.name).toBe('test');
  });
});

String Utilities

General-purpose string helpers used throughout the framework:

| Function | Description | Example | | ---------------------- | ---------------------------------------------------- | -------------------------------- | | capitalize(str) | Uppercase first letter | 'hello' → 'Hello' | | kebabCase(str) | Convert to kebab-case | 'MyService' → 'my-service' | | cleanString(str) | Remove non-alphanumeric characters | 'a-b_c' → 'abc' | | cleanAndCapitalize(str) | Clean + capitalize each word | 'my-service' → 'MyService' | | cleanTemplateString(str) | Trim + collapse multiline strings into one line | — |

Shared Types

Services & Permissions

The Services type provides typed IAM permission declarations for Lambda handlers:

import type { Services } from '@lafken/common';

// Shorthand — grants full service access
const services: Services[] = ['dynamodb', 's3'];

// Fine-grained — specific actions and resources
const services: Services[] = [
  { type: 'dynamodb', permissions: ['GetItem', 'PutItem'] },
  { type: 's3', permissions: ['GetObject'], resources: ['arn:aws:s3:::my-bucket/*'] },
  { type: 'custom', serviceName: 'ses', permissions: ['SendEmail'] },
];

Supported service types: dynamodb, s3, lambda, cloudwatch, sqs, state_machine, kms, ssm, event, and custom.

Environment Variables

import type { EnvironmentValue } from '@lafken/common';

// Static values
const env: EnvironmentValue = { TABLE_NAME: 'users' };

// Dynamic values — resolved at deploy time via resource references
const env: EnvironmentValue = ({ getResourceValue }) => ({
  TABLE_ARN: getResourceValue('dynamo::users-table', 'arn'),
});

Duration

import type { Duration } from '@lafken/common';

const timeout: Duration = 30;                              // seconds
const ttl: Duration = { type: 'days', duration: 7 };       // 7 days

Type-Safe Resource References

The package provides augmentable interfaces that enable type-safe resource names across modules. Packages extend these interfaces so that getResourceValue calls are validated at compile time:

// In your lafken-types.d.ts
declare module '@lafken/common' {
  interface ModulesAvailable {
    core: {
      Queue: { 'email-queue': string };
    };
  }
  interface DynamoTableAvailable {
    'users-table': string;
  }
}

API Reference

Decorator Factories

| Export | Description | | -------------------------- | ------------------------------------------ | | createResourceDecorator | Factory for class-level resource decorators | | createLambdaDecorator | Factory for method-level handler decorators | | createEventDecorator | Factory for parameter-level event binding | | createFieldDecorator | Factory for property-level field metadata | | createPayloadDecorator | Factory for class-level payload naming | | Context | Parameter decorator for Lambda context |

Metadata Readers

| Export | Description | | ---------------------------- | ------------------------------------------ | | getResourceMetadata | Read class resource metadata | | getResourceHandlerMetadata | Read method handler metadata | | getMetadataByKey | Read metadata by key from a class | | getMetadataPrototypeByKey | Read metadata by key from a prototype |

Utilities

| Export | Description | | ------------------------- | ---------------------------------------- | | enableBuildEnvVariable | Enable build mode for decorator capture | | isBuildEnvironment | Check if build mode is active | | getCallerFileName | Resolve the caller file from the stack | | capitalize | Capitalize a string | | kebabCase | Convert to kebab-case | | cleanString | Strip non-alphanumeric characters | | cleanAndCapitalize | Clean and capitalize each word | | cleanTemplateString | Collapse multiline string to one line |

Constants

| Export | Description | | ---------------------- | ------------------------------------ | | LAFKEN_CONTEXT | Environment variable name | | LAFKEN_CONTEXT_VALUE | Expected value for build mode |

Key Types

| Export | Description | | -------------------- | --------------------------------------------------- | | ResourceProps | Base props for resource decorators | | ResourceMetadata | Metadata shape stored by resource decorators | | LambdaProps | Lambda configuration (timeout, memory, runtime, ...) | | LambdaMetadata | Metadata shape for handler methods | | FieldMetadata | Discriminated union of field types | | PayloadMetadata | Metadata shape for payload classes | | Services | IAM permission declaration type | | ServicesValues | Array or function returning Services[] | | EnvironmentValue | Static or dynamic environment variables | | Duration | Seconds or { type, duration } object | | ClassResource | Generic class constructor type | | GetResourceValue | Callback type for cross-resource references | | DeepPartial<T> | Recursive partial type utility |

License

MIT