Open borders | Željko Šević

⬈ Open borders

https://github.com/zsevic/open-borders-server

NLP classifier for open borders (related to COVID-19 restrictions)

🔍

Supabase basics with Node.js

June 3, 2026

Supabase is an open-source backend platform built around managed PostgreSQL. You get a database, auto-generated REST APIs (via PostgREST), Auth, file Storage, Realtime subscriptions, and Edge Functions - with a dashboard and SQL editor on top.

Compared to running Postgres yourself, Supabase adds hosted infra, API layers, and product features without you wiring them up. Compared to an ORM-only stack, you often talk to Postgres through the Supabase client or SQL, with RLS (row level security) enforcing access at the database layer.

Prerequisites

Supabase account (free tier is enough for learning)
Node.js version 26
@supabase/supabase-js installed (npm i @supabase/supabase-js)

Create a project and database

In the Supabase dashboard, choose New project, pick a region, and set the database password.
Wait until the project is ready.
Open SQL Editor and run the schema below.

The Table Editor is fine for quick experiments; SQL Editor keeps schema reproducible in git and reviews.

create table if not exists public.todos (
  id bigint generated always as identity primary key,
  title text not null,
  done boolean not null default false,
  created_at timestamptz not null default now()
);
create or replace function public.list_open_todos()
returns setof public.todos
language sql
security definer
set search_path = public
as $$
  select * from public.todos where done = false order by id;
$$;
create or replace function public.mark_todo_done(todo_id bigint)
returns setof public.todos
language sql
security definer
set search_path = public
as $$
  update public.todos set done = true where id = todo_id returning *;
$$;
grant execute on function public.list_open_todos() to service_role;
grant execute on function public.mark_todo_done(bigint) to service_role;

This schema skips RLS setup because this post uses the secret key from Node.js, which bypasses RLS. For browser or mobile clients, use the publishable key instead - it obeys Row Level Security when you enable it on tables.

list_open_todos is a Postgres function exposed as an RPC endpoint.

Postgres functions default to security invoker: they run with the caller's permissions, so RLS applies as that role. security definer runs the function as its owner (often a privileged database role), not as the caller.

API keys and connection

On the project Overview tab you will find:

Project URL (https://<ref>.supabase.co) — for SUPABASE_URL
Publishable key (sb_publishable_..., legacy anon) — for browsers and mobile apps where RLS should limit access; this post does not use it

For Node.js backends, use a secret key from Project Settings → API Keys:

Secret key(s) (sb_secret_...) - full data access, bypasses RLS; trusted servers only, never in client bundles or public repos. Replaces the legacy service_role key.
Reveal or create a secret key in the dashboard (legacy projects: Legacy anon, service_role API keys tab → service_role).

The Supabase JS client talks to PostgREST and can query tables (from) and call registered functions (rpc) only after they exist. It does not run DDL (create table, create function, grant, and similar), so apply the schema in the SQL Editor (or via Supabase CLI migrations in larger projects).

Store values in environment variables:

SUPABASE_URL=https://<ref>.supabase.co
SUPABASE_SECRET_KEY=your-secret-key

Client setup

Create a client with the project URL and secret key. Read values from the environment in real apps; never commit the secret key.

import { createClient } from '@supabase/supabase-js';
const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SECRET_KEY
);

Every table you create in the public schema is available as supabase.from('<table>'). Custom SQL functions are called with supabase.rpc('<function_name>').

Insert data

Insert one or more rows and return the created records with .select().

const { data, error } = await supabase
  .from('todos')
  .insert([
    { title: 'Learn Supabase client', done: false },
    { title: 'Run RPC example', done: false },
    { title: 'Ship demo', done: true },
  ])
  .select();
if (error) {
  throw new Error(error.message);
}
console.log(data);

Read, update, and delete

Select with filters and ordering:

const { data, error } = await supabase
  .from('todos')
  .select('*')
  .eq('done', false)
  .order('id');

Update matching rows:

const { data, error } = await supabase
  .from('todos')
  .update({ done: true })
  .eq('id', 1)
  .select();

Delete matching rows:

const { error } = await supabase
  .from('todos')
  .delete()
  .eq('id', 1);

Chain .eq(), .in(), .limit(), and other filter helpers the same way across operations.

RPC

Call a database function by name. Our list_open_todos() returns open todos without repeating filter logic in the app.

const { data, error } = await supabase.rpc('list_open_todos');
if (error) {
  throw new Error(error.message);
}
console.log(data);

Functions with parameters map to a second argument:

await supabase.rpc('mark_todo_done', { todo_id: 42 });

Define parameters in SQL (todo_id bigint) and grant execute to service_role when calling RPC from a secret-key backend.

What else matters

Row Level Security (RLS) - When enabled on a table, Postgres denies access until policies allow it. The publishable key is subject to RLS; the secret key is not. Add policies per role (anon, authenticated) and operation when you turn RLS on.
Auth - Supabase Auth stores users in auth.users. After sign-in, the client JWT includes the authenticated role so policies can use auth.uid() for per-user rows.
Migrations - Avoid changing production only via the dashboard. Track SQL in versioned migration files and apply with the Supabase CLI (supabase db push, linked projects) so environments stay aligned.
Generated types - Run supabase gen types typescript --project-id <ref> to emit TypeScript types from your schema for a type-safe client.
Storage - S3-compatible buckets for files (images, PDFs) with bucket policies analogous to RLS.
Realtime - Subscribe to insert/update/delete on tables or channels for live UI updates.
Edge Functions - Deno functions for webhooks, light API logic, or tasks that should not live in the database.
Local dev - supabase init and supabase start spin up local Postgres and services; useful for offline work, while cloud projects are fastest for a first tutorial.

Demo

Runnable scripts for this post live in the supabase-basics-demo folder in the private demos repository. Get access via code demos.

RAG with OpenAI Embeddings, pgvector and LangChain

June 2, 2026

Retrieval-Augmented Generation (RAG) is a practical pattern: store knowledge as embeddings, retrieve the most relevant chunks with semantic search, then generate an answer grounded in that context.

This guide shows a simple end-to-end flow with OpenAI embeddings, PostgreSQL + pgvector, and LangChain chunking.

Architecture at a glance

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
PostgreSQL with pgvector extension enabled
npm packages: openai, langchain, pg, pgvector

What are embeddings?

Embeddings are numeric vectors that represent the semantic meaning of text. Similar text should produce vectors that are close in vector space.

In practice:

Convert document chunks to vectors and store them in pgvector
Convert a user question to a vector
Run a nearest-neighbor search to find the most relevant chunks

OpenAI client setup

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

Embedding one input element

Use a single string when embedding a user query.

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'How do I connect pgvector to PostgreSQL?',
});
const queryEmbedding = response.data[0].embedding;
console.log(queryEmbedding.length);

Embedding multiple input elements

Use an array to embed multiple chunks in one API call.

const chunks = [
  'pgvector adds vector similarity search to PostgreSQL.',
  'LangChain helps split long documents into retrieval-friendly chunks.',
  'RAG retrieves context first, then asks an LLM to answer.',
];
const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: chunks,
});
const rows = response.data.map((item, index) => ({
  text: chunks[index],
  embedding: item.embedding,
}));
console.log(rows.length); // 3

Chunking documents with LangChain

Chunking makes retrieval more precise. Instead of embedding one large document, split it into smaller overlapping parts. Start with chunkSize: 800 and chunkOverlap: 120, then adjust based on your document style and answer quality.

import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 800,
  chunkOverlap: 120,
});
const docs = await splitter.createDocuments([
  `RAG combines retrieval and generation. Store chunks as vectors and fetch similar chunks at query time.`,
]);
console.log(docs.map((doc) => doc.pageContent));

Store embeddings in pgvector

Create a table with a vector column. text-embedding-3-small outputs 1536 dimensions.

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS rag_chunks (
  id BIGSERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  embedding VECTOR(1536) NOT NULL,
  source TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Insert chunk vectors from Node.js:

import pg from 'pg';
import pgvector from 'pgvector/pg';
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
await pgvector.registerTypes(pool);
await pool.query(
  `INSERT INTO rag_chunks (content, embedding, source)
   VALUES ($1, $2, $3)`,
  ['Chunk content', pgvector.toSql(queryEmbedding), 'notes.md']
);

Semantic search in pgvector

Embed the user question, then retrieve nearest chunks using cosine distance. Lower distance means a closer semantic match. top-k means how many nearest chunks you return (in this query, k=4 with LIMIT 4). You can also use a simple threshold (for example 0.4) to discard weak matches. As a starting point, many setups work well in the 0.35 to 0.45 range for cosine distance, then tune with real questions from your domain.

const searchResult = await pool.query(
  `SELECT id, content, source, embedding <=> $1::vector AS distance
   FROM rag_chunks
   ORDER BY embedding <=> $1::vector
   LIMIT 4`,
  [pgvector.toSql(queryEmbedding)]
);
const contextChunks = searchResult.rows.map((row) => row.content);

Threshold filtering example:

const DISTANCE_THRESHOLD = 0.4;
const filteredChunks = searchResult.rows
  .filter((row) => Number(row.distance) <= DISTANCE_THRESHOLD)
  .map((row) => row.content);

If no chunks pass the threshold, skip answer generation and return a fallback message:

if (filteredChunks.length === 0) {
  console.log('I do not have enough context to answer this.');
  process.exit(0);
}

Generate answer from retrieved context

Use retrieved chunks as grounded context for the final model call.

const context = contextChunks.join('\n\n---\n\n');
const answer = await client.responses.create({
  model: 'gpt-5.5',
  instructions:
    'Answer only from the provided context. If context is insufficient, respond with: I do not have enough context to answer this.',
  input: `Context:\n${context}\n\nQuestion: How does pgvector semantic search work?`,
});
console.log(answer.output_text);

Demo

Runnable scripts for this post live in the rag-openai-embeddings-pgvector-demo folder in the private demos repository. Get access via code demos.

Integration with Hugging Face Inference API

June 1, 2026

Hugging Face hosts thousands of open models for NLP, vision, and other tasks. The Inference API (via Inference Providers) lets you call those models over HTTP. The @huggingface/inference package from huggingface.js is the Node.js client.

Prerequisites

Hugging Face account
Access token with permission to call Inference (create a token of type Read or Fine-grained with inference access)
Node.js version 26
@huggingface/inference installed (npm i @huggingface/inference)

Some models (especially image generation) are routed through Inference Providers. Enable providers and billing in account settings when a model requires it.

Client setup

Pass your token to InferenceClient. Read it from the environment in production.

import { InferenceClient } from '@huggingface/inference';
const client = new InferenceClient(process.env.HF_TOKEN);

Summarization

Shrink longer text into a short summary. Pick a model trained for summarization and respect its max input length.

const result = await client.summarization({
  model: 'facebook/bart-large-cnn',
  inputs: `The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930. It was initially criticized by some artists and intellectuals, but it became a global cultural icon of France and one of the most recognizable structures in the world.`,
  parameters: {
    max_length: 80,
  },
});
console.log(result.summary_text);

Text classification

Assign labels with confidence scores. Common use case: sentiment analysis on short text.

const labels = await client.textClassification({
  model: 'distilbert-base-uncased-finetuned-sst-2-english',
  inputs: 'I really enjoyed this workshop.',
});
for (const { label, score } of labels) {
  console.log(label, score.toFixed(4));
}

Text to image

Generate an image from a text prompt. The client returns a Blob; write it to disk or serve it from your app.

import { writeFileSync } from 'node:fs';
const image = await client.textToImage({
  provider: 'hf-inference',
  model: 'black-forest-labs/FLUX.1-schnell',
  inputs: 'A watercolor painting of a fox in an autumn forest',
  parameters: {
    num_inference_steps: 4,
  },
});
const buffer = Buffer.from(await image.arrayBuffer());
writeFileSync('output.png', buffer);

With provider: 'hf-inference', use a model from the hf-inference catalog for that task (for example black-forest-labs/FLUX.1-schnell). Older Hub repos such as stabilityai/stable-diffusion-2-1 may no longer exist or lack provider mapping.

Image models are often slower and may incur provider usage charges.

Demo

Runnable scripts for each task live in the huggingface-inference-api-demo folder. Get access via code demos.

LLM integration with OpenAI Responses API

May 31, 2026

Large language models (LLMs) understand and generate text from prompts. OpenAI exposes models through the Responses API. The official openai npm package is the practical way to call it from Node.js. This post covers common patterns beyond a single prompt string.

For the Chat Completions API (messages, choices[0].message.content), see the dedicated post.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
openai package installed (npm i openai)
For Markdown output: marked, dompurify, and jsdom (npm i marked dompurify jsdom)

Client setup

Create a client with your API key (read from the environment in production).

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

The same SDK can target other hosts that implement a compatible API by setting baseURL and apiKey:

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
});

