typelevel/feral
53.3
Adequate · 7 November 2026
4k
lines of production code
Scala
primary language
4
measurements over time
What this system is
Feral is a Scala library that provides a framework for writing serverless functions targeting AWS Lambda and Google Cloud Functions on both JVM and JavaScript runtimes. It offers type-safe handlers for a wide range of cloud events, including HTTP APIs, message queues, and storage triggers, while integrating with cats-effect for resource management and Natchez for distributed tracing. The system also includes tooling such as an sbt plugin for packaging Scala.js functions and automated migration rules to simplify API upgrades.
How it got here
2021 — Scala.js support and API modernization
16 changes.
The project expanded its serverless framework to support AWS Lambda on JavaScript runtimes, introducing platform-specific implementations and an sbt plugin for packaging Scala.js functions. Concurrently, the core API was modernized by renaming invocation types for clarity, adding distributed tracing support via Natchez, and updating event models to include CloudFormation and HTTP API v2 handlers.
2022–2026 — Scalafix migration and Google Cloud support
14 changes.
This period focused on automating the migration to Feral v0.3.0 through new Scalafix rules and comprehensive test coverage across JVM, JavaScript, and CloudFormation modules. It also introduced support for Google Cloud HTTP Functions on Scala.js and expanded example projects to demonstrate integration with Http4s, distributed tracing, and AWS services.
Features
Add Scala.js facade for AWS Lambda Context including custom client context fields
A new Scala.js facade file (Context.scala) has been added to the JS lambda module to map AWS Lambda's Context interface. This facade exposes standard context properties such as function name, version, ARN, and remaining time, along with identity and environment details. Notably, it includes support for the \clientContext.custom\ field, allowing access to custom key-value pairs passed by the client, as well as standard client and environment metadata like app version and platform information.
lambda/js/src/main/scala/feral/lambda/facade · high confidence
Add sbt plugin for packaging Scala.js Lambda functions
A new \LambdaJSPlugin\ has been introduced to simplify the build process for AWS Lambda functions written in Scala.js. This plugin automatically configures the Scala.js linker to output a CommonJS module, sets the output filename to \index.js\, and ensures a full optimization stage for the npm package, allowing users to easily bundle their serverless applications.
sbt-lambda/src/main · high confidence
Added Http4s Google Cloud example
A new example file (examples/js/src/main/scala/feral/examples/Http4sGoogleCloud.scala) demonstrates how to implement a Google Cloud HTTP function using the Http4s library, providing a concrete reference for users integrating feral with Http4s on the JavaScript platform.
examples/js · high confidence
Added Http4s and Kinesis Lambda examples with distributed tracing
New example files have been added to the shared examples module to demonstrate how to build AWS Lambda functions using the feral library. The \Http4sLambda\ example shows how to handle API Gateway v2 events using Http4s, integrating with Natchez and AWS X-Ray for distributed tracing. The \KinesisLambda\ example (specifically implementing an SQS handler in the code) demonstrates the simpler \IOLambda.Simple\ pattern, showing how to initialize resources like a Skunk database session and perform tracing within the handler.
examples/shared · high confidence
Added IOCloudHttpFunction for Google Cloud HTTP Functions on Scala.js
A new abstract class IOCloudHttpFunction has been added to the google-cloud-http4s/js module, enabling users to build Google Cloud HTTP Functions using Scala.js. This class provides a main entry point that registers an HTTP handler via the @google-cloud/functions-framework, bridging incoming Node.js requests to an http4s HttpApp managed by cats.effect.IO. Users can now extend this class to define their function's handler as a Resource\[IO, HttpApp\[IO\]\], allowing for proper resource lifecycle management within the serverless environment.
google-cloud-http4s/js · high confidence
Added JSON codecs for Instant and ByteVector types
New serialization and deserialization codecs have been added to the Google Cloud events module to handle \java.time.Instant\ and \scodec.bits.ByteVector\ types. Users can now automatically decode \Instant\ values from both ISO-8601 string formats and epoch-millisecond longs, and decode \ByteVector\ data from base64-encoded strings, ensuring consistent type handling for event payloads.
google-cloud/shared/src/main · high confidence
Added JVM example for Google Cloud HTTP functions
A new example file, Http4sGoogleCloud.scala, has been added to the JVM examples directory. It demonstrates how to implement a Google Cloud HTTP function using the http4s library and the feral-googlecloud library, specifically by extending the IOCloudHttpFunction trait to handle GET requests.
examples/jvm · high confidence
Initial project setup and documentation
The repository has been initialized with a comprehensive README describing the feral framework for writing serverless functions in Scala targeting AWS Lambda on JVM and JavaScript runtimes. Configuration files have been added to enforce code formatting via scalafmt 3.10.6, manage static analysis with scalafix, and automate pull request merging and labeling through Mergify. Additionally, JVM memory and garbage collection settings are now explicitly defined in .jvmopts, and IDE/build tool ignore rules have been updated to include Metals, Bloop, and VS Code.
(repo-wide) · high confidence
Introduce JS-specific Lambda platform implementations
Added platform-specific Scala.js implementations for the Lambda runtime, including \ContextPlatform\ to parse AWS Lambda context data (such as custom client context fields) from JavaScript objects, and \IOLambdaPlatform\ to register the Lambda handler function dynamically on the global exports object and manage asynchronous execution via a parallel dispatcher.
lambda/js/src/main/scala/feral/lambda · high confidence
New event models and CloudFormation support
Adds support for AWS CloudFormation custom resources, including the \CloudFormationCustomResourceRequest\ and \CloudFormationCustomResourceResponse\ types with validation for \PhysicalResourceId\. Introduces new event models for Google Cloud Pub/Sub (\MessagePublishedData\, \PubsubMessage\) and Cloud Storage (\StorageObjectData\, \CustomerEncryption\). Adds event types for AWS Lambda triggers including Kafka (\KafkaEvent\, \MskEvent\), S3 Batch Operations (\S3BatchEvent\, \S3BatchResult\), and AppSync Lambda Authorizer (\AppSyncLambdaAuthorizerEvent\). Updates existing event models to use \ByteVector\ for binary data and \Instant\ for timestamps, and deprecates \KinesisStreamEvent\ in favor of \kinesis4cats\.
repository · high confidence
Behavioural changes
Add explicit Instant decoder and deprecated type aliases
The library now includes an explicit circe decoder for java.time.Instant, enabling correct deserialization of timestamp fields in Lambda events. Additionally, deprecated aliases for API Gateway event types (APIGatewayProxyRequestEvent and APIGatewayProxyResponseEvent) have been added to maintain backward compatibility while encouraging migration to the new ApiGatewayProxyEvent and ApiGatewayProxyResult names.
lambda/shared/src/main/scala/feral/lambda/events · high confidence
Automated migration for Feral v0.3.0 API changes
A new Scalafix rule (V0\_3\_0Rewrites) is introduced to automatically update codebases migrating to Feral v0.3.0. This tool rewrites legacy type names (e.g., renaming \LambdaEnv\ to \Invocation\ and \APIGatewayProxyRequestEvent\ to \ApiGatewayProxyEvent\) and updates method calls on \ApiGatewayProxyHandler\ to their v2 equivalents, while also removing obsolete imports.
scalafix/rules · high confidence
CloudFormation custom resource handler now uses PUT and omits null values
The CloudFormation custom resource Lambda handler has been updated to send response events using the HTTP PUT method, aligning with AWS requirements, and configures the JSON encoder to drop null values from the response payload. Additionally, error responses now include only the first line of the stack trace to help ensure the total response size remains within the 4096-byte limit imposed by CloudFormation.
lambda-cloudformation-custom-resource/src/main · high confidence
Introduce ApiGatewayProxyHandlerV2 for HTTP API v2 support
The library now provides a dedicated handler for AWS API Gateway HTTP API v2 events via the new \ApiGatewayProxyHandlerV2\ object, which correctly decodes v2-specific fields such as cookies and raw query strings. The original \ApiGatewayProxyHandler\ remains available for REST API v1 events but is marked as deprecated in favor of the v2 handler. Users migrating to API Gateway HTTP APIs should switch to \ApiGatewayProxyHandlerV2\ to ensure proper handling of v2 event structures.
lambda-http4s/src/main · high confidence
JVM Lambda runtime re-architected for safer initialization and optimized execution
The JVM Lambda implementation has been rewritten to improve reliability and performance. Initialization is now non-lazy by default, with a fallback mechanism that detects startup errors and switches to lazy initialization to prevent cold-start failures. The runtime now uses a parallel Dispatcher for handling invocations and wraps the output stream in a Resource to ensure it is always closed, even if an error occurs. Additionally, JSON parsing and printing have been optimized by using Jawn directly, and the Context now supports custom fields from the client context.
lambda/jvm/src/main · high confidence
Refactored Lambda runtime with new Invocation model and tracing support
The Lambda runtime has been restructured to improve modularity and tracing integration. The \LambdaEnv\ has been renamed to \Invocation\, providing a cleaner abstraction for accessing event data and context. A new \IOLambda\ class simplifies handler definition by exposing a \handler\ method that returns a \Resource\, and a \Simple\ variant is available for basic use cases. Additionally, \TracedHandler\ and \AwsTags\ have been introduced to seamlessly integrate with Natchez for distributed tracing, automatically tagging spans with AWS ARN and request ID.
lambda/shared/src/main/scala/feral/lambda · high confidence
Renamed IOGoogleCloudHttp to IOCloudHttpFunction
The \IOGoogleCloudHttp\ class has been renamed to \IOCloudHttpFunction\ to better reflect its role as a base class for Google Cloud HTTP Functions. This change includes the corresponding update to the implementation file \IOCloudHttpFunction.scala\ and its test suite \IOCloudHttpFunctionSuite.scala\, ensuring that users referencing this class by its new name will continue to have access to the same functionality for handling HTTP requests and responses within Google Cloud Functions.
google-cloud-http4s/jvm · high confidence
Renamed Lambda environment types and added Scala 3-specific INothing encoder
The \LambdaEnv\ type alias has been renamed to \Invocation\, with the old name retained as a deprecated alias for backward compatibility. Several specific invocation types (e.g., \ApiGatewayProxyLambdaEnv\, \DynamoDbStreamLambdaEnv\) have also been renamed to more consistent names like \ApiGatewayProxyInvocationV2\ and \DynamoDbStreamInvocation\. Additionally, a Scala 3-specific \INothing\ type and its corresponding identity encoder have been introduced to improve type inference and handle cases where no output is desired, replacing previous implementations that may have relied on external dependencies or different encoders.
lambda/shared/src/main/scala-3 · high confidence
Renamed core invocation types and deprecated legacy aliases
The \LambdaEnv\ type and companion object have been renamed to \Invocation\ to better reflect their role as the core abstraction for handling Lambda events. Several specific invocation types (e.g., \ApiGatewayProxyLambdaEnv\, \DynamoDbStreamLambdaEnv\, \SqsLambdaEnv\) have been renamed to more consistent names like \ApiGatewayProxyInvocation\, \DynamoDbStreamInvocation\, and \SqsInvocation\. The old names are now deprecated aliases that will be removed in a future version. Additionally, \KinesisStreamLambdaEnv\ has been deprecated with a note that Kinesis support has moved to the \kinesis4cats\ library. A new \S3BatchInvocation\ type has been added to support S3 Batch events.
lambda/shared/src/main/scala-2 · high confidence
Updated V0\_3\_0 rewrite rules for Feral Lambda API migration
The V0\_3\_0 rewrite rules have been updated to reflect breaking changes in the Feral Lambda library. Users migrating code will now see \ApiGatewayProxyHandler\ replaced with \ApiGatewayProxyHandlerV2\, and various environment types (such as \ApiGatewayProxyLambdaEnv\, \DynamoDbStreamLambdaEnv\, etc.) rewritten to their corresponding \Invocation\-based counterparts (e.g., \ApiGatewayProxyInvocationV2\, \DynamoDbStreamInvocation\). Additionally, event and result types like \APIGatewayProxyRequestEvent\ and \APIGatewayProxyResponseEvent\ are migrated to \ApiGatewayProxyEvent\ and \ApiGatewayProxyResult\ respectively.
scalafix/output · high confidence
Test coverage
Added JVM-specific tests for IOLambda initialization behavior; Added decoder tests for Google Cloud Pub/Sub and Storage event data; Added property-based tests for CloudFormation custom resource serialization; Added scripted test for simple IO-based Lambda handler; Added test suite for TracedHandler syntax; Added test suite for scalafix rules; Added test suites for AWS Lambda event decoders; Added tests for API Gateway proxy event decoding; Added tests for IOLambda on JavaScript.
Dependencies
Upgrade to version 0.3 and update core dependencies
The project base version is bumped to 0.3, and core library dependencies are updated to cats-effect 3.6.3, circe 0.14.15, fs2 3.12.2, http4s 0.23.33, and natchez 0.3.8. The build now supports Scala 2.12.20, 2.13.17, and 3.3.7, while dropping Scala 2.12 support for the main cross-compiled modules. A new sbt plugin module (sbt-feral-lambda) is added with scripted tests, and the CI matrix is expanded to include JDK 17 and Node.js 20.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 61 → 53 (-7.4)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 75 → 75 (+0.0)
- Architecture 100 → 100 (+0.0)
- Maturity 52 → 50 (-2.4)
- Readiness 52 → 40 (-11.5)
- Security 81 → 68 (-12.7)
- Performance 100 → 100 (+0.0)
Resolved (3)
- Off-boarding risk: anonymized user #1
- Outdated: com.amazonaws:aws-lambda-java-core
- Outdated: com.google.cloud.functions.invoker:java-function-invoker
New (2)
- Dependency hygiene PARTLY measured — sbt declarations read, dependency currency not (Maven Central unreachable)
- Off-boarding risk: anonymized user #1
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
typelevel/feral was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 7 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 07f2e34732ae2ac41fc28c449a3a1dc14e02e7da — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-5f8314471808.