DEV Community: Damika-Anupama

Designing Asynchronous APIs with a Pending, Processing, and Done Workflow

Damika-Anupama — Thu, 12 Mar 2026 19:09:28 +0000

The Problem

Modern backend systems often integrate OCR, machine learning inference, or heavy data processing jobs that cannot complete within a typical HTTP request lifecycle. When a user sends a request that triggers a long-running operation, keeping the HTTP connection open until processing completes is usually a poor design choice. Long-running synchronous requests can still increase the risk of timeouts, tie up resources, and make failure handling more difficult, even when a platform supports longer request durations.

Although longer synchronous timeouts are possible in some environments, asynchronous APIs are still valuable as an architectural choice for resilience and better user experience. For example, AWS API Gateway increased its integration timeout limit beyond 29 seconds in June 2024 for Regional and private REST APIs, though with trade-offs such as possible reductions in account-level throttle quota.

The Core Idea

A practical way to handle this problem is to accept the request, create a job record, and return immediately, while a background worker processes the job asynchronously. The client can then periodically check the job status until the work is completed or fails.

HTTP Contract

A common HTTP approach for long-running work is to return 202 Accepted as soon as the request is accepted, then let the client check a separate status resource for updates. This matters because HTTP cannot later push the final result back into that same original response.

How Clients Receive Updates

In this article, the client checks job progress by polling a status endpoint. Polling is the simplest option, but it is not the only one: systems can also deliver updates using Server-Sent Events (SSE), WebSockets, or Webhooks, depending on the use case.

A Simple Endpoint Shape

A common way to expose this pattern is to separate job creation from job tracking.

POST /jobs → accepts the request and returns with a jobId or monitor URL
GET /jobs/{id} → returns the current job state, such as status, progress, result, or error

This style is commonly used in APIs for long-running jobs, where the initial request stays fast and the client follows a separate status resource until the job reaches a terminal state. See also MDN’s Prefer header for respond-async, and this practical guide on REST API design for long-running tasks.

The Status Lifecycle

Once the request has been accepted and the client has a way to track it, the job lifecycle can be described with a small set of states:

PENDING: When the backend accepts the request and creates a job record.
PROCESSING: When a separate worker starts processing the long-running job.
DONE: When the long-running job completes successfully.
ERROR: If the job fails during any stage, the status response should ideally include structured error details such as an error code, a human-readable message, whether the operation is retryable, and the step that failed if that information is known.

Formats such as Problem Details for HTTP APIs (RFC 9457) are useful for standardizing machine-readable error responses, while the initial 202 Accepted response still only means the work was accepted, not completed.

A similar idea appears in production APIs as well. For example, Stripe’s error handling documentation shows how structured error objects can include fields such as code, message, param, type, and links to relevant documentation, making debugging and client-side handling easier.

Example Error Payload

{
  "jobId": "12345",
  "status": "ERROR",
  "error": {
    "code": "OCR_TIMEOUT",
    "message": "Document processing exceeded the allowed time limit.",
    "retryable": true,
    "failedStep": "text-extraction"
  }
}

A job normally moves from PENDING to PROCESSING to DONE, but failures can occur during either PENDING or PROCESSING, transitioning the job into ERROR. Optional states may include RETRYING, CANCELLED, and PARTIAL_SUCCESS.

For better user experience, the status resource can optionally expose a progress field, such as 0–100, and the client can poll the status endpoint to show updates over time. However, this value is not always exact. In practice, progress may be estimate-based, stage-based, or omitted entirely when the backend cannot measure it reliably. See Google Cloud’s guide to long-running operations.

Implementation Approaches

To make this pattern more concrete, let's go through a practical example using Python, AWS, and SAM. You can access the code example here. Follow the instructions provided in the README, and don't forget to shut down any AWS service you launch during the experiment.

Why This Pattern Works Well

Responsive UX: The API can return quickly while the long-running work continues in the background, so the user is not left waiting with no visibility into what is happening. The request is accepted first and completed later through a separate status endpoint.
Retry Capability: Because the job state is stored separately from the original request, the system can apply timeouts, retries, and backoff more safely when transient failures occur. In practice, retries should be paired with idempotency and strategies such as timeouts, retries, and backoff with jitter.
Fault Isolation: The workflow can be split into smaller stages and handled by separate workers, which makes it easier to narrow failures down to a specific step instead of treating the whole process as one opaque unit. This kind of decoupling also prevents one slow or failing stage from directly blocking the initial request-response path.
Observability: When each stage is separated, it becomes easier to attach logs, metrics, and traces to each part of the workflow and understand where time is spent or where failures occur. Tools and standards such as OpenTelemetry’s observability primer help connect those signals into a clearer end-to-end view.
Scalability: Background workers can often be scaled independently from the API layer, which is useful when the long-running job needs more compute, memory, or concurrency than the initial request handler. For example, AWS documents that Lambda functions scale independently with concurrency limits and scaling behavior, which makes this split especially useful in serverless designs.

Real Challenges

Duplicate Execution: In asynchronous systems, retries and queue semantics can cause the same job to be delivered or processed more than once. For that reason, background workers and mutating endpoints should be designed to be idempotent, so repeating the same operation does not produce unintended side effects. With Amazon SQS standard queues, duplicate delivery is expected as part of at-least-once delivery behavior.
Stuck jobs: A job can remain in PENDING or PROCESSING longer than expected if a worker crashes, loses connectivity, or never updates its final state. In production, this usually needs timeouts, heartbeats, lease expiry, or a reconciliation process that detects and recovers stalled work. See AWS Batch alerts for stuck jobs.
Race conditions: When multiple workers, retries, or client actions try to update the same job at nearly the same time, the system can end up with lost updates or invalid state transitions. This is usually handled with conditional writes, optimistic locking, or version checks so only valid state changes are accepted. See DynamoDB optimistic locking.
Retry storms: If many clients or workers retry immediately after a failure, they can create a second wave of load that makes recovery even harder. Exponential backoff with jitter is a standard way to spread retries out and avoid synchronized spikes.
Visibility gaps: Once work moves into queues, workers, and downstream services, it becomes harder to understand where a job is failing or slowing down. Propagating correlation IDs and tracing context across components helps connect logs, traces, and metrics into one end-to-end view.