Azure OpenAI uses AzureOpenAI instead. Many third-party gateways support Chat Completions only; the examples below use client.responses.*, so confirm your provider supports the Responses API (especially for tools like web search).

Basic integration

Pass a string as input and read output_text from the response.

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: 'Write a one-sentence bedtime story about a unicorn.',
});
console.log(response.output_text);

System prompt

Use top-level instructions for stable behavior (tone, format, role). They take precedence over casual wording in the user message.

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Reply in one short sentence. Use plain language.',
  input: 'Explain what an LLM is.',
});
console.log(response.output_text);

Few-shot prompting

Pass prior turns as an input array with user and assistant roles, then the new user message. Keep task rules in instructions.

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions:
    'Classify sentiment as exactly one word: positive, negative, or neutral.',
  input: [
    { role: 'user', content: 'I love this!' },
    { role: 'assistant', content: 'positive' },
    { role: 'user', content: 'This is awful.' },
    { role: 'assistant', content: 'negative' },
    { role: 'user', content: 'It is fine I guess.' },
  ],
});
console.log(response.output_text);

Streaming

Set stream: true and handle response.output_text.delta events for incremental text.

const stream = await client.responses.create({
  model: 'gpt-5.5',
  input: 'List three colors.',
  stream: true,
});
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Structured output with JSON schema

Constrain the model to JSON matching your schema via text.format. With strict: true, the output should match the schema.

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: 'The film Inception was directed by Christopher Nolan.',
  text: {
    format: {
      type: 'json_schema',
      name: 'movie_summary',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          director: { type: 'string' },
        },
        required: ['title', 'director'],
        additionalProperties: false,
      },
    },
  },
});
const data = JSON.parse(response.output_text);
console.log(data.title, data.director);

For typed parsing with Zod, you can use client.responses.parse() instead of JSON.parse.

Markdown output to HTML

Ask for Markdown in instructions, then convert output_text to HTML and sanitize before rendering (for example with innerHTML in the browser or when storing HTML).

import { marked } from 'marked';
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';
const purify = DOMPurify(new JSDOM('').window);
const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Reply in Markdown only. Use a heading and a short bullet list.',
  input: 'Explain what an LLM is in three bullet points.',
});
const markdown = response.output_text;
const html = marked.parse(markdown);
const safeHtml = purify.sanitize(html);

Always run DOMPurify.sanitize on model-generated HTML. The model can emit unsafe markup; sanitization strips scripts and other dangerous content.

Web search tool

Enable the built-in web search tool when the answer should use current information from the web.

const response = await client.responses.create({
  model: 'gpt-5.5',
  tools: [{ type: 'web_search' }],
  include: ['web_search_call.action.sources'],
  input: 'What was a major tech headline this week? Cite sources briefly.',
});
console.log(response.output_text);

Web search adds latency and tool usage cost. Use a model that supports tools.

Demo

Runnable scripts for each section live in the openai-responses-api-demo folder. Get access via code demos.

Browser automation with Playwright

May 17, 2026

Playwright is a headless browser library for automating browser tasks. Here's the list of some of the features (Playwright equivalents to the Puppeteer post):

Turn off headless mode

import { chromium } from 'playwright';
const browser = await chromium.launch({
  headless: false
  // ...
});

Resize the viewport to the window size

const context = await browser.newContext({
  viewport: null
});
const page = await context.newPage();

Emulate screen how it's shown to the user via the emulateMedia method

await page.emulateMedia({ media: 'screen' });

Save the page as a PDF file with a specified path, format, scale factor, and page range

await page.pdf({
  path: 'path.pdf',
  format: 'A3',
  scale: 1,
  pageRanges: '1-2',
  printBackground: true
});

Use preexisting user's credentials to skip logging in to some websites. The user data directory is a parent of the Profile Path value from the chrome://version page. Use launchPersistentContext instead of launch + newContext.

import { chromium } from 'playwright';
const context = await chromium.launchPersistentContext(
  'C:\\Users\\<USERNAME>\\AppData\\Local\\Google\\Chrome\\User Data',
  { headless: false }
);
const page = context.pages()[0] ?? (await context.newPage());

Use Chrome instance instead of Chromium via the channel option. Close Chrome before running the script if the profile is in use.

import { chromium } from 'playwright';
const browser = await chromium.launch({
  channel: 'chrome'
  // ...
});

Switch to the selected tab

await page.bringToFront();

Get value based on evaluation in the browser page

const shouldPaginate = await page.evaluate(
  ([param1, param2]) => {
    // ...
  },
  [param1, param2]
);

Get HTML content from the specific element

const html = await page.locator('.field--text').evaluate(
  (element) => element.outerHTML
);

Wait for a specific selector to be loaded. You can also provide a timeout in milliseconds

await page.waitForSelector('.success', { timeout: 5000 });

Manipulate with a specific element and click on some of the elements

await page.locator('#header').evaluate(async (headerElement) => {
  // ...
  headerElement
    .querySelectorAll('svg')
    .item(13)
    .parentNode.click();
});

Extend execution timeout for slow evaluate callbacks

page.setDefaultTimeout(0);
// or per action:
await page.locator('#header').evaluate(async (headerElement) => {
  // ...
}, { timeout: 0 });

Manipulate with multiple elements

await page.locator('.some-class').evaluateAll(async (elements) => {
  // ...
});

Wait for navigation (e.g., form submitting) to be done

await page.waitForLoadState('networkidle', { timeout: 0 });

Or wait for navigation triggered by a click:

await Promise.all([
  page.waitForNavigation({ waitUntil: 'networkidle', timeout: 0 }),
  page.click('button[type="submit"]')
]);

Trigger hover event on some of the elements

await page.locator('#header').hover();

Or dispatch a custom event in the page:

await page.locator('#header').evaluate((headerElement) => {
  const hoverEvent = new MouseEvent('mouseover', {
    view: window,
    bubbles: true,
    cancelable: true
  });
  headerElement.dispatchEvent(hoverEvent);
});

Expose a function in the browser and use it in evaluate / evaluateAll callbacks (e.g., simulate typing using the window.type function)

await page.exposeFunction('type', async (selector, text, options) => {
  await page.locator(selector).type(text, options);
});
await page.locator('.some-class').evaluateAll(async (elements) => {
  // ...
  await window.type(selector, text, { delay: 0 });
});

Press the Enter button after typing the input field value

await page.locator(selector).fill(text);
await page.locator(selector).press('Enter');

Open a file chooser and select file for upload

const fileChooserPromise = page.waitForEvent('filechooser');
await page.locator(selector).click();
const fileChooser = await fileChooserPromise;
const filePath = `C:/Users/<USERNAME>/Downloads/test.jpeg`; // use "/" instead of "\" in file path
await fileChooser.setFiles(filePath);

Remove the value from the input field before typing the new one

await page.locator(selector).fill(text);

Or select all and replace:

await page.locator(selector).click({ clickCount: 3 });
await page.locator(selector).type(text, options);

Pass a variable into evaluate / evaluateAll callbacks via extra arguments

await page.locator('#element').evaluate(
  async (element, customVariable) => {
    // ...
  },
  customVariable
);

Mock response for the specific request

await page.route(REDIRECTION_URL, async (route) => {
  await route.fulfill({
    contentType: 'text/html',
    status: 304,
    body: '<body></body>'
  });
});

Intercept page redirections (via route) and open them in new tabs rather than following them in the same tab

await page.route(REDIRECTION_URL, async (route) => {
  const url = route.request().url();
  await route.fulfill({
    contentType: 'text/html',
    status: 304,
    body: '<body></body>'
  });
  const newPage = await context.newPage();
  await newPage.goto(url, { waitUntil: 'domcontentloaded', timeout: 0 });
  // ...
  await newPage.close();
});

Intercept page response

page.on('response', async (response) => {
  if (response.url() === RESPONSE_URL) {
    if (response.status() === 200) {
      // ...
    }
    // ...
  }
});

Deploying Node.js apps to Railway

May 16, 2026

Railway is probably one of the fastest ways to get a Node.js API live. GitHub Integration Connect your GitHub repository to Railway…

Infrastructure as Code (IaC) with Terraform (AWS EC2 Example)

April 28, 2026

Infrastructure as Code (IaC) is a DevOps approach where infrastructure is defined and managed using code instead of manual setup. This makes environments reproducible, version-controlled, and easy to scale.

In this guide, you'll provision an AWS EC2 instance using Terraform.

Requirements

Before starting, install:

Terraform
AWS CLI

AWS Credentials Setup

Go to IAM → Security credentials in AWS
Create access keys
Configure locally:

aws configure

This stores credentials in:

~/.aws/credentials
~/.aws/config

Project Structure

A simple Terraform setup:

.
├── main.tf
├── variables.tf
├── terraform.tfvars
├── outputs.tf

Provider Configuration

Define your cloud provider in main.tf:

provider "aws" {
  profile = "default"
  region  = "eu-north-1"
}

Variables

Define reusable variables in variables.tf:

variable "instance_name" {
  description = "Name tag for EC2 instance"
  type        = string
  default     = "MyNewInstance"
}
variable "ec2_instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.micro"
}

Set values in terraform.tfvars:

instance_name      = "MyEC2Name"
ec2_instance_type  = "t3.micro"

EC2 Instance Configuration

Add the resource in main.tf:

resource "aws_instance" "app_server" {
  ami           = "ami-077d1b9f9a1902bbc"
  instance_type = var.ec2_instance_type
  tags = {
    Name = var.instance_name
  }
}

You can find AMI IDs in EC2 → Images → AMI Catalog.

Outputs

Expose useful data in outputs.tf:

output "instance_id" {
  description = "EC2 instance ID"
  value       = aws_instance.app_server.id
}
output "instance_public_ip" {
  description = "Public IP address"
  value       = aws_instance.app_server.public_ip
}

Terraform Workflow

Initialize the project:

terraform init

Preview changes:

terraform plan

Apply changes:

terraform apply

Destroy infrastructure:

terraform destroy

Important Notes

State file

Terraform stores infrastructure state in terraform.tfstate.

Do not commit this file to Git.

Remote state (recommended)

For teams, store state in S3 with locking.

Idempotency

Running apply multiple times won’t recreate resources unnecessarily.

Version control

Treat Terraform code like application code.

Load and stress testing with Artillery

April 25, 2026

Artillery is a performance testing tool. This post explains types of performance testing and dives into Artillery usage, from configuration to running tests and checking results.

Load and stress testing

Load and stress testing are two types of performance testing used to evaluate how well a system performs under various conditions.

Load testing determines how the system performs under expected user loads. The purpose is to identify performance bottlenecks.

Stress testing assesses how the system performs when loads are heavier than usual. The purpose is to find the limit at which the system fails and to observe how it recovers from such failures.

Prerequisites

Artillery available via npx (or installed in project dev dependencies)
YAML config file that defines target, phases and scenarios
Optional CSV payload file for dynamic test data

Configuration

Artillery test configuration is defined in a YAML file (for example, .artillery/main.yml). It typically contains:

