@lafken/common 0.7.0 → 0.8.0

package/README.md

@@ -1,66 +1,414 @@
 # @lafken/common
 
-`@lafken/common` is the core utility package for the Lafken framework. It provides the essential factory functions and utilities used to create the decorators that define infrastructure resources and Lambda handlers throughout the ecosystem.
+`@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`.
 
-## Features
+## Installation
 
-### Decorator Factories
+```bash
+pnpm add @lafken/common
+```
+
+## Overview
 
-The package exports powerful factories to create custom decorators that integrate with the framework's metadata system.
+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:
 
-#### `createResourceDecorator`
+| 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                |
 
-Use this factory to create class-level decorators that mark a class as a deployable resource (e.g., a State Machine, a Queue, or a custom Event).
+## Decorator Factories
 
-It automatically captures:
-- The resource name.
-- The file path and folder name (for bundling).
-- Custom metadata defined in your props.
+### `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.
 
 ```typescript
 import { createResourceDecorator } from '@lafken/common';
 
-export const MyCustomResource = createResourceDecorator({
-  type: 'MY_CUSTOM_RESOURCE',
-  callerFileIndex: 5, // Adjusts stack trace to find the caller file
+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:
 
-// Usage
-@MyCustomResource({ ... })
-export class MyService { ... }
+```typescript
+@MyService({ name: 'notifications', retryCount: 5 })
+export class NotificationService { ... }
 ```
 
-#### `createLambdaDecorator`
+**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`
 
-Use this factory to create method-level decorators that mark methods as Lambda function handlers. It handles:
-- Method metadata reflection.
-- Argument injection (Event, Context, Callback).
+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.
 
 ```typescript
 import { createLambdaDecorator } from '@lafken/common';
+import type { LambdaMetadata } from '@lafken/common';
+
+export interface PublishProps {
+  name: string;
+  lambda?: LambdaProps;
+}
 
-export const MyLambdaTrigger = <T>(props: T) =>
-  createLambdaDecorator({
+export interface PublishMetadata extends PublishProps {
+  name: string;
+}
+
+export const Publish = (props: PublishProps) =>
+  createLambdaDecorator<PublishProps, PublishMetadata>({
     getLambdaMetadata: (props, methodName) => ({
       ...props,
       name: methodName,
     }),
   })(props);
+```
+
+Usage:
+
+```typescript
+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.
+
+```typescript
+import { createEventDecorator } from '@lafken/common';
+
+export const Event = createEventDecorator({
+  prefix: 'my-service',
+  enableInLambdaInvocation: false,  // Only capture metadata during build
+});
+```
+
+Usage:
+
+```typescript
+class NotificationService {
+  @Publish({ name: 'send-email' })
+  sendEmail(@Event(EmailPayload) event: EmailPayload) { ... }
+}
+```
+
+### `Context`
+
+A built-in parameter decorator that injects the Lambda execution context:
+
+```typescript
+import { Context } from '@lafken/common';
 