When NOT to Use This Pattern

Simple, fast operations: If the job finishes quickly, this pattern can add unnecessary complexity.
Strong consistency requirements: If the caller must know the final committed outcome immediately, asynchronous processing may be the wrong fit.
Transactional workflows: If several steps must succeed or fail together, a simple job-status pattern may not be sufficient.

Lessons From Real Usage

Async APIs improve UX, but production systems still need timeouts, retries, and cleanup rules.
A plain ERROR status is usually not enough; clients need structured error details and retry guidance.
A DONE status is often not enough on its own; clients may also need result metadata, timestamps, or follow-up links.
Progress values are useful, but they are often estimates rather than exact measurements.
Idempotency matters once retries and duplicate delivery become possible.
Polling is a good entry point, but not the only update model.

This pattern is a simple but powerful way to design APIs around long-running work. It improves responsiveness and separates request handling from background execution, but it also introduces operational concerns such as retries, idempotency, stuck jobs, and observability. In a follow-up article, I’ll go deeper into implementation details, production hardening, and more concrete code examples.

My GSoC '25 Experience

Damika-Anupama — Sun, 22 Feb 2026 12:10:33 +0000

What's GSoC

Google Summer of Code (gsoc) is one of open source code programs in the world. Every year summer, Google conducts this program to link open source organisations with new open source contributors. You can find gsoc organisations from here. Google also selects mentors per each organisation, mentors guide and evaluate contributors through out the summer to contribute organisations. In the beginning of the program, organisations define what are the projects they need to get completed or improved during summer, from the contributors, and mentors are allocated per each project. If you check gsoc timeline, you can get an idea how this normally works.

Why I'm Writing This Article

I want to share my 2025 gsoc experience with you guys. Furthermore what are the advantages of applying gsoc, working with open source organisations. Please consider this is not a success story or guide.

Who this Article for

This is more useful for the people who can contribute for gsoc. Please check the eligibility criteria for the contributors:

be eighteen (18) years of age or older upon registration for the Program;
for the duration of the Program, be eligible to work in the country in which they reside;
be a student or a beginner to open source software development.

If you're an undergraduate or a beginner to open source software development with a strong interest in programming, you can participate gsoc this time to grow your knowledge and profile. Here are some articles you may read why gsoc is so important: [1] [2] [3] [4]

You can enter gsoc as a contributor. First, you need to select an organisation and one of their projects they've listed. Then you need to create a project proposal for the project and submit on gsoc organisation portal during "GSoC contributor application period begins" to "GSoC contributor application deadline" period, please check the timeline. Normally, this is half a month of time period.

Why I wanted to do GSoC

During my university program, I learnt about gsoc from our seniors and lecturers, and the advantages novel programmers like us can get from open source code contribution. I researched about gsoc and found out famous open source organisations like Postgres, GitLab, Debian, Python and many more organisations are participating each year gsoc program and we can work on those organisation codebases and improve our experience. Isn't it great?

Furthermore we can work and get mentored by high experienced open source programmers all over the world. Rather than coding experience, novel programmers like us can improve engineering disciplines and soft skills too.

My Application History

I applied gsoc and got rejected in 2 previous years. When I was reviewing what went wrong, I identified:

There's a huge competition among new contributors and the contributors who applied once to get selected to the program again
Due to high competition, some projects may have multiple applicants and project proposal needs to be more descriptive and follow the rules that organisation has published.
Some mentors/ organisations expect contributors to solve their code repository (GitHub) issues and put some PRs to the project codebase to show their performance to the organization.
It's better to introduce ourselves to the organisation and communicate with organisation administrators and mentors regarding projects
Participate online meetings conducted by gsoc during contributor application period

So I understood it's not that easy to get selected and need to be more competitive. We need to show to the organisation why they choose our project proposal over the other applicants to the same project we're applying.

How competitive GSoC actually is

Although normally acceptance rate for gsoc is normally considered as 20%, year by year it's getting reduced, due to high competition. Here's the statistics about gsoc 25 program:

Based on the official Google Open Source Blog announcements, Google Summer of Code (GSoC) 2025 statistics:

Total Applicants (Submitting Proposals): 15,240 individuals from 130 countries submitted a total of 23,559 proposals.
Total Registrations: A record 98,698 people from 172 countries registered for the 2025 program.
Accepted Contributors: 1,280 contributors were accepted into the program for 2025.
Program Completion: While the coding period began on June 2, 2025, and concludes later in the year, the preliminary data indicates that 1,261 projects were completed by 185 mentoring organizations in 2025.

Key 2025 Statistics:

Acceptance Rate: The acceptance rate for applicants (1,280 accepted out of 15,240 applicants) was approximately 8.4%, making it one of the most competitive years in GSoC history.
Demographics: 92.32% of contributors are participating in their first GSoC.
Prior Experience: 66.3% of applicants had no prior open-source experience.

What organisations actually look for

Organisations and mentors really like when contributors get familiarised with their selected project(s) and related codebase. Most of the time project has well explained documentation(s) or wikis. It's better to go through most of documentations and understand the project as far as you can, because your project proposal reflects your understanding of the codebase. So gsoc is not only about your coding ability, it's a blend of understanding the codebase, communication, following instructions, and initiatives such as case studies, PRs and discussions.

My organization: Checker Framework

During gsoc 25 I got selected to the Checker Framework. It's a compile time tool that enhances Java development by preventing bugs through pluggable type-checking, addressing issues like null pointer dereferences and concurrency errors that Java's basic type system does not cover. It serves as a robust bug-finding and verification tool, ensuring specific error types are absent in programs. The framework is user-friendly, aligns with existing practices. I chose Checker Framework during 25 summer, because I'm familiar with java programming language and was curious to work with java annotations.