target: base URL of the app (http://localhost:3000)
phases: load shape over time
payload: CSV file for dynamic values
scenarios: user flows and weights

For realistic load tests, configure these parts intentionally:

Define phases for warm-up, ramp-up, and sustained load.
Use a CSV payload when requests require dynamic values (IDs, emails, tokens, and similar).
Use weighted scenarios to simulate realistic traffic distribution across endpoints.

config:
  target: 'http://localhost:3000'
  phases:
    - duration: 30
      arrivalRate: 5
      name: Warm up
    - duration: 30
      arrivalRate: 5
      rampTo: 50
      name: Ramp up load
    - duration: 30
      arrivalRate: 50
      name: Sustained load
  payload:
    path: 'dynamic_data.csv'
    fields:
      - 'CustomerId'
scenarios:
  - name: "Get customer's tracks"
    flow:
      - get:
          url: '/customers/{{ CustomerId }}/tracks'
    weight: 4
  - name: 'Get customers pdf'
    flow:
      - get:
          url: '/customers/pdf'
    weight: 1

Scenario flow and dynamic data

Scenarios define user actions during the test.

In the example:

80% of users run Get customer's tracks (weight: 4)
20% of users run Get customers pdf (weight: 1)

Dynamic data is loaded from .artillery/dynamic_data.csv, and {{ CustomerId }} is injected into request URLs.

Running tests

Load tests can be executed through an npm script:

"scripts": {
  "test:load": "artillery run ./.artillery/main.yml"
}

Run the test with:

npm run test:load

You can also run Artillery directly with npx:

npx artillery run ./.artillery/main.yml

Test report

By default, Artillery prints a terminal summary with key metrics such as:

failed virtual users and HTTP error/status-code distribution
response-time percentiles (especially p95 and p99)
median response time (p50)
requests per second and total request volume

To save raw results and generate an HTML report:

npx artillery run --output report.json ./.artillery/main.yml
npx artillery report report.json --output report.html

This generates a shareable HTML report with latency percentiles, throughput and error trends.

When reading Artillery reports, focus on these metrics first:

Error rate (vusers.failed, non-2xx/3xx codes): the most important health signal. Even small error percentages can indicate instability under load.
Tail latency (p95, p99): shows worst-case user experience. Systems can have a good median but still feel slow for a significant group of users.
Median latency (p50/median): useful for baseline responsiveness, but should always be evaluated together with p95/p99.
Throughput (http.requests, requests/sec): confirms how much traffic the system handled during the test.
Trend over time (intermediate snapshots): helps identify whether performance degrades during ramp-up or sustained load.

In short: start with reliability (errors), then check latency percentiles (especially p95/p99), and finally validate throughput and time-based stability.

2024

HTTP timeout with Axios

September 26, 2024

Setting up a timeout for HTTP requests can prevent the connection from hanging forever, waiting for the response. It can be set on the client side to improve user experience, and on the server side to improve inter-service communication.

axios package provides a timeout parameter for this functionality.

const HTTP_TIMEOUT = 3000;
const URL = 'https://www.google.com:81';
(async () => {
  try {
    await axios(URL, {
      timeout: HTTP_TIMEOUT
    });
  } catch (error) {
    console.error('Request timed out', error.cause);
  }
})();

Use this snippet also to simulate aborted requests.

RabbitMQ container with Docker Compose

September 3, 2024

Docker Compose facilitates spinning up a container for the RabbitMQ broker without installing it locally.

Prerequisites

Docker Compose installed

Configuration

The following configuration spins up the RabbitMQ container with the management UI tool.

The connection string for the RabbitMQ broker with local virtual host is amqp://localhost:5672/local.

RabbitMQ management UI is available at the http://localhost:15672 link. Default credentials are guest as username and guest as password.

# docker-compose.yml
version: '3.8'
services:
  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - 5672:5672
      - 15672:15672
    environment:
      - RABBITMQ_DEFAULT_VHOST=local
    volumes:
      - 'rabbitmq_data:/data'
volumes:
  rabbitmq_data:

Run the following command to spin up the container.

docker-compose up

Simulating keyboard typing with JavaScript

August 21, 2024

Simulating keyboard typing in JavaScript can be useful for automating tasks or testing applications. The KeyboardEvent API allows developers to trigger keyboard events programmatically.

Examples

The snippet below simulates pressing the Ctrl + Enter command. The bubbles flag ensures the event moves up through the DOM, so any elements higher up in the document can also detect and respond to it.

const event = new KeyboardEvent('keydown', {
  key: 'Enter',
  ctrlKey: true,
  bubbles: true
});
document.dispatchEvent(event);

The snippet below simulates pressing the Shift + Enter command on a specific input field.

const event = new KeyboardEvent('keydown', {
  key: 'Enter',
  shiftKey: true,
  bubbles: true
});
document.querySelector('input').dispatchEvent(event);

Profiling Node.js apps with Chrome DevTools profiler

July 5, 2024

Profiling refers to analyzing and measuring an application's performance characteristics.

Profiling helps identify performance bottlenecks in a Node.js app, such as CPU-intensive tasks like cryptographic operations, image processing, or complex calculations.

This post covers running a profiler for various Node.js apps in Chrome DevTools.

Prerequisites

Google Chrome installed
Node.js app bootstrapped

Setup

Run node --inspect app.js to start the debugger.
Open chrome://inspect, click Open dedicated DevTools for Node and then navigate to the Performance tab. Start recording.
Run load testing via autocannon package using the following command format npx autocannon <COMMAND>.
Stop recording in Chrome DevTools.

Profiling

On Perfomance tab in Chrome DevTools open Bottom-Up subtab to identify which functions consume the most time.

Look for potential performance bottlenecks, such as synchronous functions for hashing (pbkdf2Sync) or file system operations (readFileSync).

Load and stress testing with k6

May 10, 2024

k6 is a performance testing tool. This post explains types of performance testing and dives into k6 usage, from configuration to running tests.

Load and stress testing

Load and stress testing are two types of performance testing used to evaluate how well a system performs under various conditions.

Load testing determines how the system performs under expected user loads. The purpose is to identify performance bottlenecks.

Stress testing assesses how the system performs when loads are heavier than usual. The purpose is to find the limit at which the system fails and to observe how it recovers from such failures.

Prerequisites

k6 installed
Script (Node.js) file with configuration and execution function

Configuration

Configuration is stored inside options variable, which allows you to set up different testing scenarios:

constant user load, the number of virtual users (vus) remains constant throughout the test period

export const options = {
  vus: 30,
  duration: '10m'
};

variable user load, the number of users increases and decreases over time

export const options = {
  stages: [
    {
      duration: '1m',
      target: 30
    },
    {
      duration: '10m',
      target: 30
    },
    {
      duration: '5m',
      target: 0
    }
  ]
};

Environment variables can be passed through the command line and are accessible within the script via the __ENV object.

k6 -e TOKEN=token run script.js

Execution function

This function defines what virtual users will do during the test. This function is called for each virtual user and typically includes steps that simulate user actions on the app.

export default function() {
  http.get(URL);
  // Add more actions as required
}

Test report

k6 generates a report that provides detailed insights into various benchmarks, such as the number of virtual users, requests per second, request durations and error rates.

Example

This example utilizes k6 to conduct a load test using a variable user load approach:

User simulation: The script ramps up to 1,000 users, maintains that level to simulate sustained traffic, and gradually reduces to zero.
Request handling: During the test, each virtual user sends a POST request to an API, with pauses between requests to mimic real user behavior.
Performance insights: After the test, k6 provides a report that shows key information, such as how fast the app responds and how many requests fail.

Run it via k6 -e TOKEN=1234 run script.js command.

// script.js
import { check, sleep } from 'k6';
import { scenario } from 'k6/execution';
import http from 'k6/http';
export const options = {
  stages: [
    // Ramp up to 1000 users over 10 minutes
    {
      duration: '10m',
      target: 1000
    },
    // Hold 1000 users for 30 minutes
    {
      duration: '30m',
      target: 1000
    },
    // Ramp down to 0 users over 5 minutes
    {
      duration: '5m',
      target: 0
    }
  ]
};
export default () => {
  const response = http.post(
    URL,
    JSON.stringify({
      iteration: scenario.iterationInTest
    }),
    {
      headers: {
        Authorization: __ENV.TOKEN,
        'Content-Type': 'application/json'
      }
    }
  );
  check(response, {
    'response status was 200': (res) => res.status === 200
  });
  sleep(1);
};

Node Version Manager (nvm) overview

May 9, 2024

nvm facilitates switching between different Node versions across projects. This post covers its overview from installation to version management.

Installation

To install nvm, execute the following commands in your terminal. This example uses zsh, but the process is similar for other shells like bash.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc

Version management

Install the specific version. Including the v prefix is optional.
```
nvm install v21.7.2
```
Install the latest version
```
nvm install node
```
Install the latest one for the specified major version
```
nvm install 22
```
Switch to a specific installed version
```
nvm use 21
```
Add .nvmrc file inside the project directory and run nvm use command to use the specified installed version.
```
v21.7.2
```
Get the list of locally installed versions
```
nvm ls
```
Get the list of available versions for installation
```
nvm ls-remote
```

Debugging Node.js apps with Chrome DevTools debugger

April 12, 2024

Debugging with a debugger and breakpoints is recommended rather than using console logs. Chrome provides a built-in debugger for JavaScript-based apps.

This post covers configuring and running a debugger for various Node.js apps in Chrome DevTools.

Prerequisites

Google Chrome installed
Node.js app bootstrapped

Setup

Open chrome://inspect, click Open dedicated DevTools for Node and open the Connection tab. You should see a list of network endpoints for debugging.

Run node --inspect-brk app.js to start the debugger, it will log the debugger network. Choose the network in Chrome to open the debugger in Chrome DevTools.

Debugging basics

The variables tab shows local and global variables during debugging.

The step over next function call option goes to the following statement in the codebase, while the step into next function call option goes deeper into the current statement.

Add logs in the debug console via logpoints by selecting the specific part of the codebase so it logs when the selected codebase executes.

Sending e-mails with Sendgrid

March 30, 2024

To send e-mails in a production environment, use services like Sendgrid.

Verify the e-mail address on the Sender Management page and create the SendGrid API key on the API keys page.

import nodemailer from 'nodemailer';
(async () => {
  const emailConfiguration = {
    auth: {
      user: process.env.EMAIL_USERNAME, // 'apikey'
      pass: process.env.EMAIL_PASSWORD
    },
    host: process.env.EMAIL_HOST, // 'smtp.sendgrid.net'
    port: process.env.EMAIL_PORT, // 465
    secure: process.env.EMAIL_SECURE // true
  };
  const transport = nodemailer.createTransport(emailConfiguration);
  const info = await transport.sendMail({
    from: '"Sender" <sender@example.com>',
    to: 'recipient1@example.com, recipient2@example.com',
    subject: 'Subject',
    text: 'Text',
    html: '<b>Text</b>'
  });
  console.log('Message sent: %s', info.messageId);
})();

MongoDB containers with Docker Compose

February 2, 2024

Docker Compose facilitates spinning up a container for the MongoDB database without installing MongoDB locally.

Prerequisites

Docker Compose installed

Configuration

The following configuration spins up the MongoDB container with the UI tool (Mongo Express).

The connection string for the MongoDB database is mongodb://localhost:27018.

Mongo Express is available at the http://localhost:8082 link. Use the below Basic auth credentials to log in to Mongo Express.

# docker-compose.yml
version: '3.8'
services:
  mongo:
    image: 'mongo:7.0.5'
    ports:
      - 27018:27017
    volumes:
      - my-data:/var/lib/mongodb/data
  mongo-express:
    image: 'mongo-express:1.0.2'
    ports:
      - 8082:8081
    environment:
      ME_CONFIG_BASICAUTH_USERNAME: username
      ME_CONFIG_BASICAUTH_PASSWORD: password
volumes:
  my-data:

Run the following command to spin up the containers.

docker-compose up

Web scraping with cheerio

January 19, 2024

Web scraping means extracting data from websites. This post covers extracting data from the page's HTML tags.

Prerequisites

cheerio package is installed
HTML page is retrieved via an HTTP client

Usage

create a scraper object with load method by passing HTML content as an argument

set decodeEntities option to false to preserve encoded characters (like &) in their original form

const $ = load('<div><!-- HTML content --></div>', { decodeEntities: false });

find DOM elements by using CSS-like selectors

const items = $('.item');

iterate through found elements using each method

items.each((index, element) => {
  // ...
});

access element content using specific methods
- text - $(element).text()
- HTML - $(element).html()
- attributes
  - all - $(element).attr()
  - specific one - $(element).attr('href')
- child elements
  - first - $(element).first()
  - last - $(element).last()
  - all - $(element).children()
  - specific one - $(element).find('a')
- siblings
  - previous - $(element).prev()
  - next - $(element).next()

Disclaimer

Please check the website's terms of service before scraping it. Some websites may have terms of service that prohibit such activity.

2023

Integration with GitHub GraphQL API

December 22, 2023

GitHub provides GraphQL API to create integrations, retrieve data, and automate workflows.

Prerequisites

GitHub token (Settings → Developer Settings → Personal access tokens)

Integration

Below is an example of retrieving sponsorable users by location.

export async function getUsersBy(location) {
  return fetch('https://api.github.com/graphql', {
    method: 'POST',
    body: JSON.stringify({
      query: `query {
        search(type: USER, query: "location:${location} is:sponsorable", first: 100) {
          edges {
            node {
              ... on User {
                bio
                login
                viewerCanSponsor
              }
            }
          }
          userCount
        }
      }`
    }),
    headers: {
      ContentType: 'application/json',
      Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
    }
  })
    .then((response) => response.json())
    .then((response) => response.data?.search?.edges || []);
}

Web scraping with jsdom

December 14, 2023

Web scraping means extracting data from websites. This post covers extracting data from the page's HTML when data is stored in JavaScript variable or stringified JSON.

The scraping prerequisite is retrieving an HTML page via an HTTP client.

Examples

The example below moves data into a global variable, executes the page scripts and accesses the data from the global variable.

import jsdom from 'jsdom';
fetch(URL)
  .then((res) => res.text())
  .then((response) => {
    const dataVariable = 'someVariable.someField';
    const html = response.replace(dataVariable, `var data=${dataVariable}`);
    const dom = new jsdom.JSDOM(html, {
      runScripts: 'dangerously',
      virtualConsole: new jsdom.VirtualConsole()
    });
    console.log('data', dom?.window?.data);
  });

The example below runs the page scripts, and access stringified JSON data.

import jsdom from 'jsdom';
fetch(URL)
  .then((res) => res.text())
  .then((response) => {
    const dom = new jsdom.JSDOM(response, {
      runScripts: 'dangerously',
      virtualConsole: new jsdom.VirtualConsole()
    });
    const data = dom?.window?.document?.getElementById('someId')?.value;
    console.log('data', JSON.parse(data));
  });

Disclaimer

Please check the website's terms of service before scraping it. Some websites may have terms of service that prohibit such activity.

License key verification with Gumroad API

November 16, 2023

Gumroad allows verifying license keys via API calls to limit the usage of the keys. It can be helpful to prevent the redistribution of products like desktop apps.

Allow generating a unique license key per sale in product settings, and the product ID will be shown there. Below is the code snippet for verification.

try {
  const requestBody = new URLSearchParams();
  requestBody.append('product_id', process.env.PRODUCT_ID);
  requestBody.append('license_key', process.env.LICENSE_KEY);
  requestBody.append('increment_uses_count', true);
  const response = await fetch('https://api.gumroad.com/v2/licenses/verify', {
    method: 'POST',
    body: requestBody
  });
  const data = await response.json();
  if (data.purchase?.test) {
    console.log('Skipping verification for test purchase');
    return;
  }
  const verificationLimit = Number(process.env.VERIFICATION_LIMIT);
  if (data.uses >= verificationLimit + 1) {
    throw new Error('Verification limit exceeded');
  }
  if (!data.success) {
    throw new Error(data.message);
  }
} catch (error) {
  if (error?.response?.status === 404) {
    console.log("License key doesn't exist");
    return;
  }
  console.log('Verifying license key failed', error);
}

Creating a custom GPT version of ChatGPT

November 11, 2023

Creating a custom GPT agent is available to ChatGPT plus users. This post covers the main steps from creation to publishing.

Creation

Open the Explore GPTs tab and choose the Create option.

Write a description of what agent you would like to create.

GPT builder will also propose a GPT name and generate a profile picture.

Refine the GPT context with the builder. Choose interaction style and personalization for the agent.

Knowledge base

Upload files with knowledge data in the Configure tab.

Use files in formats like JSON, PDF, and CSV.

Using external API

Create a new action in the Configure tab by entering OpenAPI docs in the Schema field.

Enter schema in JSON or YAML format or import it from the URL, and ensure it contains the server's URL configured.

Set Authentication for the provided API and test the created action via the Test button.

Security

Add a rule not to expose internal instructions so other users can't copy your configuration.

Add a rule not to expose internal instructions if a user asks for it, and answer with "Sorry, it's not possible."

Publishing

To make your GPT publicly available in the GPT Store, you need to verify the website domain.

Open Settings & Beta → Builder profile and verify the new domain for the website. You'll get TXT value, which you need to configure on your domain service like Namecheap, using @ as the host value.

Once you verified the website, click the Save → Public → Confirm buttons to publish your new GPT.

Examples

PDF generation with Gotenberg

November 4, 2023

Gotenberg is a Docker-based stateless API for PDF generation from HTML and Markdown files.

To get started, configure Docker compose and run the docker-compose up command.

version: '3.8'
services:
  gotenberg:
    image: gotenberg/gotenberg:7
    ports:
      - 3000:3000

API is available on http://localhost:3000 address.

Run the following commands to generate PDFs

from the given URL

curl \
  --request POST 'http://localhost:3000/forms/chromium/convert/url' \
  --form 'url="https://sparksuite.github.io/simple-html-invoice-template/"' \
  --form 'pdfFormat="PDF/A-1a"' \
  -o curl-url-response.pdf

from the given HTML file

curl \
  --request POST 'http://localhost:3000/forms/chromium/convert/html' \
  --form 'files=@"./index.html"' \
  --form 'pdfFormat="PDF/A-1a"' \
  -o curl-html-response.pdf

PDF/A-1a format is used for the long-term preservation of electronic documents, ensuring that documents can be accessed and read even as technology changes.

Identifying missing variables in Handlebars templates

November 3, 2023

Handlebars is a template engine that can create server-side views, e-mail templates, and invoice templates by injecting JSON data into HTML.

Resolving all variables in a Handlebars template is essential to maintain the accuracy of the displayed information and to prevent incomplete content or layout problems.

The following snippet checks for missing variables by overriding the default nameLookup function. It logs a warning for unresolved variables and sets the default value, empty string, in this case.

// ...
const originalNameLookup = Handlebars.JavaScriptCompiler.prototype.nameLookup;
Handlebars.JavaScriptCompiler.prototype.nameLookup = function(
  parent,
  name,
  type
) {
  if (type === 'context') {
    const messageLog = JSON.stringify({
      message: `Variable is not resolved in the template: ${name}`,
      level: WARNING_LEVEL
      // ...
    });
    return `${parent} && ${parent}.${name} ? ${parent}.${name} : (console.log(${messageLog}), ''`;
  }
  return originalNameLookup.call(this, parent, name, type);
};
// ...
const result = Handlebars.compile(template)(data);

Extending outdated TypeScript package declarations

November 2, 2023

Extending package declarations locally is one of the options for outdated package typings.

Create a declaration file .d.ts (e.g., handlebars.d.ts), and put it inside the src directories.

Find the exact name of the package namespace inside the node_modules types file (e.g. handlebars/types/index.d.ts).

Extend the found namespace with your needed properties, like classes, functions, etc.

// handlebars.d.ts
declare namespace Handlebars {
  export class JavaScriptCompiler {
    public nameLookup(
      parent: string,
      name: string,
      type: string
    ): string | string[];
  }
  export function doSomething(name: string): void;
  // ...
}

Bun overview

September 11, 2023

Bun is a JavaScript runtime environment that extends JavaScriptCore engine built for Safari. Bun is designed for speed and developer experience (DX), which includes many features out of the box.

Some of the features include

Built-in bundler
Built-in test runner
Node.js-compatible package manager, compatible with existing npm packages
Compatibility with Node.js native modules like fs, path, etc.
TypeScript support, run TypeScript files with no extra configuration
Built-in watch mode
Support for both ES modules and CommonJS modules, both can be used in the same file
Native SQLite driver

Installation

Let's start by installing it with the following command

curl -fsSL https://bun.sh/install | bash

Update the current version with bun upgrade command and check the current version with bun --version command.

Run bun --help to see what CLI options are available.

Initialize empty project via the bun init command

The init command will bootstrap the "hello world" example with configured package.json, binary lock file (bun.lockb), and tsconfig.

Bundler

Bundler can be used via CLI command (bun build) or Bun.build() API

await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './build'
});