-// Usage
 class MyService {
-  @MyLambdaTrigger({ ... })
-  handleRequest(@Event() event: any) { ... }
+  @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.
+
+```typescript
+import { createFieldDecorator } from '@lafken/common';
+
+export const Field = createFieldDecorator({
+  prefix: 'my-service',
+  getMetadata: () => ({}),
+});
+```
+
+Usage:
+
+```typescript
+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.
+
+```typescript
+import { createPayloadDecorator } from '@lafken/common';
+
+export const Payload = createPayloadDecorator({
+  prefix: 'my-service',
+  createUniqueId: true,   // Append a counter if names collide
+});
+```
+
+Usage:
+
+```typescript
+@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`:
+
+```typescript
+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`:
+
+```typescript
+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:
+
+```typescript
+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.
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+// In your lafken-types.d.ts
+declare module '@lafken/common' {
+  interface ModulesAvailable {
+    core: {
+      Queue: { 'email-queue': string };
+    };
+  }
+  interface DynamoTableAvailable {
+    'users-table': string;
+  }
 }
 ```
 
-### Metadata Utilities
+## 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        |
 
-`@lafken/common` provides utilities to read the metadata stored by these decorators, which resolvers use to build the actual infrastructure.
+### Key Types
 
-- `getResourceMetadata(target)`: Retrieves metadata from a resource class.
-- `getResourceHandlerMetadata(target)`: Retrieves metadata for all lambda handlers in a class.
+| 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                       |
 
-## Usage
+## License
 
-This package is intended for internal use within the Lafken framework or for advanced users extending the framework with custom resource types. It ensures consistent metadata handling across all `@lafken/*` packages.
+MIT

package/lib/decorators/field/field.js

@@ -61,10 +61,13 @@ const getFieldMetadata = (props) => {
         destinationName,
         name: fieldProps?.name || destinationName,
     };
-    const primitiveType = (0, exports.getPrimitiveType)(type);
+    let primitiveType = (0, exports.getPrimitiveType)(type);
+    if (!primitiveType && fieldProps?.type) {
+        primitiveType = (0, exports.getPrimitiveType)(fieldProps.type);
+    }
     const typeHasValue = exports.mapTypeofValueToPrimitiveType[typeof fieldProps?.type];
     if (fieldProps?.type !== undefined) {
-        if (typeof fieldProps.type === 'function') {
+        if (typeof fieldProps.type === 'function' && !primitiveType) {
             return getObjectMetadata(metadata, fieldProps.type, prefix);
         }
         if (Array.isArray(fieldProps.type)) {

package/lib/decorators/lambda/lambda.d.ts

@@ -4,5 +4,4 @@ import { type CreateEventDecoratorProps, type CreateLambdaDecoratorProps, Lambda
 export declare const reflectArgumentMethod: (target: Function, methodName: string, type: LambdaArgumentTypes) => void;
 export declare const createLambdaDecorator: <T, M>({ getLambdaMetadata, descriptorValue, argumentParser, }: CreateLambdaDecoratorProps<T, M>) => (props?: T) => (target: any, methodName: string, descriptor: PropertyDescriptor) => any;
 export declare const createEventDecorator: ({ enableInLambdaInvocation, prefix }: CreateEventDecoratorProps) => (eventField: AllowedTypes) => (target: any, methodName: string, _number: number) => void;
-export declare const Callback: () => (target: any, methodName: string, _number: number) => void;
 export declare const Context: () => (target: any, methodName: string, _number: number) => void;

package/lib/decorators/lambda/lambda.js

@@ -1,13 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = exports.Callback = exports.createEventDecorator = exports.createLambdaDecorator = exports.reflectArgumentMethod = void 0;
+exports.Context = exports.createEventDecorator = exports.createLambdaDecorator = exports.reflectArgumentMethod = void 0;
 require("reflect-metadata");
 const utils_1 = require("../../utils");
 const field_1 = require("../field");
 const lambda_types_1 = require("./lambda.types");
 const argumentsByType = {
     [lambda_types_1.LambdaArgumentTypes.event]: ({ event }) => event,
-    [lambda_types_1.LambdaArgumentTypes.callback]: ({ callback }) => callback,
     [lambda_types_1.LambdaArgumentTypes.context]: ({ context }) => context,
 };
 const reflectArgumentMethod = (target, methodName, type) => {
@@ -30,8 +29,8 @@ const createLambdaDecorator = ({ getLambdaMetadata, descriptorValue, argumentPar
         ...argumentsByType,
         ...argumentParser,
     };
-    descriptor.value = async (event, context, callback) => {
-        const methodArguments = (lambdaArguments?.[methodName] || []).map((argumentType) => mapArgumentMethod[argumentType]({ event, context, methodName, target, callback }));
+    descriptor.value = async (event, context) => {
+        const methodArguments = (lambdaArguments?.[methodName] || []).map((argumentType) => mapArgumentMethod[argumentType]({ event, context, methodName, target }));
         const response = await originalValue.apply(this, methodArguments);
         return response;
     };
@@ -53,10 +52,6 @@ const createEventDecorator = ({ enableInLambdaInvocation = false, prefix }) => (
     reflectEventMetadata(target, methodName, lambda_types_1.LambdaReflectKeys.event_param, field);
 };
 exports.createEventDecorator = createEventDecorator;
-const Callback = () => (target, methodName, _number) => {
-    (0, exports.reflectArgumentMethod)(target, methodName, lambda_types_1.LambdaArgumentTypes.callback);
-};
-exports.Callback = Callback;
 const Context = () => (target, methodName, _number) => {
     (0, exports.reflectArgumentMethod)(target, methodName, lambda_types_1.LambdaArgumentTypes.context);
 };

package/lib/decorators/lambda/lambda.types.d.ts

@@ -103,17 +103,15 @@ export declare enum LambdaReflectKeys {
 }
 export declare enum LambdaArgumentTypes {
     event = "event",
-    callback = "callback",
     context = "context"
 }
 export type CallbackParam = (error: boolean | null, response?: any) => void;
 export type LambdaArguments = Record<string, LambdaArgumentTypes[]>;
-export type LambdaArgumentsType = Record<LambdaArgumentTypes, ({ event, context, callback, }: {
+export type LambdaArgumentsType = Record<LambdaArgumentTypes, ({ event, context, }: {
     event: any;
     context: any;
     methodName: string;
     target: any;
-    callback: CallbackParam;
 }) => any>;
 export interface CreateLambdaDecoratorProps<T, M> {
     getLambdaMetadata: (params: T, methodName: string) => M;

package/lib/decorators/lambda/lambda.types.js

@@ -10,6 +10,5 @@ var LambdaReflectKeys;
 var LambdaArgumentTypes;
 (function (LambdaArgumentTypes) {
     LambdaArgumentTypes["event"] = "event";
-    LambdaArgumentTypes["callback"] = "callback";
     LambdaArgumentTypes["context"] = "context";
 })(LambdaArgumentTypes || (exports.LambdaArgumentTypes = LambdaArgumentTypes = {}));

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

@@ -31,3 +31,7 @@ export type OnlyOneKey<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/utils/string.utils.d.ts

@@ -2,3 +2,4 @@ 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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cleanTemplateString = exports.cleanString = exports.kebabCase = exports.capitalize = void 0;
+exports.cleanAndCapitalize = exports.cleanTemplateString = exports.cleanString = exports.kebabCase = exports.capitalize = void 0;
 const capitalize = (str) => {
     return str.charAt(0).toUpperCase() + str.slice(1);
 };
@@ -27,3 +27,10 @@ const cleanTemplateString = (str) => {
         .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

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/common",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Lafken utilities - TypeScript decorator factories and metadata reflection for infrastructure-as-code decorators",
   "keywords": [
@@ -31,10 +31,12 @@
     "reflect-metadata": "0.2.2"
   },
   "devDependencies": {
-    "@types/jest": "30.0.0",
-    "jest": "30.2.0",
-    "ts-jest": "29.4.6",
-    "ts-node": "10.9.2"
+    "@swc/core": "^1.15.11",
+    "@swc/helpers": "^0.5.18",
+    "@vitest/runner": "^4.0.18",
+    "cdktn-vitest": "^1.0.0",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=20.19"
@@ -44,9 +46,9 @@
   },
   "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": "jest",
-    "test:coverage": "jest --coverage"
+    "test": "vitest"
   }
 }