As like other open source organisations, there was a competition to apply this organisation too, they told me I got selected from dozens of applications! They have provided their list of projects for new contributors and guidelines for gsoc contributors, as many organisations do.

Contribution before acceptance

During application period, they asked me to do a case study: Use their annotation tools on one of my previous java projects or openly available smaller java project. This case study was the critical reason I got selected to the organisation. From the case-study they identify whether I understood their project. Here's the link of my case study, compare with main branch with other branches. Furthermore I had to go through checker framework documentation and their developer manual to understand the functionalities of their annotations.

Communication with mentors and community

Communication medium is different due to the organisation: slack, google groups, discord, GitHub discussions and issue threads and different chat platforms. Always mentors and organisation administrators have emails related to the organisations, but be careful some of them don't like applicants put them private emails, they ask to join organisation main communication channel, introduce yourself and discuss about projects.

Communication is one of the best skills you need to have during gsoc. Always you need to be concise and comprehensive about your work. Documenting your work is another format of communication. After getting selected to an organization, you definitely need to have meetings with your mentors. In my case, I had 2 meetings per week, in there I had to explain my work, blockers, suggestions, my problems and so on. Before meetings I had to email my mentors regarding meeting agenda and after the meeting I had to email them meeting summary and the to do list before next meeting in the same email thread.

You may face different challenges like time zones, clarity feedback cycles and so on. It's better and more professional if you clarify most of these challenges with your mentors in the communication medium, because most of the time they are super busy with their own schedules. This is why I mentioned communication is important. To enhance contact with your mentor during gsoc, you can refer these links:

What changed after getting accepted

I got selected to a 350hrs hard project (projects are categorised due to their scope). My project's whole plan and milestones were not defined. Since I had 2 meetings per week with my mentors, considerable changes were made related to the plan, how we were going to implement my project. So in reality I had to work on implementation as well as the defining the milestones of the project with my mentors. Furthermore week by week the responsibility was increased, I had to update the documentation, follow their guidelines before making pull request on their main branch, time management and etc.

Every organisation has their own code quality standards. This is important for open source developers, although you change your organisation you need to follow your current organisation coding standards, otherwise it's hard them to keep the code quality consistent for the future developments. I also went multiple times in my organisation documentations to get aware about their own quality standards and this was really helpful during coding and meetings with my mentors.

My code was reviewed in multiple levels. First, the checker framework has integrated an Azure pipeline to automatically execute my implementation changes on 20 different open source codebases (most of the cases, legacy open jdk versions), and if any of the checks fail, I must go to the Azure pipeline dashboard to discover and resolve the issue. If all automated tests pass, the next two or three mentors will review my modifications, and I must work on their code reviews. If all of these processes are completed successfully, the changes will be merged into the main repository. Another significant consideration is that each pull request/branch should only serve one purpose. If a PR consists of modifications relating to the implementation of a new Java annotation as well as the updating of documentation for another related annotation, I had to submit two separate pull requests.

What I learned (technical + non-technical)

GSoC'25 was my first time working on a large open source codebase. Reading a large codebase, extracting the required code segment in the correct file and the correct directory is a skill every developer needs to have. Running/ debugging code, reading terminal outputs and logs, checking documentations and reworking on relevant specific case I improved this skill. After me, checker framework new open source contributors also need to continue my project. So I was careful to write a maintainable code during my work.

During GSOC, it's essential to interact with mentors—who are experienced professionals—by demonstrating patience and professionalism. Initially lacking in professionalism, I learned to pay attention to mentor advice over time. Effective communication is key; when raising issues, specificity is crucial. Rather than express general confusion about a module, you should first go through the documentation, experiment with the module, and document results and errors. If confusion still exists, a detailed email to the mentor outlining the steps taken can facilitate understanding and guidance.

What I would do differently

In retrospect, I often overestimated my ability to manage various aspects of my project while underestimating the time commitment needed for each. If I have another opportunity applying gsoc, I would allocate more time to implement a crucial component of my work.

Advice to future applicants

Be careful about your project scope, tech stack and time period
Manage the time you spend on the project so that it does not interfere with your academic work or other personal activities.
Always try to learn from every mistake you make
Don't always make your mentor angry :)
Document well and read documents
Take a brake during burnouts!

GSoC is a great experience and a really good challenge every developer need to experience in their life. This time is your turn, so take it!

Understanding Declaration Merging in TypeScript

Damika-Anupama — Tue, 21 Jan 2025 15:03:22 +0000

Typescript compiler merges two declarations with the same name into a single definition while keeping their characteristics, and it may merge any number of declarations. This declaration generates entities from at least one of three categories:

Namespace-creating declarations create a namespace, which contains names that are accessed using a dotted notation.
Type-creating declarations do just that: they create a type that is visible with the declared shape and bound to the given name.
Value-creating declarations create values that are visible in the output JavaScript.

Declaration Type	Namespace	Type	Value
Namespace	X		X
Class		X	X
Enum		X	X
Interface		X
Type Alias		X
Function			X
Variable			X

Why is Declaration Merging Important?

Understanding declaration merging is crucial for several reasons. Firstly, it gives developers a significant advantage when working with existing JavaScript by allowing for more advanced abstraction concepts. Secondly, it enables the enhancement of library functionality, module augmentation, and global augmentation without altering the original source code. This not only streamlines the development process but also simplifies the maintenance of codebases by keeping modifications and extensions organized and consistent.

Through declaration merging, TypeScript developers can effectively extend existing types in a type-safe manner, introduce new functionality to existing libraries, and more seamlessly integrate third-party libraries into their projects. Whether you are dealing with interfaces, namespaces, or modules, mastering declaration merging opens up a world of possibilities in software development.

In the following sections, we will delve deeper into the basics of declaration merging, explore practical examples, and unveil best practices to harness this powerful feature to its full potential. Stay tuned as we unlock the advanced capabilities of TypeScript, making complex concepts more accessible and enhancing your coding proficiency.

Understanding the Basics of Declaration Merging