Below is the example for CLI command usage. Run bun build --help to see all of the available options

bun build --target=bun ./index.ts --outdir=./build

Build a single executable using the compile flag.

bun build ./index.js --compile

Package manager

Install packages from package.json via the bun install command.

Install additional npm packages via the bun add command (e.g., bun add zod). To install dev dependencies, run bun add with --dev option (e.g., bun add zod --dev)

Remove dependencies via the bun remove command (e.g., bun remove zod)

Running scripts

Run specific script via the bun <SCRIPT PATH>.ts command
Auto-install and run packages locally via the bunx command (e.g., bunx cowsay "Hello world")
Run a custom npm script from package.json via the bun run <SCRIPT NAME> command

Watch mode

hot reloading mode via bun --hot index.ts command without restarting the process
watch mode via bun --watch index.ts command with restarting the process

File system

Write into the file using Bun.write method

await Bun.write('./output.txt', 'Lorem ipsum');

Environment variables

Access environment variables via Bun.env or process.env objects
Store variables in .env files, like .env, .env.production, .env.local
Print all current environment variables via bun run env command

HTTP server

Create a server with the following code

const server = Bun.serve({
  port: Bun.env.PORT,
  fetch(request) {
    return new Response('Welcome to Bun!');
  }
});
console.log(`Listening to port ${server.port}`);

Frameworks

Elysia (Bun framework)

Install packages via the bun add elysia @elysiajs/swagger command, write the initial server, and run it via the bun server.ts command.

// server.ts
import { Elysia } from 'elysia';
import swagger from '@elysiajs/swagger';
const port = Bun.env.PORT || 8081;
new Elysia()
  .use(
    swagger({
      path: '/api-docs'
    })
  )
  .get('/posts/:id', ({ params: { id } }) => id)
  .listen(port);

Express

Install the express package via the bun add express command, write the initial server, and run it via the bun server.ts command

// server.ts
import express from 'express';
const app = express();
const port = Bun.env.PORT || 3001;
app.get('/', (req, res) => {
  res.send('Hello world');
});
app.listen(port, () => {
  console.log(`Listening on port ${port}`);
});

Debugging

Install the extension Bun for Visual Studio Code by Oven and Run the Bun: Debug file command from the command palette. Execution will pause at the breakpoint.

Testing

Bun supports basic mocking and assertion functions. Run existing tests via the bun run <TEST SCRIPT NAME> (e.g., bun run test:unit) command.

Below is an example of a basic test assertion and mocking using bun:test module.

import { describe, expect, it, mock } from 'bun:test';
import { add } from './addition-service';
import { calculate } from './calculation-service';
describe('Calculation service', () => {
  it('should return calculated value', async () => {
    const result = calculate();
    expect(result).toEqual(5);
  });
  it('should return mocked value', async () => {
    mock.module('./addition-service', () => {
      return {
        add: () => 3
      };
    });
    const result = add();
    expect(result).toEqual(3);
  });
});

Run unit tests via the bun test command. Re-run tests when files change via the bun test --watch command.

SQLite database

Below is a basic example of SQLite driver usage.

import { Database } from 'bun:sqlite';
const database = new Database('database.sqlite');
const query = database.query("SELECT 'hello world' as message;");
console.log(query.get());
database.close();

Integration with Notion API

September 9, 2023

Notion is a versatile workspace tool combining note-taking, task management, databases, and collaboration features into a single platform.

It also supports integration with Notion content, facilitating tasks such as creating pages, retrieving a block, and filtering database entries via API.

Prerequisites

Notion account
Generated Integration token (Settings & Members → Connections → Develop or manage integrations → New integration)
Notion database ID (open database as full page, extract database ID from the URL (https://notion.so/<USERNAME>/<DATABASE_ID>?v=v))
Added Notion connection (three dots (...) menu → Add Connections → choose created integration)
@notionhq/client package installed

Integration

Below is an example of interacting with Notion API to create the page (within the chosen database) with icon, cover, properties, and child blocks.

const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_INTEGRATION_TOKEN });
const response = await notion.pages.create({
  parent: {
    type: 'database_id',
    database_id: process.env.NOTION_DATABASE_ID
  },
  icon: {
    type: 'emoji',
    emoji: '🆗'
  },
  cover: {
    type: 'external',
    external: {
      url: 'https://cover.com'
    }
  },
  properties: {
    Name: {
      title: [
        {
          type: 'text',
          text: {
            content: 'Some name'
          }
        }
      ]
    },
    Score: {
      number: 42
    },
    Tags: {
      multi_select: [
        {
          name: 'A'
        },
        {
          name: 'B'
        }
      ]
    },
    Generation: {
      select: {
        name: 'I'
      }
    }
    // other properties
  },
  children: [
    {
      object: 'block',
      type: 'bookmark',
      bookmark: {
        url: 'https://bookmark.com'
      }
    }
  ]
});

