Documentation
¶
Overview ¶
Package commons provides dependency-free shared utilities for AWS Lambda.
It includes environment configuration, JSON-shaped cloning and merging, Base64 decoding, DynamoDB value conversion, bounded LRU caches, and invocation metadata. Import this package at github.com/rambow-cloud/powertools-lambda-go/commons; the repository root is its module, not an importable package.
Reuse and compatibility ¶
NewLRUCache creates a concurrency-safe bounded cache. NewUtility provides utility cold-start state, while Lambda wrappers share invocation identity through context. The optional commons/awssdk, commons/dynamodb, commons/metadata and commons/regex modules supply integrations without adding dependencies here.
Conversion helpers preserve the documented Powertools compatibility contracts, which can differ from Go's native type and numeric conventions. Consult the guide before replacing standard-library conversions with these helpers.
For usage and compatibility details, see the user guide.
Index ¶
- Constants
- func BoolEnv(key string, extended bool, fallback ...bool) (bool, error)
- func BoolEnvOr(key string, extended, fallback bool) bool
- func CloneValue(value any) any
- func DecodeBase64Buffer(value string) []byte
- func DecodeUTF8(input []byte) string
- func DeepMerge(target map[string]any, sources ...map[string]any) map[string]any
- func DynamoDBNumber(value string) (any, error)
- func FormatXRayTraceID(id string) string
- func FromBase64(input string, encoding ...string) ([]byte, error)
- func GetType(value any) string
- func InitializationType() string
- func IsDevMode() bool
- func IsIntegerNumber(value any) bool
- func IsNull(value any) bool
- func IsNullOrUndefined(value any) bool
- func IsNumber(value any) bool
- func IsRecord(value any) bool
- func IsRegExp(value any) bool
- func IsRequestXRaySampled(ctx context.Context) bool
- func IsRunningInLambda() bool
- func IsStrictEqual(left, right any) bool
- func IsString(value any) bool
- func IsStringUndefinedNullEmpty(value any) bool
- func IsTruthy(value any) bool
- func IsValidServiceName(name string) bool
- func NumberEnv(key string, fallback ...float64) (float64, error)
- func ParseNumber(value string) float64
- func ResolveServiceName(explicit, fallback string) string
- func ServiceName() string
- func ShouldUseInvokeStore() bool
- func SortObjectKeys(keys []string)
- func StringEnv(key string, fallback ...string) (string, error)
- func TraceHeader(ctx context.Context) string
- func TrimSpace(value string) string
- func UnmarshallDynamoDB(input map[string]any) (map[string]any, error)
- func XRayTraceData(ctx context.Context) map[string]string
- func XRayTraceID(ctx context.Context) string
- type DynamoDBAttributeError
- type EnvironmentError
- type LRUCache
- type Utility
Examples ¶
Constants ¶
const ReferenceVersion = "2.35.0"
const Version = "0.1.0-dev"
Variables ¶
This section is empty.
Functions ¶
func BoolEnvOr ¶
BoolEnvOr preserves the fallback policy of utilities whose constructors cannot return errors.
func CloneValue ¶
CloneValue isolates acyclic decoded configuration values, retaining opaque objects. It preserves keys and bytes; DeepMerge has different key-filtering/array semantics.
func DecodeBase64Buffer ¶
DecodeBase64Buffer follows Buffer's permissive decoding, accepting URL-safe symbols and ignoring non-alphabet characters. FromBase64 remains strict.
func DecodeUTF8 ¶
DecodeUTF8 replaces each maximal malformed subpart, as Buffer.toString does.
func DeepMerge ¶
DeepMerge mutates target, merges arrays by index, and clones incoming containers. Constructor/prototype keys and references to an ancestor are skipped like the reference. Go nil represents null and replaces an existing value; it is not JavaScript undefined.
func DynamoDBNumber ¶
DynamoDBNumber returns float64 for safe numbers and *big.Int for large integer strings. Large decimal/exponent forms fail, matching the reference BigInt conversion.
func FormatXRayTraceID ¶
FormatXRayTraceID converts a nonzero 32-digit trace ID to the X-Ray wire format. This formats an identifier without importing either tracing SDK.
func FromBase64 ¶
FromBase64 preserves the reference's validation-before-encoding contract. Omitted encoding returns the validated input bytes; use "base64" to decode.
func InitializationType ¶
func InitializationType() string
func IsIntegerNumber ¶
func IsNullOrUndefined ¶
func IsRequestXRaySampled ¶
func IsRunningInLambda ¶
func IsRunningInLambda() bool
func IsStrictEqual ¶
func IsTruthy ¶
IsTruthy preserves Commons semantics: empty arrays/objects are false. It is deliberately distinct from JavaScript's language-level truthiness.
func IsValidServiceName ¶
func ParseNumber ¶
ParseNumber implements the string conversions used by the pinned Number helpers. Invalid strings return NaN; NumberEnv turns that into a typed configuration error.
func ResolveServiceName ¶
ResolveServiceName keeps fallback policy explicit at the consuming utility.
func ServiceName ¶
func ServiceName() string
func ShouldUseInvokeStore ¶
func ShouldUseInvokeStore() bool
func SortObjectKeys ¶
func SortObjectKeys(keys []string)
SortObjectKeys orders keys in place like JavaScript Object.keys: canonical array indices first in numeric order, followed by other keys in their existing order. Callers supply unique keys and preserve insertion order before calling it.
func TraceHeader ¶
TraceHeader prefers request-local data, including an explicitly empty header. Concurrent Go invocations must not fall back to a process-wide trace header.
func UnmarshallDynamoDB ¶
UnmarshallDynamoDB maps the Commons raw AttributeValue-object API. Raw B values are retained unchanged, unlike SDK wire-level binary decoding.
func XRayTraceID ¶
Types ¶
type DynamoDBAttributeError ¶
type DynamoDBAttributeError struct{ Message string }
func (*DynamoDBAttributeError) Error ¶
func (e *DynamoDBAttributeError) Error() string
type EnvironmentError ¶
type EnvironmentError struct{ Key, Expected string }
func (*EnvironmentError) Error ¶
func (e *EnvironmentError) Error() string
type LRUCache ¶
type LRUCache[K comparable, V any] struct { // contains filtered or unexported fields }
LRUCache provides capacity eviction without a TTL policy. Values remain caller-owned.
func NewLRUCache ¶
func NewLRUCache[K comparable, V any](capacity ...int) *LRUCache[K, V]
NewLRUCache defaults to 100 entries. Non-positive capacities retain no entries.
Example ¶
package main
import (
"fmt"
"github.com/rambow-cloud/powertools-lambda-go/commons"
)
func main() {
cache := commons.NewLRUCache[string, string](2)
cache.Add("region", "ap-east-1")
region, found := cache.Get("region")
fmt.Println(region, found)
}
Output: ap-east-1 true
type Utility ¶
type Utility struct {
// contains filtered or unexported fields
}
Utility maps the reference per-instance cold-start helper. Composed Lambda wrappers retain their separate, shared invocation identity in internal/invocation.
func NewUtility ¶
func NewUtility() *Utility
Source Files
Directories