At the core of TypeScript's functionality is the compiler's ability to merge declarations. This capability is pivotal for leveraging TypeScript's full potential, allowing developers to define entities across three main groups: namespaces, types, and values. Each type of declaration interacts uniquely within the TypeScript environment, playing a critical role in the structure and behavior of your code.

The Three Pillars of TypeScript Declarations

Namespace-Creating Declarations: These declarations introduce a namespace, which is essentially a named container for a set of identifiers or names. Namespaces are accessed using dotted notation and are fundamental for organizing code and preventing name collisions in larger applications.
Type-Creating Declarations: As the name suggests, these declarations create types. TypeScript is known for its robust typing system, and type-creating declarations are at the heart of this system, defining the shape and behavior of the data structures used throughout your code.
Value-Creating Declarations: These declarations are responsible for creating values that are visible in the output JavaScript. Functions and variables are typical examples of value-creating declarations, forming the executable part of your code.

Understanding the distinctions and interactions between these declarations is essential for mastering declaration merging. Let's illustrate these concepts with a table:

This table clarifies how different declarations contribute to the structure of TypeScript code, laying the foundation for understanding the intricacies of declaration merging.

The Significance of Merging Types

In TypeScript, the merging of declarations unfolds a new dimension of coding flexibility and abstraction. By merging interfaces or namespaces, developers can incrementally build up existing types or functionalities without overwriting or duplicating code. This not only promotes DRY (Don't Repeat Yourself) principles but also enhances code readability and maintainability.

Merging Interfaces: The Foundation of Declaration Merging

In TypeScript, interfaces are used to define the shape of an object or function, specifying the expected properties, types, and methods that an entity should have. When two interfaces of the same name are defined, TypeScript doesn't throw an error or ignore one of them; instead, it merges their definitions into a single interface. This merged interface then contains all the members of the original interfaces, effectively combining their specifications.

How Interface Merging Works

Consider the following example to understand the mechanics of interface merging:

interface Box {
  height: number;
  width: number;
}

interface Box {
  scale: number;
}

let box: Box = { height: 5, width: 6, scale: 10 };

In this scenario, TypeScript merges the two Box interfaces into one, allowing the box variable to include properties defined in both interface declarations (height, width, and scale). This behavior showcases the seamless integration of separate type definitions, enhancing the modularity and scalability of your code.

Managing Member Conflicts in Merging

When merging interfaces, TypeScript enforces certain rules to ensure type safety:

Non-function members (properties) must be unique or have the same type if declared more than once. If a conflict arises (i.e., the same property is declared with different types), TypeScript will issue an error.
Function members are treated as overloads. This means that if multiple interfaces declare a function with the same name, TypeScript merges them into a single function with multiple overload signatures. The order of these signatures follows a specific precedence, with later declarations having higher priority.

Consider the Cloner interface example:

interface Cloner {
  clone(animal: Animal): Animal;
}

interface Cloner {
  clone(animal: Sheep): Sheep;
}

interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
}

// Merged interface Cloner
interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
  clone(animal: Sheep): Sheep;
  clone(animal: Animal): Animal;
}

The merged Cloner interface illustrates how TypeScript organizes overload signatures, ensuring the most specific types appear first in the merged definition.

Advantages of Interface Merging

Merging interfaces offers several advantages:

Flexibility: It allows for the incremental definition or extension of interfaces across different parts of a program or in different files, contributing to a more flexible codebase.
Extensibility: Libraries and frameworks can extend types defined by their users without requiring modifications to the original interface declarations.
Maintainability: By organizing related properties and methods under a single named entity, merged interfaces enhance code readability and maintainability.

Advanced Declaration Merging Scenarios: Merging Namespaces

Namespaces in TypeScript are used for organizing code into named groups, thereby avoiding naming collisions in larger applications. Similar to interfaces, when two or more namespaces with the same name are declared, TypeScript merges their contents into a single namespace. This feature is particularly useful for modularizing code and extending existing namespaces with additional functionality.

How Namespace Merging Works

Namespace merging combines the members of each namespace declaration into a single namespace. This merged namespace contains all exported members from each of the original namespaces. Let’s consider an example to illustrate this:

namespace Animals {
  export class Zebra { }
}

namespace Animals {
  export interface Legged { numberOfLegs: number; }
  export class Dog { }
}

// Resulting merged namespace Animals
namespace Animals {
  export class Zebra { }
  export interface Legged { numberOfLegs: number; }
  export class Dog { }
}

In this example, both Animals namespace declarations are merged into one, encompassing the Zebra class, the Legged interface, and the Dog class. This merging process facilitates a cohesive and organized structure for grouping related entities.

Merging Namespaces with Classes, Functions, and Enums

TypeScript's declaration merging extends beyond interfaces and namespaces to include classes, functions, and enums. This versatile feature allows for a range of flexible design patterns:

Namespaces with Classes: You can use namespaces to add static members to classes or to define inner classes. This pattern is useful for creating classes within classes, offering a neat organizational structure.

class Album {
  label: Album.AlbumLabel;
}

namespace Album {
  export class AlbumLabel { }
}

Namespaces with Functions: Functions can be extended with additional properties through namespaces, allowing for a functional programming style combined with the structured organization of object-oriented programming.

function buildLabel(name: string): string {
  return buildLabel.prefix + name + buildLabel.suffix;
}

namespace buildLabel {
  export let suffix = "";
  export let prefix = "Hello, ";
}

Namespaces with Enums: Enums can be extended with static members using namespaces, enhancing the functionality of enum types.

enum Color {
  red = 1,
  green = 2,
  blue = 4,
}

namespace Color {
  export function mixColor(colorName: string): number {
    // Implementation
  }
}

Considerations and Best Practices

When leveraging declaration merging, particularly with namespaces, it’s important to maintain clear and consistent documentation to ensure that the merged structure is understandable and maintainable. Additionally, be mindful of the visibility and accessibility of members, especially when dealing with private or non-exported members across merged declarations.

Namespace merging in TypeScript offers a powerful mechanism for organizing and extending code, providing developers with the flexibility to structure applications in a modular and extensible manner.