Upgrading React Native app to Android 13+

August 28, 2023

There is a requirement to upgrade Android apps (hosted on Google Play Store) to target Android 13. This post covers steps to upgrade to the React Native 0.72+ version.

Automatic approach

Use the npx react-native upgrade command to make code updates to the latest version.

Manual approach

Use Upgrade helper to manually change the code. It shows the differences between boilerplates for the selected versions (e.g., 0.71.13 and 0.72.4).

Fill out the package name (e.g., com.someapp). App name can stay empty, ignore it (rndiffapp) in the code changes.

Advertising ID

Enable it on the Google Play Console app page by selecting Policy and programs → App content option. Add it as a permission in the AndroidManifest.xml file.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Browser automation with Puppeteer

August 26, 2023

Puppeteer is a headless browser for automating browser tasks. Here's the list of some of the features:

Turn off headless mode

const browser = await puppeteer.launch({
  headless: false
  // ...
});

Resize the viewport to the window size

const browser = await puppeteer.launch({
  // ...
  defaultViewport: null
});

Emulate screen how it's shown to the user via the emulateMediaType method

await page.emulateMediaType('screen');

Save the page as a PDF file with a specified path, format, scale factor, and page range

await page.pdf({
  path: 'path.pdf',
  format: 'A3',
  scale: 1,
  pageRanges: '1-2',
  printBackground: true
});

Use preexisting user's credentials to skip logging in to some websites. The user data directory is a parent of the Profile Path value from the chrome://version page.

const browser = await puppeteer.launch({
  userDataDir:
    'C:\\Users\\<USERNAME>\\AppData\\Local\\Google\\Chrome\\User Data',
  args: []
});

Use Chrome instance instead of Chromium by utilizing the Executable Path from the chrome://version URL. Close Chrome browser before running the script

const browser = await puppeteer.launch({
  executablePath: puppeteer.executablePath('chrome')
  // ...
});

Switch to the selected tab

await page.bringToFront();

Get value based on evaluation in the browser page

const shouldPaginate = await page.evaluate(
  (param1, param2) => {
    // ...
  },
  param1,
  param2
);

Get HTML content from the specific element

const html = await page.evaluate(
  () => document.querySelector('.field--text').outerHTML
);

Wait for a specific selector to be loaded. You can also provide a timeout in milliseconds

await page.waitForSelector('.success', { timeout: 5000 });

Manipulate with a specific element and click on some of the elements

await page.$eval('#header', async (headerElement) => {
  // ...
  headerElement
    .querySelectorAll('svg')
    .item(13)
    .parentNode.click();
});

Extend execution of the $eval method

const browser = await puppeteer.launch({
  // ...
  protocolTimeout: 0
});

Manipulate with multiple elements

await page.$$eval('.some-class', async (elements) => {
  // ...
});

Wait for navigation (e.g., form submitting) to be done

await page.waitForNavigation({ waitUntil: 'networkidle0', timeout: 0 });

Trigger hover event on some of the elements

await page.$eval('#header', async (headerElement) => {
  const hoverEvent = new MouseEvent('mouseover', {
    view: window,
    bubbles: true,
    cancelable: true
  });
  headerElement.dispatchEvent(hoverEvent);
});

Expose a function in the browser and use it in $eval and $$eval callbacks (e.g., simulate typing using the window.type function)

await page.exposeFunction('type', async (selector, text, options) => {
  await page.type(selector, text, options);
});
await page.$$eval('.some-class', async (elements) => {
  // ...
  window.type(selector, text, { delay: 0 });
});

Press the Enter button after typing the input field value

await page.type(selector, `${text}${String.fromCharCode(13)}`, options);

Open a file chooser and select file for upload

const [fileChooser] = await Promise.all([page.waitForFileChooser(), page.click(selector)]);
const filePath = `C:/Users/<USERNAME>/Downloads/test.jpeg`; // use "/" instead of "\" in file path
await fileChooser.accept([filePath]);

Remove the value from the input field before typing the new one

await page.click(selector, { clickCount: 3 });
await page.type(selector, text, options);

Expose a variable in the browser by passing it as the third argument for $eval and $$eval methods and use it in $eval and $$eval callbacks

await page.$eval(
  '#element',
  async (element, customVariable) => {
    // ...
  },
  customVariable
);

Mock response for the specific request

await page.setRequestInterception(true);
page.on('request', async function(request) {
  const url = request.url();
  if (url !== REDIRECTION_URL) {
    return request.continue();
  }
  await request.respond({
    contentType: 'text/html',
    status: 304,
    body: '<body></body>'
  });
});

Intercept page redirections (via interceptor) and open them in new tabs rather than following them in the same tab

await page.setRequestInterception(true);
page.on('request', async function(request) {
  const url = request.url();
  if (url !== REDIRECTION_URL) {
    return request.continue();
  }
  await request.respond({
    contentType: 'text/html',
    status: 304,
    body: '<body></body>'
  });
  const newPage = await browser.newPage();
  await newPage.goto(url, { waitUntil: 'domcontentloaded', timeout: 0 });
  // ...
  await newPage.close();
});

Intercept page response

page.on('response', async (response) => {
  if (response.url() === RESPONSE_URL) {
    if (response.status() === 200) {
      // ...
    }
    // ...
  }
});

cURL basics

August 11, 2023

cURL is a command line tool for interacting with servers, it can be used in bash scripts to automate some workflows. This post covers primary usage with examples.

Send an HTTP GET request to the server

curl ipv4.icanhazip.com

Get only the response headers

curl -I ipv4.icanhazip.com

Send POST requests with the request body and headers

curl -X POST https://api.gumroad.com/v2/licenses/verify \
  -d "product_id=product-id" \
  -d "license_key=license-key"
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "What is cURL?"}]
  }'

Use the i option to include the headers in the response

curl -i -X POST https://api.gumroad.com/v2/licenses/verify \
  -d "product_id=product-id" \
  -d "license_key=license-key"

Use the s option to hide all the logs during the request

curl -s -X POST https://api.gumroad.com/v2/licenses/verify \
  -d "product_id=product-id" \
  -d "license_key=license-key"

Use the v option for verbose logs during the request

curl -v -X POST https://api.gumroad.com/v2/licenses/verify \
  -d "product_id=product-id" \
  -d "license_key=license-key"

Retrieve bash script and run it locally

curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash

Trigger specific endpoint inside Kubernetes cronjob

# ...
containers:
  - name: cleanup
    # ...
    command:
      - /bin/sh
      - -ec
      - 'curl "https://some-service.com/cleanup"'

AI bulk image upscaler with Node.js

August 4, 2023

Image upscaling can be done using Real-ESRGAN, a super-resolution algorithm. Super-resolution is the process of increasing the resolution of the image.

Real-ESRGAN provides Linux, Windows and MacOS executable files and models for Intel/AMD/Nvidia GPUs.

The snippet below demonstrates bulk image upscaling with scale factor 4 and using the realesrgan-x4plus-anime model.

(async () => {
  const inputDirectory = path.resolve(path.join(__dirname, 'pictures'));
  const outputDirectory = path.resolve(
    path.join(__dirname, 'pictures_upscaled')
  );
  const modelsPath = path.resolve(path.join(__dirname, 'resources', 'models'));
  const execName = 'realesrgan-ncnn-vulkan';
  const execPath = path.resolve(
    path.join(__dirname, 'resources', getPlatform(), 'bin', execName)
  );
  const scaleFactor = 4;
  const modelName = 'realesrgan-x4plus-anime';
  if (!fs.existsSync(outputDirectory)) {
    await fs.promises.mkdir(outputDirectory, { recursive: true });
  }
  const commands = [
    '-i',
    inputDirectory,
    '-o',
    outputDirectory,
    '-s',
    scaleFactor,
    '-m',
    modelsPath,
    '-n',
    modelName
  ];
  const upscaler = spawn(execPath, commands, {
    cwd: undefined,
    detached: false
  });
  upscaler.stderr.on('data', (data) => {
    console.log(data.toString());
  });
  await timers.setTimeout(600 * 1000);
})();

Publishing Electron apps to GitHub with Electron Forge

July 19, 2023

Releasing Electron desktop apps can be automated with Electron Forge and GitHub Actions. This post covers the main steps for automation.

Prerequisites

bootstrapped Electron app
GitHub personal access token (with repo and write:packages permissions) as a GitHub Action secret (GH_TOKEN)

Setup

Run the following commands to configure Electron Forge for the app release.

npm i @electron-forge/cli @electron-forge/publisher-github -D
npm i electron-squirrel-startup
npx electron-forge import

The last command should install the necessary dependencies and add a configuration file.

Update the forge.config.js file with the bin field containing the app name and ensure the GitHub publisher points to the right repository.

Put Windows and MacOS icons paths in the packagerConfig.icon field, Windows supports ico files with 256x256 resolution, and MacOS supports icns icons with 512x512 resolution (1024x1024 for Retina displays). Linux supports png icons with 512x512 resolution, also include its path in the BrowserWindow constructor config within the icon field.

// forge.config.js
const path = require('path');
module.exports = {
  packagerConfig: {
    asar: true,
    icon: path.join(process.cwd(), 'main', 'build', 'icon')
  },
  rebuildConfig: {},
  makers: [
    {
      name: '@electron-forge/maker-squirrel',
      config: {
        bin: 'Electron Starter'
      }
    },
    {
      name: '@electron-forge/maker-dmg',
      config: {
        bin: 'Electron Starter'
      }
    },
    {
      name: '@electron-forge/maker-deb',
      config: {
        bin: 'Electron Starter',
        options: {
          icon: path.join(process.cwd(), 'main', 'build', 'icon.png')
        }
      }
    },
    {
      name: '@electron-forge/maker-rpm',
      config: {
        bin: 'Electron Starter',
        icon: path.join(process.cwd(), 'main', 'build', 'icon.png')
      }
    }
  ],
  plugins: [
    {
      name: '@electron-forge/plugin-auto-unpack-natives',
      config: {}
    }
  ],
  publishers: [
    {
      name: '@electron-forge/publisher-github',
      config: {
        repository: {
          owner: 'delimitertech',
          name: 'electron-starter'
        },
        prerelease: true
      }
    }
  ]
};

Upgrade the package version before releasing the app. The npm script for publishing should use publish command. Set productName field to the app name.

// package.json
{
  // ...
  "version": "1.0.1",
  "scripts": {
    // ...
    "publish": "electron-forge publish"
  },
  "productName": "Electron Starter"
}

GitHub Action workflow for manually releasing the app for Linux, Windows, and MacOS should contain the below configuration.

# .github/workflows/release.yml
name: Release app
on:
  workflow_dispatch:
jobs:
  build:
    strategy:
      matrix:
        os:
          [
            { name: 'linux', image: 'ubuntu-latest' },
            { name: 'windows', image: 'windows-latest' },
            { name: 'macos', image: 'macos-latest' },
          ]
    runs-on: ${{ matrix.os.image }}
    steps:
      - name: Github checkout
        uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Publish app
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
        run: npm run publish

Windows startup events

Add the following code in the main process to prevent Squirrel.Windows launches your app multiple times during the installation/updating/uninstallation.

// main/index.js
if (require('electron-squirrel-startup') === true) app.quit();

Kafka containers with Docker Compose

July 18, 2023

Docker Compose facilitates spinning up containers for Kafka broker and Zookeeper without installing them locally. Zookeeper is used to track cluster state, membership, and leadership.

Prerequisites

Docker Compose installed

Configuration

The following configuration spins up Kafka and Zookeeper containers with the Kafka UI tool.

The Kafka broker address is http://localhost:29092, and Kafka UI is available at the http://localhost:8085 address.

# docker-compose.yml
version: '3.8'
services:
  kafka:
    image: confluentinc/cp-kafka:6.0.14
    depends_on:
      - zookeeper
    ports:
      - '29092:29092'
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: 'zookeeper:2181'
      KAFKA_ADVERTISED_LISTENERS: LISTENER_DOCKER_INTERNAL://kafka:9092,LISTENER_DOCKER_EXTERNAL://${DOCKER_HOST_IP:-127.0.0.1}:29092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: LISTENER_DOCKER_INTERNAL:PLAINTEXT,LISTENER_DOCKER_EXTERNAL:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: LISTENER_DOCKER_INTERNAL
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    ports:
      - 8085:8080
    environment:
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
      DYNAMIC_CONFIG_ENABLED: 'true'
  zookeeper:
    image: confluentinc/cp-zookeeper:6.0.14
    ports:
      - '22181:2181'
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

Run the following command to spin up the containers.

docker-compose up

Formatting Node.js codebase with Prettier

July 3, 2023

Formatting helps to stay consistent with code style throughout the whole codebase. Include format script in pre-hooks (pre-commit or pre-push). This post covers Prettier setup with JavaScript and TypeScript code.

Start by installing the prettier package as a dev dependency.

npm i prettier -D

Specify rules inside the .prettierrc config file.

{
  "singleQuote": true,
  "trailingComma": "all"
}

Add format script in the package.json file.

{
  "scripts": {
    // ...
    "format": "prettier --write \"{src,test}/**/*.{js,ts}\""
  }
}

Notes

If you use Eslint, install the eslint-config-prettier package as a dev dependency and update the Eslint configuration to use the Prettier config.

// eslint.config.js
// ...
import eslintConfigPrettier from 'eslint-config-prettier';
export default [
  // ...
  eslintConfigPrettier
];

Using Visual Studio Code, you can install a prettier-vscode extension and activate formatting when file changes are saved.

Tracing Node.js Microservices with OpenTelemetry

June 30, 2023

Regarding microservices observability, tracing is important to catch bottlenecks of the services like slow requests and database queries.

OpenTelemetry is a set of monitoring tools that support integration with distributed tracing platforms like Jaeger, Zipkin, and NewRelic, to name a few. This post covers Jaeger's tracing setup for Node.js projects.

Start by setting up the Docker compose via the docker-compose up command. Jaeger UI will be available at http://localhost:16686.

version: '3.8'
services:
  jaeger:
    image: jaegertracing/all-in-one:1.46
    environment:
      - COLLECTOR_ZIPKIN_HTTP_PORT=:9411
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - 6831:6831/udp
      - 6832:6832/udp
      - 5778:5778
      - 16685:16685
      - 16686:16686
      - 14268:14268
      - 14269:14269
      - 14250:14250
      - 9411:9411
      - 4317:4317
      - 4318:4318

The code below shows setting up the tracing via Jaeger. Jaeger doesn't require a separate exporter package since OpenTelemetry supports it natively. Others need to use an exporter package. Filter traces within Jaeger UI by service name or trace ID stored within the logs.

Use resources and semantic resource attributes to set new fields for the trace, like service name or service version. Auto instrumentation identifies frameworks like Express, protocols like HTTP, databases like Postgres, and loggers like Winston used within the project.

Process spans (units of work in distributed systems) in batches to optimize tracing performance. Also, terminate the tracing during the graceful shutdown.

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4318/v1/traces'
});
const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: `<service-name>-${process.env.NODE_ENV}`,
    [SemanticResourceAttributes.SERVICE_VERSION]:
      process.env.npm_package_version ?? '0.0.0',
    env: process.env.NODE_ENV || ''
  }),
  instrumentations: [getNodeAutoInstrumentations()],
  spanProcessor: new BatchSpanProcessor(traceExporter)
});
sdk.start();
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.error('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Import tracing config as the first thing inside the entry file.

import './tracing';
// ...

Search → Service menu should show the service name in Jaeger UI. Happy tracing!

Streaming binary and base64 files

June 25, 2023

Streaming is useful when dealing with big files in web apps. Instead of loading the entire file into memory before sending it to the client, streaming allows you to send it in small chunks, improving memory efficiency and reducing response time.

The code snippet below shows streaming the binary CSV and base64-encoded PDF files with NestJS. Use the same approach for other types of files, like JSON files.

Set content type and filename headers so files are streamed and downloaded correctly. Base64 file is converted to a buffer and streamed afterward. Read files from a file system or by API calls.

import { Controller, Get, Param, Res } from '@nestjs/common';
import { Response } from 'express';
import { createReadStream } from 'fs';
import { readFile } from 'fs/promises';
import { join } from 'path';
import { Readable } from 'stream';
@Controller('templates')
export class TemplatesController {
  @Get('csv')
  getCsvTemplate(@Res() res: Response): void {
    const file = createReadStream(join(process.cwd(), 'template.csv'));
    res.set({
      'Content-Type': 'text/csv',
      'Content-Disposition': 'attachment; filename="template.csv"'
    });
    file.pipe(res);
  }
  @Get('pdf/:id')
  async getPdfTemplate(
    @Param('id') id: string,
    @Res() res: Response
  ): Promise<void> {
    const fileBase64 = await readFile(
      join(process.cwd(), 'template.pdf'),
      'base64'
    );
    // const fileBase64 = await apiCall();
    const fileBuffer = Buffer.from(fileBase64, 'base64');
    const fileStream = Readable.from(fileBuffer);
    res.set({
      'Content-Type': 'application/pdf',
      'Content-Disposition': `attachment; filename="template_${id}.pdf"`
    });
    fileStream.pipe(res);
  }
}

Spies and mocking with Node test runner (node:test)

June 24, 2023

Node.js version 20 brings a stable test runner so you can run tests inside *.test.js files with node --test command. This post covers the primary usage of it regarding spies and mocking for the unit tests.

Spies are functions that let you spy on the behavior of functions called indirectly by some other code while mocking injects test values into the code during the tests.

mock.method can create spies and mock async, rejected async, sync, chained methods, and external and built-in modules.

Async function

import assert from 'node:assert/strict';
import { describe, it, mock } from 'node:test';
const calculationService = {
  calculate: () => // implementation
};
describe('mocking resolved value', () => {
  it('should resolve mocked value', async () => {
    const value = 2;
    mock.method(calculationService, 'calculate', async () => value);
    const result = await calculationService.calculate();
    assert.equal(result, value);
  });
});

Rejected async function

const error = new Error('some error message');
mock.method(calculationService, 'calculate', async () => Promise.reject(error));
await assert.rejects(async () => calculateSomething(calculationService), error);

Sync function

mock.method(calculationService, 'calculate', () => value);

Chained methods

mock.method(calculationService, 'get', () => calculationService);
mock.method(calculationService, 'calculate', async () => value);
const result = await calculationService.get().calculate();

External modules

import axios from 'axios';
mock.method(axios, 'get', async () => ({ data: value }));

Built-in modules

import fs from 'fs/promises';
mock.method(fs, 'readFile', async () => fileContent);

Async and sync functions called multiple times can be mocked with different values using context.mock.fn and mockedFunction.mock.mockImplementationOnce.

describe('mocking same method multiple times with different values', () => {
  it('should resolve mocked values', async (context) => {
    const firstValue = 2;
    const secondValue = 3;
    const calculateMock = context.mock.fn(calculationService.calculate);
    calculateMock.mock.mockImplementationOnce(async () => firstValue, 0);
    calculateMock.mock.mockImplementationOnce(async () => secondValue, 1);
    const firstResult = await calculateMock();
    const secondResult = await calculateMock();
    assert.equal(firstResult, firstValue);
    assert.equal(secondResult, secondValue);
  });
});

To assert called arguments for a spy, use mockedFunction.mock.calls[0] value.

mock.method(calculationService, 'calculate');
await calculateSomething(calculationService, firstValue, secondValue);
const call = calculationService.calculate.mock.calls[0];
assert.deepEqual(call.arguments, [firstValue, secondValue]);

To assert skipped call for a spy, use mockedFunction.mock.calls.length value.

mock.method(calculationService, 'calculate');
assert.equal(calculationService.calculate.mock.calls.length, 0);

To assert how many times mocked function is called, use mockedFunction.mock.calls.length value.

mock.method(calculationService, 'calculate');
calculationService.calculate(3);
calculationService.calculate(2);
assert.equal(calculationService.calculate.mock.calls.length, 2);

To assert called arguments for the exact call when a mocked function is called multiple times, an assertion can be done using mockedFunction.mock.calls[index] and call.arguments values.

const calculateMock = context.mock.fn(calculationService.calculate);
calculateMock.mock.mockImplementationOnce((a) => a + 2, 0);
calculateMock.mock.mockImplementationOnce((a) => a + 3, 1);
calculateMock(firstValue);
calculateMock(secondValue);
[firstValue, secondValue].forEach((argument, index) => {
  const call = calculateMock.mock.calls[index];
  assert.deepEqual(call.arguments, [argument]);
});

Running TypeScript tests

Add a new test script, --experimental-transform-types flag requires Node version >= 22.10.0

{
  "type": "module",
  "scripts": {
    "test": "node --test",
    "test:ts": "NODE_OPTIONS='--experimental-transform-types --disable-warning=ExperimentalWarning' node --test ./src/**/*.{spec,test}.ts"
  }
}

Async API documentation 101

May 21, 2023

Async API documentation is used for documenting events in event-driven systems, like Kafka events. All of the event DTOs are stored in one place. It supports YAML and JSON formats.

It contains information about channels and components. Channels and components are defined with their messages and DTO schemas, respectively.

{
  "asyncapi": "2.6.0",
  "info": {
    "title": "Events docs",
    "version": "1.0.0"
  },
  "channels": {
    "topic_name": {
      "publish": {
        "message": {
          "schemaFormat": "application/vnd.oai.openapi;version=3.0.0",
          "payload": {
            "type": "object",
            "properties": {
              "counter": {
                "type": "number"
              }
            },
            "required": ["counter"]
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EventDto": {
        "type": "object",
        "properties": {
          "counter": {
            "type": "number"
          }
        },
        "required": ["counter"]
      }
    }
  }
}

Autogeneration

Async API docs can be autogenerated by following multiple steps:

define DTOs and their required and optional fields with ApiProperty and ApiPropertyOptional decorators (from the @nestjs/swagger package), respectively
generate OpenAPI docs from the defined DTOs
parse and reuse component schemas from generated OpenAPI documentation to build channel messages and component schemas for Async API docs

Validation

Use AsyncAPI Studio to validate the written specification.

Preview

There are multiple options

AsyncAPI Studio
VSCode extension asyncapi-preview, open the command palette, and run the Preview AsyncAPI command.

UI generation

Install @asyncapi/cli and corresponding template package (e.g., @asyncapi/html-template, @asyncapi/markdown-template)
Update package.json with scripts

{
  "scripts": {
    // ...
    "generate-docs:html": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/html-template --output ./docs/html",
    "generate-docs:markdown": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/markdown-template --output ./docs/markdown"
  }
}

Health checks with Terminus

April 14, 2023

Monitoring tools use health checks to check if service and external dependencies (like a database) are up and running and take some action (like sending alerts) for the unhealthy state.

Terminus provides a set of health indicators.

Liveness probe

An HTTP endpoint checks if the service is up and running.

// health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import {
  HealthCheck,
  HealthCheckResult,
  HealthCheckService,
  HealthIndicatorResult,
  TypeOrmHealthIndicator
} from '@nestjs/terminus';
import { CustomConfigService } from 'common/config/custom-config.service';
@ApiTags('health')
@Controller('health')
export class HealthController {
  constructor(
    private readonly healthCheckService: HealthCheckService,
    private readonly configService: CustomConfigService,
    private readonly database: TypeOrmHealthIndicator
  ) {}
  @Get('liveness')
  @HealthCheck()
  async check(): Promise<HealthCheckResult> {
    return this.healthCheckService.check([
      async (): Promise<HealthIndicatorResult> => ({
        [this.configService.SERVICE_NAME]: { status: 'up' }
      })
    ]);
  }
  // ...
}

A successful response is like the one below.

{
  "status": "ok",
  "info": {
    "nestjs-starter": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "nestjs-starter": {
      "status": "up"
    }
  }
}

Readiness probe

An HTTP endpoint checks if the service is ready to receive the traffic and if all external dependencies are running.

// health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import {
  HealthCheck,
  HealthCheckResult,
  HealthCheckService,
  HealthIndicatorResult,
  TypeOrmHealthIndicator
} from '@nestjs/terminus';
import { CustomConfigService } from 'common/config/custom-config.service';
@ApiTags('health')
@Controller('health')
export class HealthController {
  constructor(
    private readonly healthCheckService: HealthCheckService,
    private readonly configService: CustomConfigService,
    private readonly database: TypeOrmHealthIndicator
  ) {}
  // ...
  @Get('readiness')
  @HealthCheck()
  async checkReadiness(): Promise<HealthCheckResult> {
    return this.healthCheckService.check([
      async (): Promise<HealthIndicatorResult> =>
        this.database.pingCheck('postgres')
    ]);
  }
}

Responses

Successful response

{
  "status": "ok",
  "info": {
    "postgres": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "postgres": {
      "status": "up"
    }
  }
}

Response when the database is down

{
  "status": "error",
  "info": {},
  "error": {
    "postgres": {
      "status": "down"
    }
  },
  "details": {
    "postgres": {
      "status": "down"
    }
  }
}

Linting JavaScript codebase with Eslint

April 5, 2023

Linting represents static code analysis based on specified rules. Please include it in the CI pipeline.

Setup

Run the following commands to generate the linter configuration using the eslint package.

npm init -y
npm init @eslint/config

Below is an example of the configuration. Some rules can be ignored or suppressed as warnings, ignore the files using ignores field.

// eslint.config.js
import globals from 'globals';
import pluginJs from '@eslint/js';
export default [
  { languageOptions: { globals: globals.node } },
  pluginJs.configs.recommended,
  {
    ignores: ['dist/**/*.js']
  },
  {
    rules: {
      'no-console': ['off'],
      'no-unused-vars': ['warn']
    }
  }
];

Linting

Configure and run the script with the npm run lint command. Some errors can be fixed automatically with the --fix option.

// package.json
{
  "scripts": {
    // ...
    "lint": "eslint .",
    "lint:fix": "npm run lint -- --fix"
  }
}

Migrating Node.js app from Heroku to Fly.io

April 1, 2023

I recently migrated the Node.js app from Heroku to Fly.io, mainly due to reduced costs.

This blog post will cover the necessary steps in the migration process.

Prerequisites

Heroku app running
Use the exact versions for dependencies and dev dependencies in package.json so installation and build steps can pass successfully
Use the same Node.js version in Dockerfile, package.json, and GitHub Actions workflow
Use API gateway or custom domain for the service so web apps and mobile apps don't get affected by changing the URL of the service

Migration steps

Migrate environment variables and secrets
Migrate the Postgres database with the following commands (the ssl field in database configuration options is not needed)

fly secrets set HEROKU_DATABASE_URL=$(heroku config:get DATABASE_URL)
fly ssh console
apt update && apt install postgresql-client
pg_dump -Fc --no-acl --no-owner -d $HEROKU_DATABASE_URL | pg_restore --verbose --clean --no-acl --no-owner -d $DATABASE_URL
exit
fly secrets unset HEROKU_DATABASE_URL

Migrate the Redis database if it's used
Include the deployment step in the GitHub Actions workflow

Integration with ChatGPT API

March 19, 2023

ChatGPT is a large language model (LLM) that understands and processes human prompts to produce helpful responses. OpenAI exposes models through the Chat Completions API. The official openai npm package is the practical way to call it from Node.js. This post covers common patterns beyond a single user message.

For the newer Responses API (web search, instructions, and input), see the dedicated post.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
openai package installed (npm i openai)
For Markdown output: marked, dompurify, and jsdom (npm i marked dompurify jsdom)

Client setup

Create a client with your API key (read from the environment in production).

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

The same SDK can target OpenAI-compatible gateways by setting baseURL and apiKey:

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
});