In the following sections, we will delve into practical examples of declaration merging, showcasing its application in real-world scenarios. Stay tuned for an in-depth exploration of how to leverage declaration merging to enhance your TypeScript projects.

Practical Examples of Declaration Merging

Merging Interfaces for Extensible Models

One of the most straightforward uses of declaration merging is to extend existing interfaces, allowing for incremental enhancements and compatibility with evolving codebases. Consider a scenario where you're building a library for UI components, and you need to extend an interface to include new properties without breaking existing implementations.

// Initial interface in the library
interface ButtonProps {
  label: string;
  onClick: () => void;
}

// Extension in a consumer's code
interface ButtonProps {
  color?: string;
}

// The resulting merged interface includes both sets of properties
function createButton(props: ButtonProps) {
  // Implementation that uses label, onClick, and optionally color
}

This example demonstrates how declaration merging facilitates the evolution of API interfaces in a backward-compatible manner.

Enhancing Functionality with Merged Namespaces

Namespaces can be merged with functions to augment the functions with additional properties or metadata, enabling a pattern often used in JavaScript libraries:

function networkRequest(url: string): any {
  // Implementation omitted for brevity
}

// Merging a namespace with the function to add properties
namespace networkRequest {
  export let timeout = 3000; // Default timeout for requests
}

// Usage
networkRequest.timeout = 5000; // Adjusting the default timeout

This pattern provides a flexible way to associate configurations or metadata with functions, enhancing their functionality without altering their core implementation.

Combining Enums and Namespaces for Richer Structures

Enums in TypeScript are a powerful way to define a set of named constants. By merging enums with namespaces, you can add static methods or properties to enums, enriching their functionality:

enum StatusCode {
  Success = 200,
  NotFound = 404,
  ServerError = 500,
}

namespace StatusCode {
  export function getMessage(code: StatusCode): string {
    switch (code) {
      case StatusCode.Success:
        return "Request succeeded";
      case StatusCode.NotFound:
        return "Resource not found";
      case StatusCode.ServerError:
        return "Internal server error";
      default:
        return "Unknown status code";
    }
  }
}

// Usage
console.log(StatusCode.getMessage(StatusCode.NotFound)); // "Resource not found"

This approach allows enums to serve not only as simple constants but also as namespaces for related functions or data, providing a more structured and intuitive way to manage related sets of values and behaviors.

Best Practices in Using Declaration Merging

When utilizing declaration merging, keep the following best practices in mind:

Document Merged Declarations: Ensure that merged interfaces, namespaces, and other entities are well-documented to maintain clarity and ease of use for other developers.
Avoid Overuse: While declaration merging offers great flexibility, overuse can lead to complicated code structures that are difficult to understand and maintain. Use it judiciously.
Ensure Compatibility: When extending libraries or third-party code, ensure that your extensions do not break existing functionality or expected behaviors.

Declaration merging in TypeScript opens up a multitude of possibilities for enhancing and structuring your code. By understanding and applying this powerful feature wisely, you can create more flexible, extensible, and maintainable applications.

Module Augmentation: Extending Existing Modules

Module augmentation is a powerful feature in TypeScript that leverages the concept of declaration merging to enhance or modify modules. This is particularly useful when working with third-party libraries or modules, as it allows you to tailor them to your specific needs without waiting for the library maintainers to make changes.

How Module Augmentation Works

To augment a module, you first import it, then declare additional properties, methods, or even interfaces within the same module scope. TypeScript automatically merges these declarations with the original module's declarations.

Consider a scenario where you're using a library that defines an Observable class, but you want to add a map function to its prototype:

// Original module in observable.ts
export class Observable<T> {
  // Original class implementation
}

// Augmentation in your own code
import { Observable } from './observable';

declare module './observable' {
  interface Observable<T> {
    map<U>(f: (x: T) => U): Observable<U>;
  }
}

Observable.prototype.map = function <T, U>(this: Observable<T>, f: (x: T) => U): Observable<U> {
  // Implementation of map
  return new Observable<U>();
};

This example illustrates how module augmentation allows for seamless extensions of existing modules, enriching their capabilities without modifying the original source.

Practical Applications of Module Augmentation

Module augmentation can be employed in various scenarios, including:

Adding new functionalities to third-party libraries: Enhance libraries by introducing new methods or properties that fit your specific requirements.
Plugin or theme development: Develop plugins or themes that extend core functionalities of frameworks or libraries.
Typing external libraries: Improve or correct the types of external libraries for better type checking and developer experience.

Best Practices and Considerations

While module augmentation offers significant flexibility, it's essential to use it judiciously:

Maintainability: Ensure that augmented modules remain maintainable and that the extensions are well-documented.
Compatibility: Regularly check for updates to the original module to ensure that your augmentations do not conflict with new versions.
Scope: Use module augmentation primarily for extending functionalities or fixing types. Avoid overusing it to the point where the original module's purpose or behavior becomes obscured. Module augmentation is a testament to TypeScript's versatility, enabling developers to tailor modules to their needs dynamically. As we progress, we'll explore how global augmentation can be utilized to extend the global scope with additional declarations.

The exploration of declaration merging in TypeScript demonstrates its profound impact on improving code organization, extensibility, and maintenance. Through practical examples and advanced techniques like module augmentation, developers can leverage these features to build more robust, flexible, and maintainable applications.

This concludes our deep dive into the intricacies of Declaration Merging in TypeScript, from the basics of merging interfaces to the advanced concepts of module and global augmentation. Armed with this knowledge, you're well-equipped to harness the full potential of TypeScript in your projects.

Online Machine Learning

Damika-Anupama — Sat, 07 Sep 2024 19:37:24 +0000

The concept of online learning emerged in the early 1990s, influenced by the increasing availability of real-time data and the need for models that adapt without retraining on full datasets. The Perceptron algorithm, introduced in the 1950s, laid the groundwork for modern online learning methods. Online machine learning is a learning paradigm in which the model learns progressively in real time by processing input points sequentially. As new data comes in, the model is updated continuously, which enables it to dynamically adjust to changing data distributions without requiring a full dataset retraining. This method works especially well in situations when data is streamed or varies over time.