Azure OpenAI uses AzureOpenAI instead. Many third-party hosts implement Chat Completions, so this API is a common integration path.

Basic integration

Send a user message and read the assistant reply from choices[0].message.content.

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    { role: 'user', content: 'Write a one-sentence bedtime story about a unicorn.' },
  ],
});
console.log(completion.choices[0].message.content);

System prompt

Add a system message (or developer on newer models) before the user message to set tone, format, and role.

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    { role: 'system', content: 'Reply in one short sentence. Use plain language.' },
    { role: 'user', content: 'Explain what an LLM is.' },
  ],
});
console.log(completion.choices[0].message.content);

Few-shot prompting

Include prior user and assistant turns in messages, then the new user question. Keep task rules in the system message.

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    {
      role: 'system',
      content:
        'Classify sentiment as exactly one word: positive, negative, or neutral.',
    },
    { role: 'user', content: 'I love this!' },
    { role: 'assistant', content: 'positive' },
    { role: 'user', content: 'This is awful.' },
    { role: 'assistant', content: 'negative' },
    { role: 'user', content: 'It is fine I guess.' },
  ],
});
console.log(completion.choices[0].message.content);

Streaming

Set stream: true and read incremental text from choices[0].delta.content.

const stream = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'List three colors.' }],
  stream: true,
});
process.stdout.write('[stream] ');
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) {
    process.stdout.write(delta);
  }
}
process.stdout.write('\n');

Structured output with JSON schema

Use response_format with type: 'json_schema' and strict: true so the model returns JSON matching your schema.

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    {
      role: 'user',
      content: 'The film Inception was directed by Christopher Nolan.',
    },
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'movie_summary',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          director: { type: 'string' },
        },
        required: ['title', 'director'],
        additionalProperties: false,
      },
    },
  },
});
const data = JSON.parse(completion.choices[0].message.content);
console.log(data.title, data.director);

For typed parsing with Zod, you can use client.chat.completions.parse() instead of JSON.parse.

Markdown output to HTML

Ask for Markdown in the system message, then convert the assistant reply to HTML and sanitize before rendering.

import { marked } from 'marked';
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';
const purify = DOMPurify(new JSDOM('').window);
const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    {
      role: 'system',
      content: 'Reply in Markdown only. Use a heading and a short bullet list.',
    },
    { role: 'user', content: 'Explain what an LLM is in three bullet points.' },
  ],
});
const markdown = completion.choices[0].message.content;
const html = marked.parse(markdown);
const safeHtml = purify.sanitize(html);

Always run DOMPurify.sanitize on model-generated HTML. The model can emit unsafe markup; sanitization strips scripts and other dangerous content.

Demo

Runnable scripts for each section live in the openai-chat-completions-api-demo folder. Get access via code demos.

Documenting REST APIs with OpenAPI specs (NestJS/Swagger)

March 16, 2023

OpenAPI is a language-agnostic specification for declaring API documentation for REST APIs. It contains the following information:

API information like title, description, version
endpoints definitions with request and response parameters
DTOs and security schemas

openapi: 3.0.0
paths:
  /users:
    post:
      operationId: UsersController_createUser
      summary: Create user
      description: Create a new user
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserDto'
      responses:
        '201':
          description: 'User is created'
info:
  title: nestjs-starter
  description: Minimal NestJS boilerplate
  version: 0.1.0
  contact: {}
tags: []
servers: []
components:
  securitySchemes:
    token:
      type: apiKey
      scheme: api_key
      in: header
      name: auth-token
  schemas:
    CreateUserDto:
      type: object
      properties:
        firstName:
          type: string
          example: tester
          description: first name of the user
      required:
        - firstName

NestJS provides a Swagger plugin for generating the API docs.

Setup

Configure API documentation with the specified endpoint, like /api-docs, which shows the generated docs.

const SWAGGER_API_ENDPOINT = '/api-docs';
// ...
export const setupApiDocs = (app: INestApplication): void => {
  const options = new DocumentBuilder()
    .setTitle(SWAGGER_API_TITLE)
    .setDescription(SWAGGER_API_DESCRIPTION)
    .setVersion(SWAGGER_API_VERSION)
    .addSecurity('token', {
      type: 'apiKey',
      scheme: 'api_key',
      in: 'header',
      name: 'auth-token'
    })
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup(SWAGGER_API_ENDPOINT, app, document);
};

Configure the plugin in the NestJS config file.

{
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }
}

JSON and YAML formats are generated at /api-docs-json and /api-docs-yaml endpoints, respectively.

Decorators

ApiTags groups endpoints

@ApiTags('users')
@Controller('users')
export class UsersController {
  // ...
}

ApiOperation provides more details like a summary and description of the endpoint

@ApiOperation({
  summary: 'Get user',
  description: 'Get user by id',
})
@Get(':id')
async getById(
  @Param('id', new ParseUUIDPipe()) id: string,
): Promise<UserDto> {
// ...
}

ApiOperation can be used to mark an endpoint as deprecated

@ApiOperation({ deprecated: true })

@ApiProperty and @ApiPropertyOptional should be used for request and response DTOs fields. Example and description values will be shown in the generated documentation.

export class CreateUserDto {
  @ApiProperty({ example: 'John', description: 'first name of the user' })
  // ...
  public firstName: string;
  @ApiPropertyOptional({ example: 'Doe', description: 'last name of the user' })
  // ...
  public lastName?: string;
}

ApiHeader documents endpoint headers

@ApiHeader({
  name: 'correlation-id',
  required: false,
  description: 'unique id for correlated logs',
  example: '7ea2c7f7-8b46-475d-86f8-7aaaa9e4a35b',
})
@Get()
getHello(): string {
// ...
}

ApiResponse specifies which responses are expected, like error responses. NestJS' Swagger package provides decorators for specific status codes like ApiBadRequestResponse.

// ...
@ApiResponse({ type: NotFoundException, status: HttpStatus.NOT_FOUND })
@ApiBadRequestResponse({ type: BadRequestException })
@Get(':id')
async getById(
  @Param('id', new ParseUUIDPipe()) id: string,
): Promise<UserDto> {
  return this.userService.findById(id);
}
// ...

ApiSecurity('token') uses a custom-defined security strategy, token in this case. Other options are to use already defined strategies like ApiBearerAuth.

@ApiSecurity('token')
@Controller()
export class AppController {
  // ...
}
// ...
@ApiBearerAuth()
@Controller()
export class AppController {
  // ...
}

ApiExcludeEndpoint and ApiExcludeController exclude one endpoint and the whole controller, respectively.

export class AppController {
  @ApiExcludeEndpoint()
  @Get()
  getHello(): string {
    // ...
  }
}
// ...
@ApiExcludeController()
@Controller()
export class AppController {
  // ...
}

ApiBody with ApiExtraModels add an example for the request body

const CreateUserDtoExample = {
    firstName: 'Tester',
  };
  @ApiExtraModels(CreateUserDto)
  @ApiBody({
    schema: {
      oneOf: refs(CreateUserDto),
      example: CreateUserDtoExample,
    },
  })
  @Post()
  async createUser(@Body() newUser: CreateUserDto): Promise<UserDto> {
    // ...
  }

Importing API to Postman