There are few key characteristics:

Incremental learning involves updating the model with each new data point without the need to re-train on the entire dataset.
Real-time Adaptation is a crucial feature that allows a model to quickly adapt to continuous data arrivals.
The system efficiently reduces memory and computation costs by processing one data point at a time.

image description: Online Learning vs Batch / Offline Learning, source: https://www.linkedin.com/pulse/types-machine-learning-techniques-training-method-based-sharma/

Few use cases of Online Learning,

Real-time stock market predictions to analyze the most recent market data
Online advertising and click-through rate prediction
RL agent to predict the relevant insulin amount for a short time horizon, according to the real-time glucose level of type 1 diabetes patient
Spam filtering and network intrusion detection systems. As new patterns of spam or cyber-attacks emerge, the models are continuously updated to improve accuracy, ensuring timely detection of malicious activities with minimal manual intervention.

Meanwhile, here are few advantages and disadvantages in this learning paradigm.
Advantages:

Since small amounts of data are processed, this reduces resource requirements and improves memory efficiency and computation.
Suitable for cases in which data is delivered continuously, such as streaming data.
Capable of responding to changes in the non-stationary data distribution over time.
The model's fast updates, assisted by the availability of new data, allow for quick responses to changes in data trends, particularly in dynamic situations.

Disadvantages:

Small batches might introduce fluctuations, making them susceptible to noise.
In comparison to batch learning (opposite of online learning), it may take longer to converge to an optimal solution.
The learning rate and regularization parameters must be carefully tuned for performance.

Let's talk about the mathematical foundation of online learning. Gradient descent-based optimization methods are frequently employed, specifically stochastic gradient descent (SGD), which updates model parameters iteratively based on small batches or individual data points to minimize the objective function over time. Perceptron algorithm and Hoeffding tree (Streaming Decision Tree) are another algorithms that use online learning. Here's a sample code to demonstrate online learning to use SGD.

Above online learning with SGD code output, shows how accuracy of the model output may change with time, when new data samples are continuously coming. Check how above-mentioned advantages and disadvantages may apply to code, and output.

During online learning cumulative error rate is calculated by analyzing performance over time across all data points. This calculates how quickly the model adjusts to new patterns in the data. Memory efficiency relates to the processing of small data chunks. There are few related learning paradigms that crosses with ours:

Batch Learning / Offline Learning: Whole dataset all at once during training, only making updates to the model after the dataset has been thoroughly examined. Compared to online learning, this method usually produces updates that are more accurate and reliable, but it uses more memory and processing power. Batch learning is less effective in dynamic or streaming situations where data is always changing, as it is less flexible than online learning when it comes to real-time adaptation to new data.
Incremental Learning: Updates models incrementally as new data becomes available, retaining previous knowledge and incorporating new information. It's suitable for large datasets or computationally expensive scenarios, combining online learning and batch-based updates.
Active Learning: Involves selecting the most informative data points for learning, useful in scenarios with limited data.

Finally, let's discuss some modern applications regarding online learning. Real-time recommendation systems like Netflix, Amazon use online learning to recommend content as user preferences evolve. Banks and financial institutions use online models to detect fraudulent transactions in real-time. Continuously updating models in self-driving cars handle new sensor data from changing environments.
Future directions of this learning paradigm include Adversarial Robustness, Federated Online Learning, and Online Deep Learning.

Let's Play Snyk 🐶

Damika-Anupama — Wed, 06 Mar 2024 16:56:56 +0000

Hi folks, I'm diving into Snyk this time. This is a platform for developer security that helps protect infrastructure as code, dependencies, containers, and code. Snyk includes the following products and mostly focuses on security and dependency monitoring:

Snyk Code

Static application security testing (SAST): helps developers find and fix vulnerabilities in their code as they write it. This offers real-time scanning, fix advice, broad language and platform support, machine learning engine, risk prioritization, and workflow integration.

Features: Secure code without disrupting development workflow, save time and money by preventing code delays and security issues, and become quasi-security professionals with comprehensive security tooling and knowledge.

Snyk Open Source

source

What is Snyk Open Source? Software composition analysis (SCA) solution that helps developers find and fix security vulnerabilities and license issues in open source dependencies.
How does it work 🤔 Integrates with various developer tools, scans open source packages and dependencies for vulnerabilities and license issues, providing actionable advice and automated workflows for fixing them.
Why use it? Enables developers to secure open source code using industry-leading security and application intelligence, reducing risk and ensuring compliance with regulatory and internal security policies.

Snyk Container

What is Snyk Container? Developer-first solution that helps find, prioritize, and fix vulnerabilities in container images and Kubernetes workloads throughout the software development lifecycle.

Source

How does Snyk Container work? Snyk Container integrates with daily developers' tools, scans for vulnerabilities in base images, dependencies, Dockerfile commands, and Kubernetes manifests, provides remediation advice, recommendations, and priority scoring.
Why use Snyk Container? Snyk Container allows developers to secure containers and Kubernetes workloads without disrupting daily workflows, thereby saving development time, reducing security risks, and achieving compliance objectives.

Snyk Infrastructure as Code

What is Snyk IaC? Snyk IaC is a tool that helps developers secure their infrastructure as code (IaC) configurations from code to cloud. It scans IaC files for vulnerabilities and misconfigurations, provides remediation advice and fixes, and detects drift in running cloud environments.

Snyk IaC integrates with developer workflows, providing security feedback and suggested fixes. It enforces consistent security and compliance rules across SDLC and cloud using OPA's Rego query language. It enables proactive security issue fixation and unifies visibility and governance across multiple IaC frameworks and cloud providers.

Snyk AppRisk

What's Snyk AppRisk: A solution that helps teams build, deploy, and operate securely in the cloud by embedding security in developer workflows from code to cloud.

source

Key Features: Snyk AppRisk provides security feedback and fixes for code, dependencies, container images, and cloud infrastructure as code (IaC) across the software development life cycle (SDLC) and running cloud environments.
Benefits: Snyk AppRisk enables developers to proactively fix security issues in their IDE, CLI, and Git workflows, reducing backlogs and time to fix. It also unifies visibility and governance from code to cloud with a single policy engine and ruleset, and speeds up and scales developer-led fixes for cloud misconfigurations with direct links to the source IaC file in Git workflows.
Supported Technologies: Terraform, CloudFormation, ARM, Kubernetes, Docker, AWS, Azure, Google Cloud, and more. It also integrates with Sysdig for runtime security and OPA for policy enforcement.

Before we go any farther, I need to volunteer to tackle two key difficulties that you could be having 😉

What's the meaning of Snyk?
How to pronounce this word 👀 This Snyk support provides answers

Let's use Snyk

There're couple of ways we can use Snyk

You can install Snyk CLI using terminal, and scan your project using Snyk

IDE Plugins - my main IDE is VSCode, but you can also use Snyk in Jetbrains IDEs, Eclipse and Visual Studio

Git Repositories - GitHub, Bitbucket, Gitlab and Azure (TFS). From these GitHub and Bitbucket integrations are popular. For this you have to login with your relevant account

after you add github repositories to Snyk, you can see vulnerabilities in each repository Snyk dashboard's projects section

You can check each security vulnerability, in each project by going inside, and it'll show like this:

Settings allows you to adjust git repository Snyk configurations. This has an incredible collection of capabilities, that you may setup Snyk automated pull requests for repositories, enable Snyk scan for manual pull requests, activate Snyk for code, activate Snyk for IaC. Check your Snyk Usage (If you're using the Snyk free plan like me, you can see how much resource you've used). Snyk may be integrated with your existing notification system, such as Slack.

Here's a Snyk-bot's automatic pull request on GitHub repository

You can change Snyk configurations to check your repository code, IaC weekly due to limited resources in your plan.

Furthermore, you can add Snyk app to your GitHub account from the marketplace:

Snyk for CI/CD - Pipelines and integrations in AWS, Azure, Bitbucket and more

Image source

Can COLD STARTS be prevented by Webpack ❄️

Damika-Anupama — Sat, 03 Feb 2024 06:39:39 +0000

Hi folks, let's talk about Cold Starts in Cloud Services. I'm Focusing on the AWS cold starts, according to

The background details of cold starts
How cold starts begin
What are the effects of cold starts
How I tried to prevent cold starts
Further improvements.

I'll try my best to provide you updated details via this article. So, let's begin 😎

The background details of cold starts

If you work in a software company that uses cloud services in production, you've probably heard developers talk about cold starts. If not, now it’s the time to learn everything about cold starts. Maintaining cold starts in clouds, reduces service costs and the amount of time it takes to execute HTTP requests.

Cold start term is related to the Function-as-a-Service in cloud services and this article provides pretty good comparison and an analysis of Cold Starts in Serverless Functions across AWS (lambda), Azure (Functions), and GCP (Functions).

How cold starts begin

A cold start begins with how the architecture of the lambda service implemented in AWS. Normally when we sent an API request to lambda, lambda service works according to following order:

Is there a free execution environment? (Container with runtime)
If not, Create an Execution environment
Download lambda code
Initialize (Running code outside handler function)
Run handler function code

2, 3, 4 steps caused Cold Starts

Extracted from AWS re:Invent 2023 - Demystifying and mitigating AWS Lambda cold starts (COM305)

Then What's a lambda warm start

These execution environments (lambda instances) remain only 10 or 15 minutes after the first run (Cold start) of handler function. If another request comes during that time it uses already built virtual environment. This is the warm start. BUT if another request comes while already created environment is busy with another request, lambda service has to create another virtual environment (look above steps of lambda service working order and you can understand this process). Then lambda's concurrency increases by 1 (total concurrency = 1 + 1 = 2).

PS: When you’re working with lambda functions, you may probably work with AWS cloud watch. In there you may sometimes be confused with log groups and log streams. These log groups are created for 1 lambda service and 1 log stream is created for one lambda instance in the lambda service (source) in another words, when a cold start begins. So 1 cloud watch stream includes all the details of the lambda instance such as, details of cold start, warm starts, cached requests, logs, errors etc. AWS X-Ray works on these logs output by the cloud watch service.

What are the effects of cold starts

You might wonder why we are focusing on lambda cold starts. Because cold start implies that the relevant lambda instance is starting, the http request must wait until the lambda instance is warmed up, which may result in a few seconds of latency in the frontend website / mobile app. This leads to a poor user experience. Otherwise, if your application is a response-critical website, such as a bank app, an ecommerce website, or a stock market application, this could cause significant disaster.

How I tried to prevent cold starts

I used webpack to reduce the cold start time for AWS lambda functions. Normally, we use webpack for the bundling purposes in single page applications, basically on frontend frameworks such as Angular-CLI, React and more. In here we use the webpack's bundling, minifying and tree shaking features to bundle AWS NodeJS lambda functions.
My approach on applying webpack in microservices:

Install Webpack and other relevant dependencies
npm install --save-dev webpack webpack-cli ts-loader webpack-node-externals glob
Configure the webpack.config.ts where the index.ts as the entry point to webpack.

import * as path from "path";
import { Configuration } from "webpack";
import nodeExternals from "webpack-node-externals";
const config: Configuration = {
    entry: "./index.ts",
    target: "node",
    mode: "production",
    module: {
        rules: [
            {
                test: /\.ts$/,
                use: "ts-loader",
                exclude: /node_modules/,
            },
        ],
    },
    resolve: {
        extensions: [ ".ts", ".js" ],
    },
    output: {
        filename: "[name].js",
        path: path.resolve(__dirname, "lib"),
        libraryTarget: "commonjs2",
    },
    externalsPresets: { node: true }, // Use externalsPresets to specify Node.js environment
    externals: [nodeExternals()], // Use the function to exclude node_modules
};
export default config;