Import JSON version of API docs as Postman API with Import → Link option (e.g., URL http://localhost:8081/api-docs-json). Imported API collection will be available in the APIs tab.

Deploying Next.js apps to Netlify

March 7, 2023

This post covers the main notes for deploying to Netlify and domain setup. Prerequisites Next.js app bootstrapped Deployment Add a new site…

Node.js built-in module functions as Promises

February 28, 2023

Node.js provides asynchronous methods for fs, dns, stream, and timers modules that return Promises.

const {
  createWriteStream,
  promises: { readFile }
} = require('fs');
const dns = require('dns/promises');
const stream = require('stream/promises');
const timers = require('timers/promises');
const sleep = timers.setTimeout;
const SLEEP_TIMEOUT_MS = 2000;
(async () => {
  const fileName = 'test-file';
  const writeStream = createWriteStream(fileName, {
    autoClose: true,
    flags: 'w'
  });
  await stream.pipeline('some text', writeStream);
  await sleep(SLEEP_TIMEOUT_MS);
  const readFileResult = await readFile(fileName);
  console.log(readFileResult.toString());
  const lookupResult = await dns.lookup('google.com');
  console.log(lookupResult);
})();

Use the promisify function to convert other callback-based functions to Promise-based.

const crypto = require('crypto');
const { promisify } = require('util');
const randomBytes = promisify(crypto.randomBytes);
const RANDOM_BYTES_LENGTH = 20;
(async () => {
  const randomBytesResult = await randomBytes(RANDOM_BYTES_LENGTH);
  console.log(randomBytesResult);
})();

Postgres and Redis containers with Docker Compose

February 26, 2023

Docker Compose facilitates spinning up containers for databases without installing the databases locally. This post covers the setup for Postgres and Redis images.

Prerequisites

Docker Compose installed

Configuration

The following configuration spins up Postgres and Redis containers with UI tools (Pgweb and Redis Commander).

Connection strings for Postgres and Redis are redis://localhost:6379 and postgres://username:password@localhost:5435/database-name.

Pgweb and Redis Commander are available at http://localhost:8085 and http://localhost:8081 links.

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:alpine
    environment:
      POSTGRES_DB: database-name
      POSTGRES_PASSWORD: password
      POSTGRES_USER: username
    ports:
      - 5435:5432
    restart: on-failure:3
  pgweb:
    image: sosedoff/pgweb
    depends_on:
      - postgres
    environment:
      PGWEB_DATABASE_URL: postgres://username:password@postgres:5432/database-name?sslmode=disable
    ports:
      - 8085:8081
    restart: on-failure:3
  redis:
    image: redis:latest
    command: redis-server
    volumes:
      - redis:/var/lib/redis
      - redis-config:/usr/local/etc/redis/redis.conf
    ports:
      - 6379:6379
    networks:
      - redis-network
  redis-commander:
    image: rediscommander/redis-commander:latest
    environment:
      - REDIS_HOSTS=local:redis:6379
      - HTTP_USER=root
      - HTTP_PASSWORD=qwerty
    ports:
      - 8081:8081
    networks:
      - redis-network
    depends_on:
      - redis
volumes:
  redis:
  redis-config:
networks:
  redis-network:
    driver: bridge

Run the following command to spin up the containers.

docker-compose up

GitHub actions 101

February 19, 2023

GitHub action is a CI/CD tool integrated within GitHub repositories that can run different kinds of jobs (building, testing, deployment). Store workflow files in .github/workflows inside the repository, which will be triggered based on specified conditions.

This post covers GitHub actions basics, from specifying the workflow name to configuring different jobs.

Name

Specify the name of the workflow with the name field.

# .github/workflows/config.yml
name: CI/CD pipeline

Running

on field specifies when the workflow should be running.

Automatically

The following configuration runs on every push to a specific branch.

# .github/workflows/config.yml
on:
  push:
    branches:
      - main

The following configuration runs on every push to every branch.

# .github/workflows/config.yml
on:
  push:
    branches:
      - '*'

Cron jobs

The following configuration runs at a specified interval (e.g., every hour).

# .github/workflows/config.yml
on:
  schedule:
    - cron: '0 * * * *'

Manual triggers

The following configuration enables manual triggering. Trigger it on the Actions tab by selecting the workflow and clicking the Run workflow button.

Use a manual trigger to upload apps to the Google Play console or update the GitHub profile Readme.

# .github/workflows/config.yml
on:
  workflow_dispatch:

Environment variables

Specify with the env field. Set repository secrets in Settings → Secrets and variables → Actions page.

# .github/workflows/config.yml
env:
  API_KEY: ${{ secrets.API_KEY }}

Jobs

Specify the job name with the name field. Otherwise, the workflow will use the jobs item as the job name.

Every job should have a runs-on field specified for the machine, which will be running on (e.g., ubuntu-latest) or container field with set Docker image (e.g., node:20.9.0-alpine3.17)

Every job can have a separate working directory in case you have multiple subdirectories, and you want to run a different job in a different subdirectory so you can specify it within the defaults field

jobs:
  job-name:
    defaults:
      run:
        working-directory: directory-name

You can specify multiple tasks inside one job. Every task can have the following fields

name - task name
uses - GitHub action path from GitHub Marketplace
with - parameters for the specified GitHub action
run - bash commands
env - environment variables

# .github/workflows/config.yml
jobs:
  build:
    name: Custom build job
    runs-on: ubuntu-latest
    # container: node:20.9.0-alpine3.17
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Configure Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install and build
        run: |
          npm ci
          npm run build

Use the needs field for running jobs sequentially. It specifies a job that has to be finished before starting the next one. Otherwise, jobs will run in parallel.

# .github/workflows/config.yml
jobs:
  build:
  # ...
  deploy:
    name: Custom deploy job
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        run: |
          npm run deploy

Every job can run multiple times with different versions using a matrix strategy (e.g., Node versions 18 and 20 or multiple OS versions inside an array of objects).

# .github/workflows/config.yml
jobs:
  build:
    name: Custom build job
    strategy:
      matrix:
        node-version: [18, 20]
        os:
          [
            { name: 'linux', image: 'ubuntu-latest' },
            { name: 'windows', image: 'windows-latest' },
            { name: 'macos', image: 'macos-latest' },
          ]
    runs-on: ${{ matrix.os.image }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Configure Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Install and build
        run: |
          npm ci
          npm run build

Every job can provision databases for e2e tests with a services field like Postgres in the following example.

# .github/workflows/config.yml
jobs:
  build:
    name: Custom build job
    runs-on: ubuntu-latest
    strategy:
      matrix:
        database-name:
          - test-db
        database-user:
          - username
        database-password:
          - password
        database-host:
          - postgres
        database-port:
          - 5432
    services:
      postgres:
        image: postgres:latest
        env:
          POSTGRES_DB: ${{ matrix.database-name }}
          POSTGRES_USER: ${{ matrix.database-user }}
          POSTGRES_PASSWORD: ${{ matrix.database-password }}
        ports:
          - ${{ matrix.database-port }}:${{ matrix.database-port }}
        # Set health checks to wait until postgres has started
        options: --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      # ...
      - run: npm run test:e2e
        env:
          DATABASE_URL: postgres://${{ matrix.database-user }}:${{ matrix.database-password }}@${{ matrix.database-host }}:${{ matrix.database-port }}/${{ matrix.database-name }}

Passing artifacts between jobs can be done with uploading (actions/upload-artifact) and downloading (actions/download-artifact) actions.

# .github/workflows/config.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Configure Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install and build
        run: |
          npm ci
          npm run build
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: artifact
          path: public
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: artifact
      # ...

Running locally

You can use act to run GitHub actions locally.

Install it and run it with the following commands.

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
cp ./bin/act /usr/local/bin/act
act

Error tracking with Sentry

February 14, 2023

Error tracking and alerting are crucial in the production environment, proactively fixing the errors leads to a better user experience. Sentry is one of the error tracking services, and it provides alerting for unhandled exceptions. You should receive an email when something wrong happens.

Sentry issues show the error stack trace, device, operating system, and browser information. The project dashboard shows an unhandled exception once it's thrown. This post covers the integration of several technologies with Sentry.

Node.js

Create a Node.js project on Sentry
Install the package

npm i @sentry/node

Run the following script

const Sentry = require('@sentry/node');
Sentry.init({
  dsn: SENTRY_DSN
});
test();

Next.js

Create a Next.js project on Sentry (version 13 is not yet supported)
Run the following commands for the setup

npm i @sentry/nextjs
npx @sentry/wizard -i nextjs

Gatsby

Create a Gatsby project on Sentry
Install the package

npm i @sentry/gatsby

Add plugin in Gatsby config

module.exports = {
  plugins: [
    // ...
    {
      resolve: '@sentry/gatsby',
      options: {
        dsn: SENTRY_DSN
      }
    }
  ]
};

React Native

Create a React Native project on Sentry
Run the following commands for the setup

npm i @sentry/react-native
npx @sentry/wizard -i reactNative -p android

Logging practices

February 7, 2023

This post covers some logging practices for the back-end (Node.js) apps.

Avoid putting unique identifiers (e.g., user id) within the message. A unique id will produce a lot of different messages with the same context. Use it as a message parameter.
Use the appropriate log level for the message. There are multiple log levels
- info - app behavior, don't log every single step
- error - app processing failure, something that needs to be fixed
- debug - additional logs needed for troubleshooting
- warning - something unexpected happened (e.g., third-party API fails)
- fatal - app crash, needs to be fixed as soon as possible

Don't use the debug logs on production. Put log level as an environment variable.

Stream logs to the standard output in JSON format so logging aggregators (Graylog, e.g.) can collect and adequately parse them
Avoid logging any credentials, like passwords, auth tokens, etc.
Put correlation ID as a message parameter for tracing related logs.
Use a configurable logger like pino

const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  redact: {
    paths: ['token'],
    remove: true
  }
});
logger.info({ someId: 'id' }, 'Started the app...');
const correlationId = request.headers['correlation-id'] || uuid.v4();
logger.debug(
  { data: 'some data useful for debugging', correlationId },
  'Sending the request...'
);

Vim overview

February 5, 2023

Vim is a text editor known for editing files without using a mouse. It's also useful when you SSH into a remote server, and you have to edit some files there. This post covers the main notes from installation to its usage (shortcuts, commands, configuration).

Installation

Vim is usually already installed on mostly *nix operating systems. You can install it via the package manager and open it with the following commands.

sudo apt-get update
sudo apt-get install -y vim
vim

Modes

Vim has four modes

Normal - this is the default mode. It enables scrolling through the file content
Visual - type v, and you can select text content for deleting and copying with scrolling shortcuts
Insert - type i, and you can start editing the file content
Command-line - type : and some command plus Enter to run the command

Usage

Shortcuts

Esc - go back to Normal mode
h to scroll left
j to scroll down
k to scroll up
l to scroll right
Shift + g - scroll to the end of the file
g + g - scroll to the beginning of the file
line number + Shift + g, (e.g., 5 + Shift + g) - jump to the specific line number, 5th in this case
^ - jump to the start of the current line
$ - jump to the end of the current line
w - move to the next word
b - move back to the previous word

Commands

:edit script.js - create a new file or open the existing one
:w - save the changes
:q - exit the file
:wq - save the changes and exit the file
:q! - exit without the changes
:%s/<text>/<new text>/g - find and replace the occurrences within the whole file (e.g., :%s/Vim/Emacs/g)
: + ↑ - to find the previous command

Miscellaneous

Copy pasting
- enter the visual mode, scroll through the text you want to copy, type y, then scroll to the place you want to paste it and type p
- type y + number of lines + y to copy specified lines and paste it with p
Deleting
- enter the visual mode, scroll through the text you want to delete, and type d
- type d + number of lines + d to delete specified lines
- type x to remove the letter
- type dw to remove the word (and the space after it)
Type u to undo the previous change
Type CTRL + r to redo the previous undo
Find specific text with /<text> like /vim and press Enter. Type n to go to the next occurrence and N to the previous one

Configuration

Vim configuration is stored in ~/.vimrc file. You can specify plugins and other configurations, like theme, tabs spaces, etc.

To use plugins, install the vim-plug plugin manager with the following command

curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
  https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

and run the :PlugInstall command.

Check the status of the plugins with the :PlugStatus command.

Below is the configuration I use.

"------PLUGINS SETTINGS---------
set nocompatible              " be iMproved, required
filetype off                  " required
call plug#begin('~/.vim/plugged')
Plug 'vim-airline/vim-airline'
Plug 'vim-airline/vim-airline-themes'
Plug 'Raimondi/delimitMate'
Plug 'flazz/vim-colorschemes'
Plug 'prettier/vim-prettier', { 'do': 'npm install' }
Plug 'tpope/vim-commentary'
" All of your Plugins must be added before the following line
call plug#end()              " required
filetype plugin indent on    " required
"---------AIRLINE SETTINGS------
let g:airline_powerline_fonts = 1
let g:airline_theme='solarized'
"-----COMMENTARY SETTINGS-------
noremap <leader>/ :Commentary<cr>
"-----PRETTIER SETTINGS---------
let g:prettier#autoformat = 1
let g:prettier#autoformat_require_pragma = 0
"------------TABS---------------
set expandtab
set tabstop=2
set shiftwidth=2
set softtabstop=2
" makefile tabs
autocmd FileType make setlocal noexpandtab
" tab completion
set wildmenu
" line numbers
set number
set relativenumber
syntax on
" theme
colorscheme molokai
let g:solarized_termcolors=256
set background=dark
" indention
set autoindent
" highlight found words
set hlsearch
" press left/right and move to the previous/next line after reaching the first/last character in the line
set whichwrap+=<,>,h,l,[,]
" long lines
nnoremap k gk
nnoremap j gj
" disable arrow keys in normal mode
map <Left> <Nop>
map <Right> <Nop>
map <Up> <Nop>
map <Down> <Nop>
" toggling paste mode
set pastetoggle=<F2>
" last command
set showcmd
" disable swap files and backups
set noswapfile
set nobackup
set nowritebackup
" mouse click navigation
set mouse=a

Further learning

Try vimtutor with the following command to dive deep into Vim features.

vimtutor