Modify package.json as

"scripts": {
  "build": "webpack --config webpack.config.ts"
}

Update tsconfig.json:

Added webpack.config.ts to the include array to ensure TS includes Webpack config file when compiling.

{
    "compilerOptions": {
        "module": "commonjs",
        "moduleResolution": "node",
        "esModuleInterop": true,
        "pretty": true,
        "sourceMap": true,
        "allowJs": true,
        "target": "es6",
        "outDir": "./lib",
        "baseUrl": "./",
        "types": ["chai", "node"],
    },
    "include": [
        "./**/*",
        "test/.mocharc",
        "webpack.config.js" 
    ],
    "exclude": [
        "node_modules", "lib"
    ]
}

After doing these changes you can build your code and you'll precisely see how your js files are minified and tree shaked dependencies. In here I reduced the package size of the output folder nearly 90% applying the webpack on my lambda functions. Please consider this might vary according to your architecture and other factors. But as a result of bundling the code using webpack, it should reduce the final output folder package size. Next, I went to check the impact of the webpack on lambda execution time.

How I conducted my tests:

I used 2 API calls to check the impact of webpack.

GET ALL - Get All Users
GET - Get User by ID

After sending couple of API requests to AWS lambda functions, I went to CloudWatch to see the results, later I used AWS X-ray, because it clearly shows only the relevant results of set of API calls (for this, first you should enable X-ray in your lambda function/s)

This image shows a set of API requests I sent to an instance of my lambda function. As I mentioned previously in this article, every instance starts with a cold start, and all the other instances invoke warm starts. You can figure out it by the Response Time. Meanwhile requests might be cached due to couple of reasons.

Caching

When we call the same request couple of times, response becomes cached. Caching may occur for a variety of reasons, including:

Lambda Container Reuse: AWS Lambda may reuse the same container for multiple invocations, which can lead to data persistence across invocations if our code uses global variables or similar constructs.
API Gateway Caching: If we’re invoking our Lambda through API Gateway, it might be caching responses.
Client-side Caching: Tools like Postman might cache responses based on headers.

So, we obtain responses without warm beginnings, and caching saves lambda service resources by returning the prior result without activating the lambda instance. You can clearly see how the response time has been reduced when it’s getting cached.

Since our goal is to check lambda warm starts, we can prevent caching by sending requests with a 2 - 3-minute time delay between two API requests. Otherwise, to assure Lambda functions without interference from cache, we can try the following approaches:

Disable API Gateway Caching: Ensure that caching is disabled in API Gateway settings.
Unique Query Parameters: When testing with Postman or similar tools, you can add a unique query parameter to each request. This approach can prevent client-side and intermediate caching. For example, append a timestamp or a random number as a query parameter.
Avoiding Caching in Postman: If you suspect Postman might be caching responses, you can disable caching in Postman settings or use a different tool for testing, like curl in the command line.
Scheduled Invocations:

To invoke Lambda functions automatically without API calls, you can use AWS CloudWatch Events (or EventBridge).
Set up a rule to trigger your Lambda function at regular intervals.
This approach can be useful for simulating traffic and understanding Lambda behavior over time.

When checking X-Ray logs for lambda functions, I should specifically mention that there are two nodes called as function and context.

Lambda Context and Function - X-RAY

Function Node: Actual execution of Lambda function's code, in another words execution time of the function logic itself. This includes the time taken by code and any libraries it uses.
Context (or Initialization) Node: Related to the "initialization" or "bootstrap" phase of the Lambda function. Time spent by AWS Lambda to initialize the execution environment.

A few cold start timings that I obtained by X-ray are included in the table below. Ultimately, although my output folder package size was reduced, neither the lambda execution time nor the cold start time improved. 😑, Since I make quite a number of mistakes, please leave a comment if you find anything wrong with my process. 🫡
CS - Cold Start

Optional: For analyzing AWS X-Ray logs and monitoring the performance impact of applying Webpack to AWS microservices, especially in terms of Lambda cold starts and warm starts, there are several third-party tools and services that might be useful. These tools offer more advanced analytics and visualization capabilities than what's available directly in AWS X-Ray or CloudWatch.

if you're following GitHub Student Developer Pack, you can get free credits for some of these services.

Further improvements.

Later on, I discovered that lambda memory may potentially affect cold starts as well as AWS monthly bill. We can check what is the optimal memory size for each of our lambda using AWS Lambda Power Tuning. And this article well explains, how to test our lambda functions using AWS power tuning tool. Although there isn't much impact from webpack on your current lambda memory size, it might show a significant impact on a different lambda memory size after applying webpack.

Image source

Furthermore, we can follow couple of solutions. I got images from this video for solution 1 and 2.

Solution 01 - Using CloudWatch Event Rule

In here we can ping a lambda for an execution environment for a scheduled time period (i.e.: 10 or 15 min). But lambda might remove this virtual environment within 1 or 1.5 hours of time. Until then requests can use the execute environment stimulated by the scheduled event. In this way we can reduce the count of cold starts.

we can use serverless-plugin-warmup for this purpose.

Solution 02 - Lambda Provisioned Concurrency

For each AWS account, we get 1000 provisioned concurrencies. So, when applying provision concurrency, it will be deducted from our AWS account.

Cost comparison between step 1 and step 2

This basically explains the cost comparison with a lambda function with 100 instances. When lambda pinging, AWS charges the normal charge for lambda service. But in provision concurrency, AWS charges additional cost for explicit warm environment. They're keep charging until we disable the provision concurrency.

Best Practices

Do NOT apply provision concurrency for all the lambdas. Apply only for frequently invoked lambdas.
Use provision concurrency based on a schedule - (Scheduled scaling for Application Auto Scaling)
You can apply Lambda Hing for less frequently used lambda Lambda Ping can further be configured with a CRON expression to minimize cost furthermore. For example, Ping lambda from Monday to Friday from 8AM-5PM. Identify the best memory allocation for your lambda-Use tools like Lambda Power Tuning