Casual Programming RSS Feed

Types in Typescript should make your life easier

Wed, 17 Dec 2025 11:37:00 GMT

Type systems are great, but it depends how you use them. I see often developers obsessed with name conventions or pattern design architectures, but not very often to tackle what matters. what it matters to me:

Most real failures come from I/O: environment variables, network boundaries, databases, and external APIs. If someone changes a function inside your codebase, you’ll see it in reviews or tests. If an external API changes its payload shape, you often only discover it in production. If you forgot and env vars, your be may not start up after the deployment, if your react client got the wrong response, it may not render your page correctly and so on. A good coding and testing style prioritizes validating I/O early, explicitly, and at the boundaries.
Defining and mantaining Types should not be a lot of “manual” works and it should be driven by the compiler, not from you hammering differnt types to keep them in sync. There are some rules you can follow.
You should know as many think as possible at compile time. if you are using Typescript for evertying and you have a monorepo, then if infra code breaks the be code (let’s say due to an env var change), you should know it at compile time. if the backend change the contract and breaks the render of the frontend , you should know it at compile time,an so on..

Zod Is the De‑Facto Standard

In the TypeScript ecosystem, Zod is effectively the de‑facto standard for runtime validation that stays aligned with static types.

Zod:

Synchronizes runtime checks and TypeScript inference
Makes failures explicit
Pushes errors to the leafs of the system, where unknown data enters

Prefer Zod‑compatible libraries so validation remains consistent:

Network contracts: ts-rest, tRPC
Environment variables: Zod schemas parsed at startup
Databases: Drizzle + Zod for inputs/outputs

Validate What You Don’t Control

If someone changes a function in your codebase, you’ll notice.
If an external system changes its behavior, you won’t—unless you validate.

Typical I/O boundaries:

Environment variables
Network requests and responses
Database reads/writes
Third‑party APIs

Fail fast, close to the source.

Never Use `any`

Never use any.
If you don’t know the shape, use unknown and narrow it.

If you know something, encode it:

Record<string, unknown>

This forces assumptions to be proven instead of silently trusted.

Strings Are Overused

A user ID is not “just a string”. It’s a UserId.

Use branded types:

export const UserId = z.uuid().brand<'UserId'>();
export type UserId = z.infer<typeof UserId>;

Reuse branded identifiers everywhere. This prevents accidentally mixing unrelated strings across your domain.

Avoid Enums: They Kill Composability

TypeScript enums reduce composability and flexibility.

Prefer literal unions (or as const arrays) instead. They:

Compose naturally
Work cleanly with Zod
Avoid runtime artifacts

If you want to enforce this, enable:

{
  "compilerOptions": {
    "erasableSyntaxOnly": true
  }
}

Prefer `type` Over `interface`

Interfaces:

Don’t compose as well
Encourage inheritance

Prefer type aliases:

Better with unions and intersections
More aligned with functional domain modeling

Strict Types Aren’t Expensive — Duplication Is

Most “types are expensive” complaints come from duplication.

Model relationships and derive types instead of redefining them.

export const User = z.object({
  id: UserId,
  name: UserName,
  dob: UserDob,
});

export const CreateUser = User.omit({ id: true });
export const ModifyUser = CreateUser.partial();

Derivation keeps refactors cheap and models consistent.

Use Discriminated Unions

Discriminated unions make invalid states unrepresentable.

Zod Example

import { z } from 'zod';

const WithOpeningDate = z.object({
  openingDateStatus: z.literal('available'),
  opening_date: z.date(),
});

const NoOpeningDate = z.object({
  openingDateStatus: z.literal('notav'),
});

const CommonForm = z.object({
  title: z.string(),
  description: z.string(),
});

export const Form = z.discriminatedUnion('openingDateStatus', [
  CommonForm.merge(WithOpeningDate),
  CommonForm.merge(NoOpeningDate),
]);

export type Form = z.infer<typeof Form>;

Both runtime and compile‑time validation now agree.

Explicit Environment Variable Validation

Validate environment variables at startup. Fail loudly.

import { z } from 'zod';

export const Stages = z.union([
  z.literal('local'),
  z.literal('dev'),
  z.literal('staging'),
  z.literal('prod'),
]);

const DatabaseUrl = z.union([z.string().url(), z.literal(':inmemory:')]);

export const EnvSchema = z.object({
  STAGE: Stages,
  AWS_REGION: z.string(),
  DATABASE_URL: DatabaseUrl.default(':inmemory:'),
});

const parsedEnv = EnvSchema.parse(process.env);

for (const [key, value] of Object.entries(parsedEnv)) {
  if (process.env[key] === undefined && value !== undefined) {
    process.env[key] = value.toString();
  }
}

export const envVarsConfig = parsedEnv;

Do not lazily validate config later.
Delayed validation leads to opaque runtime failures.

Share Types in a Monorepo

If you use a monorepo, share your types:

Share env var schemas between infra and backend
Share domain models between backend and frontend
Share network contracts between server and client

This prevents drift.

Network Validation with ts‑rest

Use ts-rest on both server and client so the network boundary is typed and validated.

Zod defines the contract
The server validates requests and responses
The client is type‑safe by construction

No duplicated DTOs. No guessing.

Minimal Monorepo Example (Conceptual)

Stack

Zod (schemas)
ts-rest (network)
Express (server)
Drizzle (database)
React (client)
CDK (infra)

Shared package

Domain schemas
Env var schemas
API contracts

Backend

Parses env vars using shared schema
Validates network input via ts-rest
Uses Drizzle for typed DB access

Frontend

Uses ts-rest client generated from shared contract
Uses shared Zod schemas for input validation

Infra (CDK)

Reuses env var definitions from shared package
Avoids config drift

Final Takeaways

Types are great, but I/O validation is critical
Validate what you don’t control
Zod is the de‑facto standard
Never use any
Avoid enums
Prefer type over interface
Use branded types for domain identifiers
Derive related schemas instead of duplicating them
Use discriminated unions
Share schemas and contracts across your monorepo

Strong types plus explicit runtime validation lead to predictable systems and far fewer production surprises.

Progressive React: When Your App Still Works with JS Disabled

Sat, 26 Jul 2025 19:37:00 GMT

In the last year, I worked extensively with Remix and React Router 7, and I have to say it was a genuinely pleasant experience. If you’re a seasoned web developer like me—someone who was there when AJAX was becoming a thing and struggled to make websites work both with and without JavaScript enabled—you’ll really appreciate the evolution of React Router.

To demonstrate these concepts, I built a Matrix chat application that works almost entirely without JavaScript. You can try it yourself at https://matrix-chat.fly.dev - disable JavaScript in your browser and see how everything works: registration, login, room creation, browsing rooms, and sending messages. The only thing that won’t work is seeing new messages from other users in real-time—you’ll need to refresh the page for that. Then re-enable JavaScript to get the enhanced real-time synchronization.

Why This Matters: Beyond Just “Working Without JavaScript”

The point of building apps that work without JavaScript isn’t just about supporting users who have disabled JavaScript—though that’s important. The real benefits are more practical and impactful:

Escaping the Uncanny Valley

The most compelling reason is performance and user experience. In poor network conditions, your JavaScript bundle might take 10-15 seconds to download and parse. During this time, users are stuck in an “uncanny valley”—they can see your app, but nothing works when they click. Buttons don’t respond, forms don’t submit, links don’t navigate. This can last much longer than you think, especially on slower devices or networks.

With progressive enhancement, your app is immediately functional. Users can start accomplishing their goals right away, even if the enhanced features haven’t loaded yet.

Real Performance Benefits

Faster Time to Interactive (TTI): Core functionality is available before JavaScript loads
Reduced Cumulative Layout Shift (CLS): Server-rendered content is stable and complete
Better First Contentful Paint (FCP): No waiting for client-side rendering
Resilient to JavaScript failures: If your bundle fails to load or throws an error, the app still works

Accessibility by Default

Screen readers work immediately: Server-rendered HTML is immediately accessible to assistive technologies
Keyboard navigation: Standard HTML elements provide built-in keyboard support
Low-powered devices: Older devices that struggle with heavy JavaScript can still use the app
Assistive technology compatibility: Progressive enhancement ensures compatibility with a wider range of accessibility tools

SEO and Crawlability

Search engines get real content: No waiting for JavaScript to render content
Social media previews work: Open Graph tags and meta descriptions are immediately available
Web scrapers and bots: Third-party tools can access your content without executing JavaScript

Developer Benefits

Easier debugging: You can isolate server-side vs client-side issues
Simpler testing: Core functionality can be tested without complex JavaScript environments
Better error boundaries: Server-side errors are handled gracefully, client-side errors don’t break core functionality

The Philosophy: Progressive Enhancement as Modern Best Practice

This approach represents a return to web fundamentals, but with modern tools that make it sustainable. HTML provides structure, CSS provides presentation, and JavaScript provides behavior enhancement. The magic happens when these technologies work together harmoniously, with each layer gracefully degrading when the next isn’t available.

Modern React development, especially with server-side rendering and React Server Components, is essentially a sophisticated evolution of this principle. We’re not abandoning the separation of concerns; we’re redefining what those concerns are. Instead of separating HTML, CSS, and JavaScript, we’re now separating server and client responsibilities.

About the Matrix Protocol

For this project, I didn’t want to build a chat backend from scratch—I just needed a backend-for-frontend. So I leveraged the Matrix Protocol (https://matrix.org/), an open standard for real-time communication. This meant I could simply run a Docker image to have a fully functional chat server available.

Matrix is particularly interesting for this demonstration because it provides a real-world API that supports both REST endpoints and real-time features. This gives us the perfect opportunity to showcase how React Router 7 handles both traditional form submissions (which work without JavaScript) and enhanced real-time features (which require JavaScript for polling or WebSocket connections).

React Router 7: The Bridge Between Server and Client

If you’re already familiar with React Router or Remix, feel free to skip this section—but if you’re new to this paradigm, understanding these concepts is crucial to appreciating the progressive enhancement approach.

The Anatomy of a Route

In React Router 7, a route is a file that contains everything needed for a page. Think of it as a complete page definition with three key parts:

loader → Executes on the server when the page is accessed with a GET request
action → Executes on the server when the page receives non-GET requests (POST, DELETE, etc.)
default export → The UI component that renders both server-side and client-side

Server vs. Client Execution

Here’s where it gets interesting: everything runs on the server first, except for React’s useEffect hooks. The default export (your React component) runs in both environments, but with an important distinction:

Server-side: Everything executes except useEffect hooks
Client-side: The component is hydrated with server data, then useEffect hooks execute

This dual execution model is what enables progressive enhancement—your app works completely without JavaScript, but gains enhanced interactivity when JavaScript is available.

A Practical Example

import { json, LoaderFunctionArgs, ActionFunctionArgs } from "react-router";
import { Form, useLoaderData, useNavigation } from "react-router";

// Runs on server for GET requests
export async function loader({ params }: LoaderFunctionArgs) {
  const messages = await fetchMessages(params.roomId);
  return json({ messages });
}

// Runs on server for POST/PUT/DELETE requests
export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const message = formData.get("message");
  await sendMessage(message);
  return json({ success: true });
}

// Runs on both server and client
export default function ChatRoom() {
  const { messages } = useLoaderData<typeof loader>();
  const navigation = useNavigation();
  
  // This runs on both server and client
  console.log("Rendering chat room");
  
  // This ONLY runs on the client
  useEffect(() => {
    console.log("Setting up real-time polling");
    const interval = setInterval(pollForNewMessages, 1000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div>
      <div className="messages">
        {messages.map(msg => <div key={msg.id}>{msg.text}</div>)}
      </div>
      
      {/* This form works with or without JavaScript */}
      <Form method="post">
        <input name="message" placeholder="Type a message..." />
        <button type="submit" disabled={navigation.state === "submitting"}>
          {navigation.state === "submitting" ? "Sending..." : "Send"}
        </button>
      </Form>
    </div>
  );
}

Key Components and Hooks

React Router provides several crucial components that enable progressive enhancement:

<Form> → Creates forms that work both with and without JavaScript
<Link> → Navigation that enhances to client-side routing when JavaScript is available
useLoaderData() → Access server-loaded data
useNavigation() → Track form submission and navigation states for enhanced UX

Progressive Enhancement in Practice

The beauty of this approach becomes clear when you see how fundamental web features are handled. Let’s examine how key functionality works both with and without JavaScript:

Without JavaScript: Nearly Full Functionality

When JavaScript is disabled, the chat application works almost completely because it relies on fundamental web technologies:

User registration and login → Forms submit via HTTP POST with server-side authentication
Room creation → Standard form submission creates new Matrix rooms
Room browsing and search → GET requests with URL parameters for filtering
Message sending → Forms post messages to the Matrix server
Navigation → All links work as traditional page navigations
Server-side rendering → Every page loads with complete HTML content and styling

The only missing feature: Real-time message updates from other users. You’ll need to refresh the page to see new messages. Everything else works exactly the same.

With JavaScript: Enhanced Experience

When JavaScript is available, the same foundation gets enhanced:

Forms become AJAX calls → Smooth, in-page submission without full page reloads
Navigation becomes client-side routing → Instant page transitions
Real-time updates → Polling or WebSocket connections for live message updates
Loading states → Visual feedback during form submissions and navigation

Feature Comparison: Matrix Chat Implementation

Feature	Traditional SPA Approach	React Router 7 Approach
Login/Register	Form submission blocked, AJAX call, manual redirect handling	`<Form>` component, server `action`, automatic redirect
Create Room	Client-side form submission, loading states, error handling	Server `action` with built-in validation and redirect
Search Rooms	Debounced client-side search, manual state management	URL-based search with server `loader`, automatic caching
Room Messages	useEffect fetch, manual polling, complex state sync	Server `loader` + client-side polling with `useEffect`

Implementation Deep Dive

Let’s examine how each feature was implemented using React Router 7 patterns, showing the actual code that makes progressive enhancement work.

Login/Register

The authentication system demonstrates the power of action functions and progressive form handling. The same form works with and without JavaScript:

// app/routes/login.tsx
export async function loader({ request }: LoaderFunctionArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const token = await getTokenFromCookie(cookieHeader);
  
  // Redirect if already authenticated
  if (token) {
    return redirect("/");
  }
  
  return null;
}

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const intent = formData.get("intent");
  const username = formData.get("username");
  const password = formData.get("password");

  if (intent === "login") {
    const response = await fetch(`${matrixUrl}/_matrix/client/v3/login`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        type: "m.login.password",
        user: username,
        password: password,
      }),
    });

    if (response.ok) {
      const { access_token } = await response.json();
      
      return redirect("/", {
        headers: {
          "Set-Cookie": await createUserSession(access_token),
        },
      });
    }
  }

  return json({ error: "Invalid credentials" });
}

export default function Login() {
  const navigation = useNavigation();
  const actionData = useActionData<typeof action>();

  return (
    <Form method="post">
      <input name="username" placeholder="Username" required />
      <input name="password" type="password" placeholder="Password" required />
      
      <button name="intent" value="login" type="submit" 
              disabled={navigation.state === "submitting"}>
        {navigation.state === "submitting" ? "Signing in..." : "Sign In"}
      </button>
      
      <button name="intent" value="register" type="submit">
        Register
      </button>
      
      {actionData?.error && <p className="error">{actionData.error}</p>}
    </Form>
  );
}

Why this works progressively:

Without JS: Form submits via HTTP POST, page refreshes with results
With JS: Enhanced with loading states and no page refresh
Server-side: Authentication logic runs on the server, cookies are secure

Create Room

Room creation shows how server actions can handle complex API integrations while maintaining form simplicity:

// app/routes/createroom.tsx
export async function action({ request }: ActionFunctionArgs) {
  const token = await requireUserSession(request);
  const formData = await request.formData();
  
  const roomName = formData.get("roomName");
  const topic = formData.get("topic");
  const isPublic = formData.get("visibility") === "public";

  try {
    const response = await fetch(`${matrixUrl}/_matrix/client/v3/createRoom`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: roomName,
        topic: topic,
        visibility: isPublic ? "public" : "private",
        preset: isPublic ? "public_chat" : "private_chat",
      }),
    });

    if (response.ok) {
      const { room_id } = await response.json();
      return redirect(`/room/${room_id}`);
    }
  } catch (error) {
    return json({ error: "Failed to create room" });
  }
}

export default function CreateRoom() {
  const navigation = useNavigation();
  const actionData = useActionData<typeof action>();

  return (
    <Form method="post">
      <input name="roomName" placeholder="Room Name" required />
      <textarea name="topic" placeholder="Room Topic" />
      
      <select name="visibility">
        <option value="private">Private</option>
        <option value="public">Public</option>
      </select>
      
      <button type="submit" disabled={navigation.state === "submitting"}>
        {navigation.state === "submitting" ? "Creating..." : "Create Room"}
      </button>
      
      {actionData?.error && <p className="error">{actionData.error}</p>}
    </Form>
  );
}

Progressive enhancement benefits:

Server validation: Input validation happens on the server first
Automatic redirect: No manual navigation handling required
Error handling: Built-in error states without try/catch blocks

Search Rooms

Room search demonstrates URL-driven state management that works perfectly without JavaScript:

// app/routes/browse.tsx
export async function loader({ request }: LoaderFunctionArgs) {
  const token = await requireUserSession(request);
  const url = new URL(request.url);
  const filter = url.searchParams.get("filter");
  
  const body: any = { limit: 100 };
  if (filter) {
    body.filter = { generic_search_term: filter };
  }

  const response = await fetch(`${matrixUrl}/_matrix/client/v3/publicRooms`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const { chunk: rooms } = await response.json();
  return json({ rooms, filter });
}

export default function Browse() {
  const { rooms, filter } = useLoaderData<typeof loader>();
  const navigation = useNavigation();

  return (
    <div>
      <Form method="get">
        <input 
          name="filter" 
          placeholder="Search rooms..." 
          defaultValue={filter || ""} 
        />
        <button type="submit">Search</button>
      </Form>

      {navigation.state === "loading" && <p>Searching...</p>}
      
      <div className="rooms">
        {rooms.map(room => (
          <Link key={room.room_id} to={`/room/${room.room_id}`}>
            <h3>{room.name || room.canonical_alias}</h3>
            <p>{room.topic}</p>
            <span>{room.num_joined_members} members</span>
          </Link>
        ))}
      </div>
    </div>
  );
}

URL-driven state advantages:

Bookmarkable searches: Share filtered results via URL
Back button works: Browser navigation handles search history
Server-side filtering: Fast initial page loads with filtered results

Room Messages and Real-time Updates

The room page shows the perfect blend of server-side data loading and client-side enhancement:

// app/routes/room.tsx
export async function loader({ params, request }: Route.LoaderArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const token = await matrixTokenCookie.parse(cookieHeader);
  const baseUrl = await matrixBaseUrlCookie.parse(cookieHeader);
  
  if (!token || !baseUrl) {
    throw redirect("/login");
  }

  const roomId = params.roomId;
  
  // Fetch room details
  const roomResponse = await fetch(`${baseUrl}/_matrix/client/v3/rooms/${roomId}/state/m.room.name`, {
    headers: { "Authorization": `Bearer ${token}` }
  });
  
  // Fetch initial messages
  const messagesResponse = await fetch(
    `${baseUrl}/_matrix/client/v3/rooms/${roomId}/messages?dir=b&limit=20`,
    {
      headers: { "Authorization": `Bearer ${token}` }
    }
  );
  
  const roomData = await roomResponse.json();
  const messagesData = await messagesResponse.json();
  
  // Convert Matrix events to our Message format
  const messages = messagesData.chunk
    .filter((event: any) => event.type === "m.room.message")
    .map((event: any) => ({
      id: event.event_id,
      sender: event.sender,
      body: event.content.body,
      timestamp: new Date(event.origin_server_ts)
    }))
    .reverse();

  return {
    room: { id: roomId, name: roomData.name || roomId },
    messages,
    matrixConfig: { token, baseUrl }
  };
}

export async function action({ request, params }: Route.ActionArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const token = await matrixTokenCookie.parse(cookieHeader);
  const baseUrl = await matrixBaseUrlCookie.parse(cookieHeader);
  
  const formData = await request.formData();
  const message = formData.get("message");
  
  const response = await fetch(
    `${baseUrl}/_matrix/client/v3/rooms/${params.roomId}/send/m.room.message/${Date.now()}`,
    {
      method: "PUT",
      headers: {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        msgtype: "m.text",
        body: message,
      }),
    }
  );
  
  return { success: response.ok };
}

export default function Room() {
  const { room, messages: initialMessages, matrixConfig } = useLoaderData<typeof loader>();
  const navigation = useNavigation();
  
  // Custom hook for Matrix synchronization - this is where the magic happens!
  const { messages, isConnected, error } = useMatrixSync({
    roomId: room.id,
    initialEvents: initialMessages,  // Server-provided initial data
    token: matrixConfig.token,
    baseUrl: matrixConfig.baseUrl
  });

  return (
    <div>
      <div className="room-header">
        <h1>{room.name}</h1>
        <div className="connection-status">
          {isConnected ? "🟢 Connected" : "🔴 Disconnected"}
        </div>
      </div>
      
      <div className="messages">
        {messages.map(message => (
          <div key={message.id} className="message">
            <strong>{message.sender}</strong>: {message.body}
            <time>{message.timestamp.toLocaleTimeString()}</time>
          </div>
        ))}
      </div>
      
      <Form method="post">
        <input 
          name="message" 
          type="text" 
          placeholder="Type a message..." 
          required 
          disabled={navigation.state === "submitting"}
        />
        <button type="submit" disabled={navigation.state === "submitting"}>
          {navigation.state === "submitting" ? "Sending..." : "Send"}
        </button>
      </Form>
      
      {error && <div className="error">Connection error: {error}</div>}
    </div>
  );
}

Now, here’s the crucial part - the custom useMatrixSync hook:

// app/hooks/useMatrixSync.ts
export function useMatrixSync({ roomId, initialEvents, token, baseUrl }: {
  roomId: string;
  initialEvents: Message[];
  token: string;
  baseUrl: string;
}) {
  const [messages, setMessages] = useState(initialEvents);
  const [isConnected, setIsConnected] = useState(false);
  const [error, setError] = useState<string | null>(null);
  
  // This runs on both server and client, but the initial messages 
  // are provided by the server loader
  console.log("useMatrixSync: Setting up with", initialEvents.length, "initial messages");
  
  useEffect(() => {
    // This ONLY runs on the client side - perfect for real-time sync!
    console.log("useMatrixSync: Starting client-side sync for room", roomId);
    
    let syncToken: string | null = null;
    let abortController = new AbortController();
    
    async function sync() {
      try {
        const syncUrl = new URL(`${baseUrl}/_matrix/client/v3/sync`);
        syncUrl.searchParams.set("timeout", "30000");
        syncUrl.searchParams.set("filter", JSON.stringify({
          room: { rooms: [roomId] }
        }));
        
        if (syncToken) {
          syncUrl.searchParams.set("since", syncToken);
        }
        
        const response = await fetch(syncUrl.toString(), {
          headers: { "Authorization": `Bearer ${token}` },
          signal: abortController.signal
        });
        
        if (response.ok) {
          const syncData = await response.json();
          setIsConnected(true);
          setError(null);
          
          // Process new messages
          const roomData = syncData.rooms?.join?.[roomId] || syncData.rooms?.timeline?.[roomId];
          if (roomData?.timeline?.events) {
            const newMessages = roomData.timeline.events
              .filter((event: any) => event.type === "m.room.message")
              .map((event: any) => ({
                id: event.event_id,
                sender: event.sender,
                body: event.content.body,
                timestamp: new Date(event.origin_server_ts)
              }));
            
            setMessages(current => [...current, ...newMessages]);
          }
          
          syncToken = syncData.next_batch;
          // Continue syncing
          setTimeout(sync, 100);
        }
      } catch (error) {
        if (error.name !== "AbortError") {
          setIsConnected(false);
          setError(error.message);
          // Retry after delay
          setTimeout(sync, 5000);
        }
      }
    }
    
    sync();
    
    return () => {
      abortController.abort();
    };
  }, [roomId, token, baseUrl]);
  
  return { messages, isConnected, error };
}

The Custom Hook Magic: Server-Side Execution

Here’s the fascinating part about the useMatrixSync hook that perfectly demonstrates React Router 7’s dual execution model:

// This part runs on BOTH server and client
const [messages, setMessages] = useState(initialEvents);  // ✅ Server & Client
console.log("Setting up with", initialEvents.length, "initial messages");  // ✅ Server & Client

// This part runs ONLY on the client  
useEffect(() => {  // ❌ Server (skipped), ✅ Client only
  console.log("Starting client-side sync");
  // All the real-time synchronization logic
}, [roomId]);

Why the hook accepts initialEvents:

The custom hook needs initialEvents from the loader because when it runs on the server during SSR, the useEffect won’t execute. The server-side execution only initializes the state with the data we fetched in the loader. Then, when the component hydrates on the client, the useEffect kicks in and starts the real-time synchronization from where the server left off.

This creates a seamless handoff:

Server: Fetches initial messages, passes them to the hook, hook initializes state
Client: Hook hydrates with server state, then useEffect begins real-time sync
Result: No gap in data, no loading states, perfect progressive enhancement

Perfect progressive enhancement:

Server-side: Initial messages load immediately, forms work without JS
Client-side: Real-time updates and enhanced UX when JS is available
Graceful degradation: If polling fails, manual refresh still works
Hook design: Accepts server data to bridge server-client execution seamlessly

The Evolution of Separation of Concerns

Here’s where things get philosophically interesting. The traditional “separation of concerns” in web development meant separating technologies: HTML in one file, CSS in another, JavaScript in a third. We were taught that mixing these was evil—it created “spaghetti code” that was hard to maintain.

But React and modern frameworks challenged this thinking. Instead of separating by technology, we began separating by feature or component. A button component might contain its HTML structure, CSS styling, and JavaScript behavior all in one place. This felt wrong at first, but it proved to be more maintainable for complex applications.

React Router 7 and React Server Components represent the next evolution: separating by execution environment. We’re not just thinking about what runs where, but when it runs and why. This creates a new kind of separation of concerns:

Server concerns: Data fetching, authentication, business logic, initial rendering
Client concerns: User interactions, real-time updates, enhanced UX, local state

This isn’t abandoning separation of concerns—it’s refining what those concerns actually are. We’re returning to the web’s original progressive enhancement model, but with modern tools that make it sustainable and developer-friendly.

Why This Matters for Backend-for-Frontend

In the past, when I built React apps with a separate backend-for-frontend (often in PHP), I had to:

Manually configure Webpack to split code by route
Manually type every HTTP call
Keep frontend and backend logic in sync across different languages
Handle loading states, error states, and form submissions in every component

React Router 7 eliminates this friction. The loader and action functions run on the server, giving you the backend-for-frontend logic right alongside your components. There’s no context switching between languages, no manual API typing, and no wondering whether your frontend and backend are in sync.

It’s not just about reducing work—it’s about reducing the cognitive overhead of building web applications.

Key Takeaways

Building this Matrix chat application with React Router 7 reinforced several important principles:

More Belongs in Loaders and Actions Than You Think

Initially, I tried to keep server-side logic minimal, but I discovered that pushing more logic into loaders and actions creates a better user experience. Authentication checks, data validation, business logic, and even complex data transformations work better on the server where they can fail fast and provide immediate feedback. I even ditched entirely the typescript sdk for matrix in favour of doing every query and command in the loader / action, and having a bunch of custom hooks which would listend for events comming.

Embrace URL State

Put as much state as possible in the URL—it’s easier for both developers and users. Room IDs, filter states, pagination, and even UI preferences can live in the URL. This makes the application more shareable, bookmarkable, and debuggable. React Router’s nested routing makes this natural and maintainable.

Progressive Enhancement Isn’t Just Nice-to-Have

When your app works without JavaScript, you’ve built something fundamentally more resilient. It will work on slow networks, older devices, and in environments where JavaScript fails to load. But more importantly, you’ve built something that aligns with the grain of the web rather than fighting against it.

The Framework Handles the Hard Parts

React Router 7 eliminates so much boilerplate around form handling, loading states, error boundaries, and data synchronization. You write declarative loaders and actions, and the framework handles optimistic updates, race conditions, and state management automatically.

Conclusion

React is evolving back toward the web’s fundamental principles, and that’s not a step backward—it’s a step forward with better tools. Server-side rendering, progressive enhancement, and unobtrusive JavaScript aren’t old-fashioned ideas; they’re timeless principles that modern frameworks are finally making approachable.

The Matrix chat application demonstrates that you can build rich, interactive experiences without sacrificing accessibility, performance, or reliability. When your React app works with JavaScript disabled, you know you’ve built something that truly embraces the web platform.

Try it yourself: disable JavaScript in your browser and see how many of your favorite web applications still work. Then imagine building your next project with progressive enhancement from day one. The web—and your users—will thank you for it.

Thinking in React in few words

Sat, 21 Jun 2025 20:55:00 GMT

Thinking in React

In an era dominated by AI agents and vibecoding, mastering the fundamentals has never been more important. That’s why I created my own version of Thinking in React and the Tic Tac Toe tutorial - shorter, easier, with Typescript and slot machines.

Find my code here

The “Minimal State” Principle

There’s a core idea in Thinking in React that’s both crucial and often misunderstood: Find the minimal but complete representation of UI state. Everyone agrees with this in principle, yet I see many developers struggling in practice.

Let’s look at an example. Suppose you want a User type with birthDate and age:

type User = {
  birthDate: string,
  age: number
}

You might write:

const user: User = {
  birthDate: "2022/11/21",
  age: 2
}

This is incorrect. The problem is that birthDate and age must stay in sync — and that’s fragile..

A Better Approach

Instead, compute age from birthDate:

function ageFromDate(dateString: string){
    const birth = new Date(dateString);
    const today = new Date();
    
    let age = today.getFullYear() - birth.getFullYear();
    const monthDiff = today.getMonth() - birth.getMonth();
    
    // Adjust age if birthday hasn't occurred this year yet
    if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birth.getDate())) {
      age--;
    }
    
    return age;
}

const person = {
  birthDate: "2022/11/21",
  
  get age(): number {
    return ageFromDate(this.birthDate)
  }
};

💡 If you’re not familiar with JavaScript getters, check them out here.

You could write an OOP version of this, but the point is clear: age should not be stored — it’s derived from birthDate.

The React Tic Tac Toe Challenge

Now that we understand minimal state, let’s bring that into React.

Where do you store state in React? If you’re not using an external state manager, you use the useState hook.

Here’s the challenge:
How many useState hooks do you need to implement Tic Tac Toe?

The answer: Only one — and not the one you’re probably thinking.

🧠 For a more patient explanation, check out the full Tic Tac Toe tutorial from the React documentation.

Here it is:

  const initialMovesHistory: Move[] = [];
  const [movesHistory, setMoveHistory] = useState(initialMovesHistory);

That’s it! The only state you need is the history of moves for the current game.
Check the code here (open App.tsx) and see the magic in action.

Defining Types

Here’s what we’re working with:

type Player = 'x' | 'o';
type Move = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 ;
type GameHistory = Move[];

A Player can be 'x' or 'o'. Nothing to see here.
A Move is just a grid index (0–8).
A GameHistory is a list of moves.

But Who Made the Move?

You might wonder:

Why am I not storing the player in the Move?

Because you can derive it. If 'x' always starts first, then:

Even-indexed moves in the history (0, 2, 4, …) belong to 'x'.
Odd-indexed moves (1, 3, 5, …) belong to 'o'.

function getPlayerFromMoveIndex(movesHistoryLength: number): Player {
  return movesHistoryLength % 2 === 0 ? 'x' : 'o';
}

Determining Game Status

The next derived value is the game status. Here’s how:

const winningCombinations: Move[][] = [
  [0, 1, 2],
  [3, 4, 5],
  [6, 7, 8],
  [0, 4, 8],
  [2, 4, 6],
  [0, 3, 6],
  [1, 4, 7],
  [2, 5, 8],
] as const;

type GameStatus =
  | {
      status: 'inprogress';
      player: Player;
    }
  | {
      status: 'ended:tie';
    }
  | {
      status: 'ended:won';
      player: Player;
    };

function gameStatus(movesHistory: GameHistory): GameStatus {
  const hlen = movesHistory.length;
  for (const [a, b, c] of winningComps) {
    const aPlayer = getPlayerForSquare(a, movesHistory);
    if (aPlayer) {
      const bPlayer = getPlayerForSquare(b, movesHistory);
      const cPlayer = getPlayerForSquare(c, movesHistory);
      if (aPlayer == bPlayer && bPlayer === cPlayer) {
        return {
          status: 'ended:won',
          player: aPlayer,
        };
      }
    }
  }

  if (hlen >= GRID_SIZE) {
    return {
      status: 'ended:tie',
    };
  }
  return {
    status: 'inprogress',
    player: getPlayerFromMoveIndex(hlen),
  };
}

From just the movesHistory and a set of winningCombinations, you can fully determine:

Whether the game is still in progress.
If it ended in a tie.
If someone won — and who they are.

That’s All, Folks!

Everything else is glue code and some CSS. Again, check the full code here if you’re curious.

A Note on Performance

You might be concerned about performance — but in most real apps, bottlenecks come from side effects like:

HTTP requests
Local storage access
Expensive re-renders

Don’t prematurely optimize.

🧙 Want to become a React performance wizard?

Make sure you understand React’s compiler and memoization first.

Loose Types Make Your Code Verbose — Type Narrowing to the Rescue!

Thu, 12 Jun 2025 15:19:00 GMT

Loose Types Make Your Code Verbose — Type Narrowing to the Rescue!

TypeScript’s type system isn’t strictly safe by default — and that was likely a conscious decision to make it more accessible to JavaScript developers. This flexibility helped drive adoption in the JS community. But as TypeScript gained popularity, it also attracted developers from other languages. As a result, the community now includes both developers who aren’t used to static types, and others who don’t fully understand JavaScript’s quirks. That mix has led to a lot of confusion about how types should actually be used in TypeScript.

TL;DR Version

If you don’t have time, here is what you are gonna learn:

When you are defining your types, follow these rules:

❌ Avoid any at any cost; prefer unknown
❌ If you need an object type, avoid object.
✅ Use Instead Record<string, MyUnion>and make the union as strict as possible.
✅ With properly typed data, optional chaining (?.) will usually be all you need.

The `User` Object: Starting Simple

Here’s a pattern I’ve seen many times in real-world code. Imagine we have a basic User object that allows arbitrary data. let’s say you want to get the user.data.role property from your user. Ideally, if you know what is the optional chaining (the ?. operator) you would expect that you could do something like const role = user?.data?.role and eventually assign undefined if something in this chain does not exist.

At first glance, data?: any feels like the simplest way to allow any shape of object… but it silently disables all checks

so the type would be:

type User = {
  id: string;
  name: string;
  data?: any;
};

const user:User = {
    id:"1",
    name:"user1",
}

console.log(user.data.role)

Try this example on TS Playground

your compiler will be happy, but you will get an error at runtime.

The compiler is happy because typing properties with any does not mean only accept “any value”, in reality any means "accept any value" AND "disable the typecheck for this property".

Now if you are an old-school js developer, you know that the js, has many dynamic languages, is based on Duck Typing. In a nutshell, if you are too lazy to read wikipedia, duck typing means you got to write a bunch of checks at runtime if object properties exists. This force you to write repetitive, defensive checks, and if you are not an experienced javascript developer, probably you don’t even know what to check exactly.

It is my belief that any was one of the major weapons to convince js developers to move to typescript. But in 2025 any still exists in typescript mainly for retrocompatibility reasons (and any linter discourages you to use it)

`unknown` to the Rescue

If you think you should use any, it probably means you want to use unknown:

let’s see how this changes:

type User = {
  id: string;
  name: string;
  data?: unknown;
};

const user:User = {
    id:"1",
    name:"user1",
    data:{role: "user"}
}

if(user?.data && typeof user?.data ==="object" &&  "role" in user.data ) // you need to add this if or the compiler will not let you do it.
    console.log(user?.data?.role)

Try this example on TS Playground

Now, TypeScript forces you to check before use, that’s why the check is changed. Now it is safe, but it is super verbose. For this reason, I saw many developers preferring to use any and hoping to not be on call if this becomes an error in production.

✅ The check is still at runtime, but you can’t forget it anymore. The compiler has your back. Still very verbose indeed.

What About `object`?

Using object feels more descriptive, I mean, in js an object is that thing you define with {}, right? it is basically an hashmap, correct? It seems exactly what I need! Here is how your type would be:

type User = {
  id: string;
  name: string;
  data?: object;
};

if(user?.data  &&  "role" in user.data ) 
    console.log(user?.data.role)

A little better, but still too verbose. Also this is not particularly safe. In fact, this allows any value where typeof value === "object", which includes:

Arrays ([])
null
{}

That’s because typescript need to reflect what javascript do. In general, Not ideal for safe usage or good DX.

✅ Use `Record<string, unknown>`

The reality is that what you need is a record. Your key values are probably strings, and if you don’t know your values type, you can use unknown. Something like:

type User = {
  id: string;
  name: string;
  data?: Record<string, unknown>;
};

const user:User = {
    id:"1",
    name:"user1",
    data:{
      "role": "user"
    }
}

console.log(user.data?.role)

Check this on the Try this example on TS Playground

This enforces you to have data :

Must be a plain object
Keys must be strings

How you use it:

This is finally what we want!

Bonus tip

String is not the only type you can use for object keys in javascript and typescript. But if you don’t know what a symbol is, or why this is true in js: typeof [] === 'object', stick with Record<string, ...>.

Narrowing with Union Types

You can do better than this. You can also limit the types of values allowed inside data:

type User = {
  id: string;
  name: string;
  data: Record<string, string | number | boolean>;
};

const user:User = {
    id:"1",
    name:"user1",
    data:{
      "role": "user"
    }
}

console.log(user.data?.role)

Because you’ve already told TypeScript what values are possible, narrowing is straightforward and less error-prone.

Summary

Using narrow, well-defined types makes your code safer, reduces bugs, and dramatically improves your developer experience.

Want to dig deeper into advanced type guards or build custom ones for your library? Drop a comment — or better, share how you handle dynamic data with TypeScript!

Implementing a Node.js/Express Server Using MinIO for Image Uploads

Sat, 21 Sep 2024 15:19:00 GMT

Implementing a Node.js/Express Server Using MinIO for Image Uploads

What We’re Going to Do

In this article, we’ll set up a Node.js server using Express and MinIO for image uploads and downloads. Is gonna be fully functional locally without requiring any AWS credentials. Our server will have two key features:

Generate Pre-signed URLs:
- Endpoint: http://localhost:3000/api/urls/:key
- This will generate PUT and GET pre-signed URLs for securely uploading and downloading files from MinIO without exposing credentials. the put url could be used by any http client to upload an image
Upload an Image from a URL:
- Endpoint: /api/uploads/url?url=imageUrl&key=keyName
- This will download an image from a given URL, upload it to MinIO with a specified key, and return a public URL to access the image.

We’ll deploy MinIO locally using Docker Compose and implement the server using Node.js, express, Axios and the AWS Typescript SDK (this last one will be configured to use minio instead of s3 in the backend).

For the Impatient

If you want to dive right in, you can find the complete working code in the repository below. Follow the instructions in the README to get started:

👉 https://github.com/jurgob/s3-test-minio

Introduction to S3, MinIO and Pre-signed URLs

Amazon S3 and Minio

Amazon S3 (Simple Storage Service) is a popular cloud storage solution that allows you to store and retrieve large amounts of data. It’s often used for file uploads, backups, and serving static content. However, S3 itself is a closed-source service, making it challenging to test locally without using the cloud.

To address this issue, we can use MinIO, an open-source, S3-compatible storage solution that can be run locally. MinIO enables developers to simulate S3 interactions without needing an internet connection or an AWS account. You can use MinIO through the official AWS s3 sdk just chaning the service url to point at the Minio url.

Pre-signed URLs?

Pre-signed URLs are secure, time-limited links that allow you to perform specific actions (like uploading or downloading files) without exposing your credentials. They are commonly used in scenarios where direct access to S3 (or a compatible service like MinIO) is required, but security is a concern.

Why do you need them?

Example: PUT Pre-signed URL

A PUT pre-signed URL allows you to upload a file directly to S3 (or MinIO) without needing credentials on the client-side.

# Example PUT request with a pre-signed URL
PUT https://bucketname.s3.amazonaws.com/yourkey?X-Amz-Expires=600&... # your presigned url

Headers:
Content-Type: image/jpeg
Content-Lenght: {fileSize}

Body: 
{the image content in binary format}

check the uploadStream() function defined below to see how to do it with axios.

Why Are Pre-signed URLs Needed?

Pre-signed URLs are essential for securely uploading and downloading files directly to cloud storage (like S3 or MinIO) without putting your backend in the middle of the process.

Managing file upload on the backend side is much harder then what you may thig, so Instead of routing large file uploads through your server, pre-signed URLs let clients upload files directly to storage (usually hosted by AWS), reducing [your] server load and improving efficiency. The URLs are temporary and grant limited access to specific files, ensuring security while allowing clients to upload or download files without exposing your credentials.

Architecture Quick Overview

Node.js Server (Express): Handles the API logic, generates pre-signed URLs, and uploads images to MinIO.
A set of docker compose services including:
- minio: MinIO is a high-performance, self-hosted object storage service that is fully compatible with Amazon S3 APIs. It allows you to store large amounts of unstructured data (like images, videos, backups).
- createbuckets: a script to do the initial setup of minio
npm run dev: this npm script will spin up both the nodejs server and the docker compose. Is gonna be the only thing you need to run to make the server work.

Setting up the server dependencies with docker compose

First, let’s set up our MinIO instance. We’ll be using Docker to run MinIO locally, and Docker Compose will make this process seamless.

Create a docker-compose.yml file with the following content:

version: '3.8'

services:
  minio:
    image: minio/minio
    container_name: minio
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      - MINIO_ROOT_USER=minio_username
      - MINIO_ROOT_PASSWORD=minio_password
    volumes:
      - /tmp/mino_data:/data
    command: server /data --console-address ":9001"

  createbuckets:
    image: minio/mc
    depends_on:
      - minio
    entrypoint: >
      /bin/sh -c "
      /usr/bin/mc alias set myminio http://minio:9000 minio_username minio_password;
      /usr/bin/mc mb myminio/miniobucket;
      /usr/bin/mc policy set public myminio/miniobucket;
      exit 0;
      "

if you run this with npm run dev:server and you navigate to http://localhost:9001. you should see the minio dashboard. you can login using minio_username as username and minio_password as password

you can now run npm run cli and see an image upload in your system.

Explaining the Docker Compose File

This docker-compose.yml file is designed to run a local MinIO instance and automatically create a bucket with public access. Here’s a breakdown of what each section does:

version: '3.8': Specifies the version of Docker Compose being used.

services:: Defines the services (containers) that Docker will run.

minio:

Image: Uses the official minio/minio image to run MinIO.
Container Name: Names the container minio.
Ports:
- Maps port 9000 on the host to 9000 on the container for the MinIO API.
- Maps port 9001 on the host to 9001 on the container for the MinIO web console.
Environment Variables: Sets up the root credentials for accessing MinIO:
- MINIO_ROOT_USER: Sets the username.
- MINIO_ROOT_PASSWORD: Sets the password.
Volumes: Mounts /tmp/mino_data on the host to /data inside the container, ensuring that data persists locally.
Command: Starts MinIO in server mode, storing data in /data and running the web console on port 9001.

createbuckets:

Image: Uses the minio/mc image (MinIO client) to manage the MinIO instance.
depends_on: Ensures that this service runs only after the minio container is up and running.
Entrypoint: Runs a shell script to:

Set up an alias (myminio) pointing to the MinIO instance at http://minio:9000 with the credentials.
Create a new bucket named miniobucket.
Set the bucket’s policy to public, allowing anyone to access objects in the bucket.
Exit the script after the setup.

This setup ensures MinIO starts, creates a bucket, and configures it for public access automatically.

Creating the Node.js server

There are gonna be 2 files:

src/index.ts -> this is contain the really intresting part. it’s were we are gonna use the offical aws s3 sdk, configure it to point at our loca minio, we are gonna use it to create presigned urls and we are gonna use axios to both download images and to upload images into minio.
src/server.ts -> this will containt the server endpoints definition

Understanding: `src/index.ts`

The index.ts file is responsible for interacting with MinIO by generating pre-signed URLs and uploading files via streams. Let’s break it down:

1. Setting Up MinIO Client

const s3Client = new S3Client({ 
    region: "REGION",
    credentials: {
        accessKeyId: "minio_username",
        secretAccessKey: "minio_password",
    }, 
    endpoint: "http://127.0.0.1:9000",
});

A MinIO client is created using AWS SDK’s S3Client.
The credentials (accessKeyId and secretAccessKey) are set to the values defined in the Docker Compose file (minio_username and minio_password).
The endpoint points to the local MinIO instance running on localhost:9000.

2. Generating Pre-signed URLs

xport const generatePresignedUrl = async (objectKey: string, cmd : "get"| "put"): Promise<string> => {
    const bucketName: string = "miniobucket";
    if (!["get", "put"].includes(cmd)){
        throw "unkdonw cmd option"
    }
    let CmdObj = cmd === "put" ? PutObjectCommand : GetObjectCommand

    const commandOptions = {
        Bucket: bucketName,
        Key: objectKey,
      }

    const command = cmd === "put" 
        ? new PutObjectCommand(commandOptions) 
        : new GetObjectCommand(commandOptions) 
        
    try {
      const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 600 });
      console.log("Presigned URL:", presignedUrl);
      return presignedUrl;
    } catch (err) {
      console.error("Error generating presigned URL:", err);
      throw err;
    }
  };

This function generates pre-signed URLs for either uploading (PUT) or downloading (GET) a file from MinIO.
The URL is generated using the AWS SDK’s getSignedUrl function and is valid for 600 seconds (10 minutes).
The pre-signed URL is a secure, temporary URL that allows users to interact with a specific object (file) without needing credentials.

4. Uploading a Stream to MinIO

export const uploadStream = async (presignedUrl: string, readStream: Readable, contentLength: string, contentType: string): Promise<void> => {
    try {
        const response = await axios.put(presignedUrl, readStream, {
            headers: {
                'Content-Type': contentType,
                'Content-Length': contentLength,
            },
        });
    } catch (error: any) {
        throw error;
    }
};

This function uploads a stream (e.g., an image file) to MinIO using a PUT pre-signed URL.
Axios is used to send a PUT request with the stream and required headers:
- Content-Type: The MIME type (e.g., image/jpeg).
- Content-Length: The size of the image.

If the request is successful, the image will be stored in the MinIO bucket, accessible via the GET pre-signed URL.

Key Takeaways

Pre-signed URLs enable secure, time-limited access to specific files in MinIO.
The server uploads files by sending streams (image data) using a pre-signed PUT URL.
Axios handles both generating and uploading streams, while the AWS SDK is used to interact with MinIO.

The complete `src/index.ts` file:

import axios from "axios";
import {createReadStream,statSync} from "fs";
import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { stat} from "fs/promises";
import { Readable } from "node:stream";

const s3Client = new S3Client({ 
    region: "REGION",
    credentials: {
        accessKeyId: "minio_username",
        secretAccessKey: "minio_password",
    }, 
    endpoint: "http://127.0.0.1:9000",
});

export const generatePresignedUrl = async (objectKey: string, cmd : "get"| "put"): Promise<string> => {
    const bucketName: string = "miniobucket";
    if (!["get", "put"].includes(cmd)){
        throw "unkdonw cmd option"
    }
    let CmdObj = cmd === "put" ? PutObjectCommand : GetObjectCommand

    const commandOptions = {
        Bucket: bucketName,
        Key: objectKey,
      }

    const command = cmd === "put" 
        ? new PutObjectCommand(commandOptions) 
        : new GetObjectCommand(commandOptions) 
        
    try {
      const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 600 });
      console.log("Presigned URL:", presignedUrl);
      return presignedUrl;
    } catch (err) {
      console.error("Error generating presigned URL:", err);
      throw err;
    }
  };


export  const uploadFileWithPresignedUrl = async (presignedUrl: string, filePath: string): Promise<void> => {
    const fileStream = createReadStream(filePath);
    const fileStats = await stat(filePath);

    await uploadStream(presignedUrl, fileStream, fileStats.size.toString(), "image/jpeg")

};

export  const uploadStream = async (presignedUrl: string, readStream: Readable, contentLength: string, contentType: string): Promise<void> => {
  try {
    const response = await axios.put(presignedUrl, readStream, {
      headers: {
        'Content-Type': "image/jpeg",
        'Content-Length': contentLength,
      },
    });
  
  } catch (error:any ) {
      console.error("ERROR UPLOADING THE IMAGE:")
      if (error.response) {
          console.error(error.response?.data)
          return 
      }else{
          console.log(error)
      }
      throw error;
  }
};

Understanding `src/server.ts`

This Node.js server built with Express provides an API to download an image from a given URL, upload it to MinIO, and return a pre-signed GET URL for retrieval. Here’s how the image download and upload process works.

Endpoint: `/api/uploads/images`

This route handles the logic for downloading an image from a given URL and uploading it to MinIO.

app.get('/api/uploads/images', async (req: Request, res: Response) => {
    
    try{
        const { url , key} = req.query;
        console.log({ url , key})
        if (!url || typeof url !== 'string') {
            throw {
                status: 400,
                message: 'The url query parameter is required',
                example: '/api/uploads/images?key=example&url=https://example.com/image.jpg'
            } as HTTPError;
            throw new Error('The imageUrl query parameter is required');
        }
        if (!key || typeof key !== 'string') {
            throw {
                status: 400,
                message: 'The key query parameter is required',
                example: '/api/uploads/images?key=example&url=https://example.com/image.jpg'
            } as HTTPError;
        }

        const [put, get] = await Promise.all([
            generatePresignedUrl(key, "put"),
            generatePresignedUrl(key, "get"),
        ])
        
        // download the content of the imageUrl param and put it in a readable stream. check the content type is an image. retrive the content length and put it in a variable
        const response = await axios.get(url, { responseType: 'stream' });
        const contentType = response.headers['content-type'];
        const contentLength = parseInt(response.headers['content-length'], 10);

        if (!contentType.startsWith('image/')) {
            throw new Error('The URL does not point to an image');
        }
        const imageStream = response.data as Readable;
        await uploadStream(put, imageStream, contentLength.toString(), contentType);


        res.json({
            key,
            contentType,
            contentLength,
            imageUrl: url,
            getUrl: get
        });

    }catch(e){
        httpError(res, e)
    }
});

1. Get Query Parameters:

url: The URL of the image to download. key: The unique key externally provied (name) for the file in MinIO. The server validates that both the url and key parameters are provided.

2. Generating Pre-signed URLs

const [put, get] = await Promise.all([
    generatePresignedUrl(key, "put"),
    generatePresignedUrl(key, "get"),
]);

PUT Pre-signed URL: Used to upload the image to MinIO.
GET Pre-signed URL: Generated for retrieving the image after upload.

These URLs are generated using the generatePresignedUrl function, which communicates with MinIO to create temporary access URLs for uploading and downloading files.

3. Downloading the Image

const response = await axios.get(url, { responseType: 'stream' });
const contentType = response.headers['content-type'];
const contentLength = parseInt(response.headers['content-length'], 10);

if (!contentType.startsWith('image/')) {
    throw new Error('The URL does not point to an image');
}

Image Download: The server uses Axios to download the image from the provided url. It requests the image as a stream (responseType: 'stream'), making it easier to handle large files without loading the entire file into memory.
Headers:
- contentType: The MIME type of the image, ensuring it is a valid image format.
- contentLength: The size of the image file.

The server checks if the downloaded file is an image by verifying if the content-type starts with “image/“.

4. Uploading the Image to MinIO

const imageStream = response.data as Readable;
await uploadStream(put, imageStream, contentLength.toString(), contentType);

Stream Upload: The server takes the downloaded image (which is a readable stream) and uploads it to MinIO using the PUT pre-signed URL.
The uploadStream function handles the actual file upload:
Headers:
- Content-Type: Set to the downloaded image’s MIME type.
- Content-Length: Set to the size of the image.

This ensures that the image is uploaded in the correct format and size.

5. Response to Client

res.json({
    key,
    contentType,
    contentLength,
    imageUrl: url,
    getUrl: get
});

After the image is successfully uploaded, the server responds with:

key: The unique key (name) under which the image was saved in MinIO.
contentType: The MIME type of the image.
contentLength: The size of the image.
imageUrl: The original URL from which the image was downloaded.
getUrl: A pre-signed GET URL that allows the user to download the image from MinIO.

Endpoint: `/api/urls/:key`

This is the entire endpoint code; it is quite self-explanatory at this point:

app.get('/api/urls/:key', async (req: Request, res: Response) => {
    try{
        const {key} = req.params;
        const [put, get] = await Promise.all([
            generatePresignedUrl(key, "put"),
            generatePresignedUrl(key, "get"),
        ])

        res.json({
            put:put,
            get
        });

    }catch(e){
        httpError(res, e);
    }
});

The entire `scr/server.ts`:

import express, { Request, Response } from 'express';
import cors from 'cors';
import { generatePresignedUrl, uploadStream } from ".";
import axios from 'axios';
import { Readable } from 'stream';

const app = express();
type HTTPError = {
    status: number,
    message: string,
    example?: string
}
app.use(cors());
app.use(express.json());

app.get('/api/urls/:key', async (req: Request, res: Response) => {
    try{
        const {key} = req.params;
        const [put, get] = await Promise.all([
            generatePresignedUrl(key, "put"),
            generatePresignedUrl(key, "get"),
        ])

        res.json({
            put:put,
            get
        });

    }catch(e){
        httpError(res, e);
    }
});

// add an endpoit /api/upload/images/:key/:url which genereate a get presigned url and upload the image to the presigned url and return the get presigned url
app.get('/api/uploads/images', async (req: Request, res: Response) => {
    
    try{
        const { url , key} = req.query;
        console.log({ url , key})
        if (!url || typeof url !== 'string') {
            throw {
                status: 400,
                message: 'The url query parameter is required',
                example: '/api/uploads/images?key=example&url=https://example.com/image.jpg'
            } as HTTPError;
            throw new Error('The imageUrl query parameter is required');
        }
        if (!key || typeof key !== 'string') {
            throw {
                status: 400,
                message: 'The key query parameter is required',
                example: '/api/uploads/images?key=example&url=https://example.com/image.jpg'
            } as HTTPError;
        }

        const [put, get] = await Promise.all([
            generatePresignedUrl(key, "put"),
            generatePresignedUrl(key, "get"),
        ])
        
        // download the content of the imageUrl param and put it in a readable stream. check the content type is an image. retrive the content length and put it in a variable
        const response = await axios.get(url, { responseType: 'stream' });
        const contentType = response.headers['content-type'];
        const contentLength = parseInt(response.headers['content-length'], 10);

        if (!contentType.startsWith('image/')) {
            throw new Error('The URL does not point to an image');
        }
        const imageStream = response.data as Readable;
        await uploadStream(put, imageStream, contentLength.toString(), contentType);


        res.json({
            key,
            contentType,
            contentLength,
            imageUrl: url,
            getUrl: get
        });

    }catch(e){
        httpError(res, e)
    }
});

const httpError = (res: Response, err: unknown) => {
    console.error(`ERROR: `, err);
    if(err 
        && typeof err === "object" 
        && "status" in err
        && "message" in err
        && "example" in err){
        const _err = err as HTTPError;
        
        res.status(_err.status)
        return res.json({
            message: _err.message,
            example: _err.example, 
        });
    }else {
        res.status(500)
        return res.json({
            status: 500, 
            message: err?.toString()
        });
    }
};

// Start the server on port 3000
const PORT = 3000;
app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

Npm scripts:

is worth to mention how the npm scripts are working in this project.

{
  "name": "s3-test",
  ...
  "scripts": {
    "cli": "tsx src/cli.ts",
    "start:db": "docker compose up",
    "server": "tsx src/server.ts",
    "dev:server": "node --import=tsx --watch src/server.ts",
    "dev": "concurrently --kill-others=true 'npm run start:db' 'npm run dev:server' "
  },
  ...
  
}

dev: start the server and the docker compose using concurrently
start:db: docker copose
dev:server: spin up the node.js server with hotreloading
cli: run a test to upload the test.jpeg image in the asset directory

Conclusion

You’ve now successfully set up a Node.js server with MinIO for handling image uploads using pre-signed URLs. MinIO offers a cost-effective, self-hosted alternative to AWS S3 for object storage, and the use of pre-signed URLs allows clients to securely upload and retrieve files without exposing sensitive credentials.

For the complete code, visit the repository here and start building your own object storage solution locally with Node.js and MinIO.

Effortless Node.js Development with TypeScript: A Zero-Configuration Guide

Tue, 23 Jul 2024 16:37:00 GMT

This guide provides a straightforward approach to setting up a Node.js project with TypeScript, without the need for complex configurations. By taking advantage of the latest Node.js features like watch mode, the built-in test runner, and the assert library, this setup minimizes dependencies while ensuring a smooth and efficient development experience. Follow step-by-step instructions to initialize your project, integrate TypeScript, set up Git, and add testing capabilities. In this guide I wanted to minimize to depencencies you install and the configuration files you have to add in your project. If you are not doing Frontend you can go very far with a very simple scaffolding.

TLDR

for the more impatients, just here is the source code. Just go there and follow the README.

Scaffolding a Node.js Project with TypeScript with No Configuration

Creating a Node.js project with TypeScript without the hassle of complex configurations can be streamlined with the following steps. This guide walks you through setting up a boilerplate project that includes TypeScript support, automatic type checking, and testing.

Prerequisites

Before we start, install fnm (Fast Node Manager) and use it to install Node.js version 20:

fnm install v20.15.1

Initialize the Node.js Project

Create a new directory for your project and navigate into it:

mkdir boilerplate_node_typescript
cd boilerplate_node_typescript

Initialize a new Node.js project:
```
npm init
```
(Optional) If you are using fnm or nvm, set the Node.js version for the project:
```
node -v > .nvmrc
```
Now, every time you navigate into the project directory, the Node.js version will be set automatically.

Set Up Git

Initialize a new Git repository:
```
git init
```
Create a .gitignore file:
```
touch .gitignore
```
Add the following lines to .gitignore to exclude the node_modules and dist directories:
```
node_modules/*
dist/*
```

Install TypeScript

Install TypeScript and tsx (a tool for running TypeScript files directly):
```
npm i -D typescript tsx
```
Create a src directory and an entry file:
```
mkdir src
touch src/index.ts
```

Update `package.json`

Add the following scripts to your package.json file:

{
  "main": "dist/index.js",
  "scripts": {
    "dev": "node --import=tsx --watch --no-warnings src/index.ts",
    "build": "tsc src/index.ts --outDir dist",
    "typecheck": "tsc src/index.ts --noEmit",
    "typecheck:watch": "tsc src/index.ts --noEmit --watch",
    "start": "node dist/index.js"
  }
}

Add Some Code

Create a sum.ts file:
```
touch src/sum.ts
```

Add the following code to src/sum.ts:

export function sum(a: number, b: number): number {
  return a + b;
}

Update src/index.ts to use the sum function:

import { sum } from './sum';

console.log(sum(1, 2));

Run the development script to see your code in action:
```
npm run dev
```
This script will watch for changes and reload automatically.
You can also build and start the project:
```
npm run build
npm start
```

Add Type Checking

While tsx is great for development, it doesn’t report type errors. Use TypeScript’s tsc for type checking:

Add a typecheck script to package.json (already added above):

"scripts": {
  "typecheck": "tsc src/index.ts --noEmit",
  "typecheck:watch": "tsc src/index.ts --noEmit --watch"
}

Run the type checking script:
```
npm run typecheck
```

Add Tests

Install @types/node for TypeScript support in Node.js:
```
npm i -D @types/node
```
Create a test file:
```
touch src/sum.test.ts
```

Add the following code to src/sum.test.ts:

import { sum } from './sum';
import { test } from 'node:test';
import { strictEqual } from 'node:assert';

test('sum(1, 2) equals 3', () => {
  strictEqual(sum(1, 2), 3);
});

Add test scripts to package.json:

"scripts": {
  "test": "node --import=tsx --test src/**/*.test.ts",
  "test:watch": "node --import=tsx --test --watch src/**/*.test.ts"
}

Run the tests:
```
npm test
```

Work in a Reactive Environment

For an efficient development workflow, open three terminals and run:

Terminal 1: Development mode
```
npm run dev
```
Terminal 2: Type checking
```
npm run typecheck:watch
```
Terminal 3: Testing
```
npm run test:watch
```

You are done! This setup provides a simple and effective way to scaffold a Node.js project with TypeScript without any complex configuration. Enjoy coding!

Bonus: adding test coverage.

We can use tools like nyc to make our life much easier.

install nyc:

npm i -D nyc

then modify the package.json like this:

package.json

scripts: {
    ...
    "test": "nyc --reporter=html --reporter=text node  --import=tsx --test src/**/*.test.ts",
    ...,
    "coverage": "nyc report --reporter=text --reporter=text-summary",
    "coverage:html": "npx http-server coverage"
}

add to your .gitignore the following:

...
.nyc_output/*
coverage/*

now, if you run npm test, you will see some new information after the test run:

After you have runned the test, you will be able to print any time you want several report.

to run a text based report just run:

npm run coverage

you will see:

or you can run the html report with:

npm run coverage:html

now if you go at http://localhost:8000/ from your browser you will see in details the coverage file by file:

you can even click on a sigle file to check which part of your source code is not covered by your tests:

Exploring Utopian Testing Strategies for Node.js REST APIs

Thu, 07 Mar 2024 11:23:00 GMT

TLDR

Writing tests for Node.js REST APIs can be complex due to various challenges:

End-to-end (E2E) and integration/unit tests often differ despite overlapping.
E2E tests are slow and prone to flakiness.
Unit tests sometimes focus on implementation rather than architecture.
I/O operations, such as database access and spinning up APIs, make E2E tests slow.

Solutions like using express.listen(0) and in-memory databases can mitigate this issue. Additionally, a subset of these tests can be run periodically against live environments (that’s what in Vonage we were calling Smoke Tests).

Check out this Example Code of a Node.js api integrating this Utopian Testing Strategy

Let’s talk about testing

Let’s discuss some general concepts and problem about testing REST API

The Testing Problem

The testing landscape for Node.js REST APIs (and REST APIs in general) is fraught with challenges. E2E tests, essential for validating user scenarios, often suffer from slowness and fragility. Conversely, unit tests may not always capture architectural concerns and tend to be implementation-centric. Additionally, the diverse technologies involved in testing further compound the complexity. This is often exacerbated by a culture of siloing developers and SDET, and in general, a lack of consideration of the costs such an approach brings (slowing down refactoring/releases due to extensive test changes can significantly reduce overall quality more than the lack of test coverage).

Understanding The Testing Pyramid

The testing pyramid, with unit tests at the base, followed by integration tests and E2E tests at the apex, is a reflection of testing priorities. However, the pyramid shape also signifies the increasing “cost” associated with tests as we move towards the top. E2E tests, being more user-like, are costly to maintain and slow to execute. Moreover, parallelizing E2E tests can introduce complexities, such as dependencies between test cases.

Also often Integrated Tests and E2E tests tend to have great overlap but typically teams tend to not take benefit from this, typically because they are mantained by different teams and they are using different technologies (in my previus company we got the unit/integration tests in javascript and the e2e in python as instance).

Understanding Smoke Tests

Let me introduce the concept of Smoke Test, which is not very well defined across the industry, but in Vonage it had a very specific meaning. “Smoke tests” refer to periodic E2E tests that validate essential functionalities of the application. These tests are typically run at regular intervals, providing a quick check on the system’s health. By prioritizing critical paths, smoke tests offer a balance between efficiency and coverage, complementing the broader testing strategy. In your tests Testing Pyramid this would be a new level at the apex.

An Utopian Testing Strategy Proposal.

It would be great if you could write the tests once and run them both against your real API and on an in-memory version of your API. Let’s do that:

Configuring your app

here is our rest api (and testing) configuration:

import { z } from 'zod'

const envSchema = z.object({
    PORT: z.coerce.number().min(1000).default(3000),
    TEST_API_URL: z.string().url().optional(),//if empty, the test will use an inmemory-mock server
    MONGO_URL: z.string().url().optional(),// if empty, the express server will use an inmemory-mock mongodb version
    MONGO_DB_NAME: z.string().max(50).optional(),
});

const env = envSchema.parse(process.env)

console.log(`NODE_ENV: `,process.env.NODE_ENV);
console.log(`TEST_API_URL: `,env.TEST_API_URL);

export default env

I think this is self explenatory

Giving your api the ability to run with an inmemory MongoDB

I chose MongoDB for simplicity; this can work with every type of DB that has an in-memory version (as far as I know, Postgres and CouchDB have that). Here is what the dbClient looks like:

Having a dedicated rest api

Assuming I’ve implemented a createApp function which returns an Express app, I can create a test utility:

import {createApp} from '../server';
import { Server } from "http";

import { AddressInfo } from 'node:net';
import env from '../env';
export async function createMockServer() {
    let server:Server|undefined = undefined
    let intUrl = undefined
    if(!env.TEST_API_URL){
        const app = await createApp()
        server = app.listen(0); // this will open the server on a random ephimeral port
        const address = server.address() as AddressInfo;
        server.on('close', () => {
            app.emit('close');
        });
        intUrl = `http://localhost:${address.port}`
    }else {
        intUrl = env.TEST_API_URL
    }
    
    const url: string = intUrl
    return {
        url,
        close: () => {
            if(server)
                server.close()
        }
    }
}

Basically, if the TEST_API_URL environment variable is not set, it will create a mock server and return the URL. The close() function needs to be called at the end of your test. If you are setting TEST_API_URL, then this function will just return that, and the close() function will not do anything.

Here is how a test looks like:

test('endpoint /users', async () => assert.doesNotReject(async () => {
    const {url,close } = await createMockServer();
    const res = await axios({
        baseURL: `${url}`,
        url: '/users',
        method: 'post',
        data: {
            name: 'test',
            email: 'test@email.com',   
        }
    });
    const {_id, ...data} = res.data;

    assert.deepStrictEqual(res.status, 201, 'Unexpected status code from POST /users endpoint');
    assert.deepEqual(data, {
        name: 'test',
        email: 'test@email.com',
    }, 'Unexpected response from POST /users endpoint');
    assert.ok(_id, 'Expected _id to be defined');

    close();
}));

Using an in-memory version of your db

Similarly to the REST API, inside the dbClient, you can check if the MONGO_URL is set. If not, you will use the in-memory version (so every “ephemeral API” will have a dedicated in-memory DB):

import {MongoClient} from 'mongodb';
import { MongoMemoryServer } from 'mongodb-memory-server';
import env from './env';
type User= {
  name: string;
  email: string;
}
export async function  createDBClient(){
  let mongoServer:MongoMemoryServer|undefined =undefined;
  let mongo_db_name: string| undefined = undefined;
  let mongo_url: string| undefined = undefined;
  if(!env.MONGO_URL){
    mongoServer = await MongoMemoryServer.create()
    mongo_db_name = `db_${Math.random().toString(36).substring(7)}`;
    mongo_url = mongoServer.getUri()+`  /${mongo_db_name}`
  }else {
    if(!env.MONGO_DB_NAME){
      throw new Error('MONGO_DB_NAME is required when using a real mongodb server (aka when MONGO_URL is defined)');
    }
    mongo_url = `${env.MONGO_URL}/${env.MONGO_DB_NAME}`;
    mongo_db_name = env.MONGO_DB_NAME;
  }  
  const db = new MongoClient(mongo_url);
  const collectionUsers = db.db(mongo_db_name).collection<User>('users');
  const disconnect = async () => {
    await db.close();   
    if(mongoServer)
      await mongoServer.stop();
  }
  const createUser = async (user:User) => {
    const {insertedId} = await collectionUsers.insertOne(user);
    const newUser = await collectionUsers.findOne({_id: insertedId});
    return newUser;
    
  }
  return {
    disconnect,
    createUser
  }
}

how to run this

Here is the script section of your package.json file:

    {
        // the rest of your package.json file config....
        "script": {
            "dev": "tsx watch --env-file=.env src/index.ts",
            "test": "node --env-file=.env.test  --import tsx --test src/**/*.test.ts",
            "test:smoke:createuser": "node --env-file=.env.test.smokes  --import tsx --test src/test_e2e/createuser.smoke.test.ts",
            "test:w": "node --env-file=.env.test --import tsx --test --watch  src/**/*.test.ts",
        }
    }

Here is the content of the .env files (this is used to run the REST API, I’m spinning up MongoDB with Docker locally. Check the example readme):

PORT=3000
MONGO_URL=mongodb://root:secret@localhost:27017
MONGO_DB_NAME=admin%

here is the content of the .env.test files:

# this is empty!

here is the content of the .env.test.smokes files ( I just need to set the TEST_API_URL):

TEST_API_URL="http://localhost:3000"

Why I call this “Utopian”

First of all, even if I called this “Utopian”, it does not solve all the problems. Testing race conditions is one such issue. (Even though if you attach stats on your smoke tests, it can give you some indication of those.) But if you could write just one type of test, it should be this one.

What you should keep in mind is that testing is just one factor of quality; others include metrics, alerts, type systems, linters (if you believe in them), and software design.

Anyway, I call this a “Utopia” because it is very difficult to achieve. Typical problems include:

Not all frameworks of Node.js support listening to ephemeral ports.
Not all databases provide an in-memory version.
You may have external dependencies that are very complicated to mock.

Conclusion

Achieving high-quality software involves a delicate balance between various factors, including code quality, test coverage, duplication of effort, metrics, mean time to recovery (MTTR), and refactoring time. By adopting utopian testing strategies, such as incorporating smoke tests, re-evaluating the testing pyramid, and optimizing test execution, developers can navigate the complexities of testing Node.js REST APIs more effectively. This approach fosters meaningful insights, driving continuous improvement and enhancing overall software quality. Check out this Example Code of a Node.js API integrating this Utopian Testing Strategy

Exhaustive Pattern Matching in TypeScript

Sun, 03 Mar 2024 20:27:00 GMT

Pattern matching is a powerful programming construct that allows developers to match values against a series of patterns and execute code based on the matched pattern. Exhaustive pattern matching ensures that all possible cases are handled, leaving no room for unintended behavior. In this article, we’ll explore exhaustive pattern matching in TypeScript, its importance, and various techniques to achieve it.

Why Exhaustive Pattern Matching?

Exhaustive pattern matching is crucial for writing robust and maintainable code. By ensuring that all possible cases are handled, it helps prevent unexpected runtime errors and makes code more predictable and easier to reason about.

Let’s start with an example in Rust to illustrate the concept:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u32 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

In this Rust code, the match expression guarantees exhaustive pattern matching for the Coin enum. Each variant is handled explicitly, leaving no possibility of unhandled cases.

Try to remove some of the match in the value_in_cents function in the rust playground, you will get an error at compile time.

Exhaustive Pattern Matching in TypeScript

Rust kind of force you to into the Exhaustive Pattern Matching. Typescript does not. So, if you are a Typescript developer who has never heard of this concept, you may implement the code above in this way:

type Coin = "Penny" | "Nickel" | "Dime" | "Quarter";

function valueInCents(coin: Coin): number {
    switch (coin) {
        case "Penny":
            return 1;
        case "Nickel":
            return 5;
        case "Dime":
            return 10;
        case "Quarter":
            return 25;
        default:
            return 0
    }
}

Check this on the TS Playground

Do you see the problem? If you forget to manage a case, the compiler will not help you. If tomorrow, there’s a new type of Coin, the compiler will not tell you that you have to update the valueInCents function.

(p.s. if you are asking yourself why I didn’t use an enum , it’s because in Typescript enum are not type-safe.

In TypeScript, achieving exhaustive pattern matching involves leveraging the never type. By using never, TypeScript ensures that a function or switch statement covers all possible input types or values.

Enter the `never`

What does the never keyword do?. In TypeScript, the never keyword represents the type of values that never occur. When a function has a return type of never, it means that the function never returns normally and either throws an error or enters an infinite loop. never is a useful tool for making TypeScript code more robust and ensuring that all possible cases are handled. Read more about it in the official TS docs or go even more deep here.

Using `never` in Functions

Here is how we can implement the example we did in Rust using never:

type Coin = "Penny" | "Nickel" | "Dime" | "Quarter";

function valueInCents(coin: Coin): number {
    switch (coin) {
        case "Penny":
            return 1;
        case "Nickel":
            return 5;
        case "Dime":
            return 10;
        case "Quarter":
            return 25;
        default:
            return 0 as never
    }
}

In this function, if a new Coin type is introduced in the future, TypeScript ensures that we handle it explicitly by assigning it to a variable of type never (which will give a compile error). This guarantees exhaustive pattern matching.

Try to add a value to the Coin union or to remove a case in the switch on the typescript background, you will see the compiler complaining.

Using `never` in Switch Statements

Similarly, we can achieve exhaustive pattern matching using never in switch statements:

type Coin = "Penny" | "Nickel" | "Dime" | "Quarter";

function myFunction(coin: Coin): void {
    
    let value = 0;
    switch (coin) {
        case "Penny":
            value= 1;
            break;
        case "Nickel":
            value= 5;
            break;
        case "Dime":
            value= 10;
            break;
        case "Quarter":
            value= 25;
            break;
        default:
            value = 0 as never
    }
}

This will also return an error in case you forget a break.

Try to remove a break in the typescript playground.

Error handling.

You may have noticed that in the default branch, which in theory is never reached, I’m returning a 0. The reason is that Typescript is not a very safe/strict type system (and this is by design), so you can always end up having unexpected value. It can be because you are parsing the information from a network request, cli input, file, etc… and your parser is not very strict. Or it can be just because you have just used as Coin like this:

type Coin = "Penny" | "Nickel" | "Dime" | "Quarter";

function valueInCents(coin: Coin): number {
    switch (coin) {
        case "Penny":
            return 1;
        case "Nickel":
            return 5;
        case "Dime":
            return 10;
        case "Quarter":
            return 25;
        default:
            return 0 as never
    }
}

const value = valueInCents("CoinNotValid" as Coin) // thh compiler will be happy. value is gonna be 0

aka: if I have passed an invalid coin, the value in cent is 0. you may instead want to be more explicit in the error handling and delegate it to the caller of the valueInCent function. you could throw an Error like this:

type Coin = "Penny" | "Nickel" | "Dime" | "Quarter";

function valueInCents(coin: Coin): number {
    switch (coin) {
        case "Penny":
            return 1;
        case "Nickel":
            return 5;
        case "Dime":
            return 10;
        case "Quarter":
            return 25;
        default:
            throw Error("hello") as never;
    }
}

valueInCents("CoinNotValid" as Coin)

Or you could return undefined. If you go this way, you should change the signature of the function to return number | undefined The Compiler does not force you, but in this way you will force whoever is using the function to manage undefined. Obviously I’m assuming you are working with "strict": true in your complier option

the could would look like this:

type Coin = "Penny" | "Nickel" | "Dime" | "Quarter";

function valueInCents(coin: Coin): number|undefined {
    switch (coin) {
        case "Penny":
            return 1;
        case "Nickel":
            return 5;
        case "Dime":
            return 10;
        case "Quarter":
            return 25;
        default:
            return undefined as never;
    }
}

const res:number = valueInCents("CoinNotValid" as Coin)  || 0 //the complier force you to manage the case is undefined

Go to the typescript playground and try to remove the || 0. the compiler will complain. Try to remove also the |undefined from the signature, now the compiler will be happy. Unluckily it is gonna be up to you to be disciplined.

Alternatives

While using never for exhaustive pattern matching is effective, there are alternative approaches available in the TypeScript ecosystem:

ts-pattern Library

The ts-pattern library provides a powerful pattern matching syntax for TypeScript:

import { match, isMatching } from "ts-pattern";

const Coin = ["Penny", "Nickel", "Dime", "Quarter"] as const;
type Coin = (typeof Coin)[number];

function valueInCents(coin: Coin) {
  if (!isMatching(Coin, coin)) return undefined;
  return match<Coin>(coin)
    .with("Penny", () => 1)
    .with("Nickel", () => 5)
    .with("Dime", () => 10)
    .with("Quarter", () => 25)
    .exhaustive();
}

const res: number = valueInCents("CoinNotValid" as Coin) || 0;
console.log(res);

Check how the complier works on TS Playground, to make it run you will need to export it to CodeSandbox (check the export menu in the TS Playground).

note: I’m not an expert of the ts-pattern library, it is possible there’s a better way to write this.

ECMAScript Pattern Matching Proposal

The ECMAScript Pattern Matching proposal introduces native pattern matching syntax to JavaScript and TypeScript. While still a proposal, it shows promise for simplifying pattern matching in TypeScript in the future.

Conclusion

Exhaustive pattern matching is a valuable technique for writing reliable and maintainable code. By leveraging TypeScript’s type system and features like never, developers can ensure that all possible cases are handled, leading to more robust software. Additionally, with libraries like ts-pattern and upcoming language features, pattern matching in TypeScript is becoming even more expressive and convenient. Anyway, My personal opinion is that the pattern matching in typescript right now, in terms of ergonomics, is very far from the one you got in languages like Rust. Such a fundamental things should be part of the language, so I’m really looking forward for the pattern matching proposal. But don’t wait for it, us it now! with ts-pattern or with never.

My journey in the React world

Fri, 01 Apr 2022 22:19:00 GMT

Why I’m writing this

In this article I’m gonna tell you how I’ve discovered React. It was an exciting journey, becouse At the first I didn’t get react, then I started to understand a series of concept that made me a better developer overall, not only a better js / frontend guy.

Who am I

I started my careed in my own start up doing Google GWT, then for 4 years I did mobile websites targetting even very old mobile phones thus having an interface working without JS was a must. In this period I also did a geolocated chat using Angular.js as a freelancer.

Then I change my job and for 2 years I worked with mustache and React.

Then 5 years ago I change completly my career and I became a backend developer, since then I follow react as an hobbist and I use it mainly for doing small POC around our APIs.

Who should read this?

Any JS developer could read this, but I feel that someone who is not familiar with React and its ecosystem would just be a little overwhealmed by the ammount of things I’m talking about and would not benefit too much with this.

Why you should read this

By telling you my story I would like you to understand that getting a new framework takes time, you don’t get it all in 5 min (or at least I don’t).

By giving some “historical” context of how was the frontend world when React came out, I hope to highlinght why React was a big thing back then.

In the end I hope I will give a brief reacap of all the main React concepts toghether with a list of must see video / must read articles. Is not gonna be a short read, but if you care only about the Design concepts I m talking, just click on the following list of links:

Also keep in mind, this is not a React developer guide, there are a lot of better articles and guided for that, starting with the amazing Official React Documentation

The Journey

Part 1: Adopting React

The first part of my react journey is obviously how I decided to use it.

I start my fist job in London as a frontend developer, the company I was working wanted to migrate their website based on handlebarsjs to some other more modern js framework and they asked me to choose.

Everyone kind of knew/want Angular tehre, I had a previus experiense with it. So in I was like “in the end I m gonna choose Angular, but they give me one week, so I was sure I would have choose Angular. But I had 1 week to decide, so I decided to write a todo list with Angular, Ember.js and React. I Wrote the Angular and Ember with no problem, but then I started with React my initial reaction was “what da F** is this?” I do I display things? Why do I have to use so many callbacks everywhere? Where do I put my business logic?

I was lost. I understood that my usual Cowboy Coding Approach was not enough to have something working. So I started to search material about React.

Enter Pete Hunt, how I got exited about React

This was the first video I saw, Pete Hunt back then was working at Facebook and he was kind of “The Voice of React”. Apparently they presented react before this video and some people didn’t like it at all, telling ironicly that “facebook was rechinking eb best practices”. They use this as the title of this talk that try to explain the React Design decision

Pete Hunt: React: Rethinking best practices — JSConf EU

here the takeaway were (and they were A LOT):

Templates incourage poor separation of concerns
separating technologies (css, html, js) is not really separating concern
templates reinvent (in a underpowered way) concepts that already exists in programming languages, like (scoping)[https://en.wikipedia.org/wiki/Scope_(computer_science)]
not doing spaghetti code is up to you, not to the tecnology. Instead of separate css/html/js, do small component, also, be sure to have components with state separated by component that are pure UI.
work with your designer.
react component are just (idempotent function)[https://en.wikipedia.org/wiki/Idempotence#:~:text=Idempotence%20(UK%3A%20%2F%CB%8C%C9%AA,result%20beyond%20the%20initial%20application.] (aka if you pass a certain input you will always have the same output, like in math)
React components are pure function that you compose, so they are easyer to test
To simplify your life, immagine your state as a Giant JSON, and immagine to rerender the entire app all the time
rewrite your entire app every frame for real is slow, the virtual DOM make this efficent automatically render only the difference. AKA react virtual doom is like the Doom3 engine
Virutal DOM can run in node JS this means you can test ui with not super convoluted testing environment

I was amazed by all of this. I didn’t understood it all, but in my head I got this image:

and I was thinking “oh, my job as developer is just to model the entire state as a big JSON, translate this in visual component according with the designer, and then I m done”. More or less. Still my components were very nested, I found myselef pass callback everywere. Also people were saying me “with backbone or angular I don’t have to pass those callback everywhere, I just use the 2 way binding”. That’s when I discover Flux.

Meet Jin Chen, how I discover about Flux

Jin Chen: Talking about Flux

I ve always struggled with MVC. I found it verbose. Plus at this moment I felt the react idea made a lot of sense, but I was strugling doing even the easier thing. Luckily I saw this video of Jin Chang talking about flux, an “unidirectional data flow model” My understanding here was:

MVC can be messy
2 way binding is bad, unidirectional flow is good
make the functionality “unread chat messages” which is bug free is really difficult
the UI just dispatch actions, the store is taking the action and modifing your state. UI just read the state from the store and react to state changes
react and flux works very well togheter, they are complementary

In a nutshell I had this image in my mind:

also I ve understood why I always struggled with MVC, it can became this:

Which is a mess!

Adding With flux (or a state manager in general) my code became much more clear. In hear I ve remembrered Pete Hunt saying “not doing spaghetti code is up to you”.

More concept I was learning and better my code was becamming. Also I had the feeling that I was learning a lot about javascript and pattern design rather then specific things about React And Flux.

Also at this point something was clear to me: Facebook is using React for doing facebook itself and instagram. Google back then was not using angular for doing gmail or google.

I started using that at work.

Isomorphic Javascript aka Server Side Rendering

Somewhere I can find now, I get the concept of Isomorpchic Javascript. This means you can render your JS both in the backend and in the frontend. You can do this for 2 reason:

prerender stuff on the backend make feel the loadtime much faster to the user.
if used extensivly, your app can work even wihtout JS.

Given my context, I was even more amazed by those possibility, but the tools were clearly not making easy all those things.

Phase 2: Improving React knoledge

The rising of Redux

… TODO …

Here I am using React and Flux and this promise of a server side rendering. but flux was not really thinked for that. To be fear Flux was a library, but it was described with the sentence: “more a pattern then a library” I remember the impression I had, everyione liked the Flux pattern, but a lot of ppl though the Flux library could be improved. So library like https://github.com/yahoo/fluxible and https://acdlite.github.io/flummox were rising. I was even writing mine on top of FLux. I wanted to write samething that makes you achive the SSR in an simple way.

Dan Abramov presenting redux

hot reload? “time travel”? are you craxy? I rememberd I though “ok, this guy as won”. I abbandoned any work I was doing to my framework based on flux and I started to use it.

Redux was everything I wanted and it was offering a lot of things that I didn’t know yet I wanted. The vast majority of it was just javascript (an action is just a json, a reducer is just a function, the compose utils was litteraly something he could have been released by itelf).

I started to use it but after a while I had some problem writing code, I felt I was nesting a lot of things and my code was generically hard to change. I thought that maybe the fault was that redux was too long to write, so I tryied to reduce the boilerplate writing a framework on top of redux called reduxt. It didn’t helped much (and looking this know I feel a little bit of shame for reduxt :P). As often to me while using React, the problem was not the tool itself, but the way you are designing your code. Luckily I read this MUST READ article of Dan Abramov: Presentational and Container Components and my life changed. I realised that no other tools or library were needed, I ve just needed to learn how to organize my code better.

Now my state was written in a bunch of pure js functions (the reducers) and the visualization was written in a bunch of components that were as well pure js functions (what dan called presentational component in the article). another way to see it is the following: 1 your state is just a big JSON object 2 this json object is generated by the your reducers that accept an action and the prevState and return a specific part of the state, 3 the presentational components take part of those json using maybe some selectors and they just render it in HTML. Everything else a side those things is just gloo you write to make stuff work, namely Containers Components, Sagas , middleware , etc etc..

The good part is that you can write your UI and THEN make it work for real. I still remember when I wrote my login/logout logic. As you can immagine in the first iteration I was loosing the login every time I ve refreshed the page. To solve that, I ve just to added a middleware (maybe this one) and it just worked, with 0 changed in every part of the code. If you have experience with redux this could seems obvious, but to me back then, I could feel how much feel “clean” working with react and redux.

takeaways:

the “important” thing in your website are: store, reducers, selectors, actions, presentational components.
every side effect should be outside of those (unless in the action you are using thunk), typically in middlewares
the vast majority of your UI is in the presentational components.

*** How to work with the designer: Styleguide ***

I was starting be confident with react, and in this period I started a semi-serius pet project with a colegue of mine, who was a UI/UX designer who could code some JS.

One of the thing the React team was stressing in their talk was to work a lot with the designer, if the UX designer is using a tool like desing tools like Figma or Sketch, the way they organize their components should be exaclty the same as your UI component.

In my experience this is true if your designer is focusing a lot on the UX, that means usability, wich means consistency, wich usually means the abstract the UI in the right way reusing components when it make sense.

Luckily for me this was the situation, so in this side project I did the backend and in the frontend I let the designer write entirely by himself the presentational component.

The React Router

… TODO …

How to write Component that do logic

… TODO …

How to write Component that do logic

… TODO …

“Recent” react stuff

React Hooks and context API

Possibilities and tools react allows

Next.js the missing framework

That’s a quote from a friend of mine . Next js was making it easier the webpack configuration, you can do it only if you got

An interactive way to learn javascript: jsquest

Tue, 17 Aug 2021 22:19:00 GMT

Do you want to learn javascript / test your javascript skills, but reading articles and books is not your cup of tea?

Here you go: https://jsquest.io

That s all you need to know, go there and play with it, you will get it, the rest of the article is gonna just be some blah blah about why I did it and how.

What is this jsquest

If you are a person who can focus very intensively but just for very short amount of time, then I’m sure you struggle when you try to read books about coding. They are long, a lot of words, is hard to focus for me.

That’s why my preferred guide for js is this one: http://xahlee.info/js/js.html. I really think It’s describing JS in the minimum amount of words possible.

The story of jsquest

March 2007, i need to do my driving license, and I decide to study for the theory exam by myself. I found this amazing app where there are questions divided by arguments. You can try to respond, if you fail, there’s a link to the theory of that argument. That s just amazing and in one week I pass the exam. (Then it took me months to pass the driving exam, but that’s another story).

December 2011, is night, I’m in my bed thinking: “I want to improve my JS skills”. Js was my main language since a couple of years, but I felt I was using it like I was using JAVA (not in the best way, probably). So I’ve searched on google “advanced javascript”. I end up in this website where there was just some interactive code. Nothing else. But just trying to change the code, was enough for me to feel I was learning. It was mind blowing! Then I discovered that that website was supplementary material for Secrets of the JavaScript Ninja from John Resig, the author of jQuery.

February 2015, my team leader at the time ask me to teach some javascript to our designer. Also, 3 friends of mine wanted to change their position at the same time, they were all JS developers. This is when I discover the Xah Lee JS guide and I’ve started to use it to structure my lessons. I did with all of them several calls, i would say I’ve spent probably 20 hours with all of them to explain js fundamentals. The way I was doing this it was explaining them things via Skype and then Using a google docs to make them questions. In order to not have any misunderstanding, the questions were js code. And they had to respond with the result of the code execution. I call it “forcing people to understand”.

October 2016, another couple of people heard about those “courses” and they would love the idea of doing them but as you can imagine, is not easy to dedicate around 20 hours per person and everyone is busy, so is hard to get organized. Is also not particular pleasant to get lessons from me, patience is not exactly my best quality. That s when I’ve decided to do jsquest, taking inspiration from all the moments I told you.

The how of jsquest

I’ve created this react website (which work also offline, because I’m obsessed with offline first JS app). So is a classic creater-react-app website. I’m the most absent mind person ever, so in the very end every question is just an object in an array like this:

const questions = [  
  {    
     text:"default assignment",
     code :"var a; log(a);"  
   },
    //...
]

The code is evaluated when you click “Check” with the js command eval, check here to see the implementation. it worked almost in every case aside some edge case where not even stackoverflow could help me.

I save every given response in the local storage, evaluating on load time if they are true or not. For doing the responsive layout, I‘ve experimented a little with the CSS container queries using the library react-container-query

I ‘ve beautified the code with this trick I used often in React, doing something like:

<pre>
 {JSON.stringify(code, null, '  ')}
</pre>

adding a string with two whitespace as the third argument of JSON.stringify, is gonna format the code using those two space as formatter token.

I use it in my node.js debug all the time. The problem if you want to render this in html is that the content is automatically formatted, the only way to preserve the formatting is using the tag pre.

I’ve tryed to use react component to do code highlight instead of this trick, but the render was slow and in the end I prefer a responsive user experience then adding the colors.

In the end

It was a fun experiment, the whole experience made me a better js developer. Probably online there are tons of better interactive platforms to test/study JS, such as https://justjavascript.com/, so if your goal is to learn JS, check around.

But if you like the project and you want to contribute, feel free to send your PR here: https://github.com/jurgob/js_questions.

An easy way to try Vonage Communication API locally

Sun, 08 Aug 2021 16:37:00 GMT

At Vonage’s API department we’ve designed a collection of tools you might have come across as Communication API```. It allows you to do anything from sending/receiving SMS and phone calls, to creating video, audio, and text chats, all the way to the really “crazy” stuff like connecting a regular phone call to someone responding from a browser.

This article is not about Communication API. I will instead introduce you to a CLI tool called Conversation API function that will deeply simplify prototyping apps using Communication API, with as little config as possible.

If I have tingled your attention, and you want to get your hands in the dirt, visit https://github.com/jurgob/conversation-api-function and follow the instructions from there. You will have something up and running in less than 20 minutes (10 if you are a node developer).

If you have some extra time, make sure to also check out the examples and learn the variety of things this CLI allows you to do. You can stop reading here if you were just looking for a quick installation guide :).

But if you want to know something more about the why and the what of this CLI, keep reading on…

The Vonage configuration API fatigue

To test our communication API, you need to set up several things. let’s say you want to test how you can receive a voice call and say some text, and you want to do it locally. what you need to do is the following:

register to Vonage and buy an LVN
create an application
configure your number to be connected to your application
your “backend” is in your local machine as far as you are developing, so you need to expose this somehow with tools like Localtunnel.
configure your application to hit your public Locatunnel address, so you can receive in your local application the Vonage events.

after you do this, you can test a scenario where you receive a phone call. Let’s say you want to try a PHONE to BROWSER scenario. That means you have to add the following steps:

setup some frontend
configure our SDK in your frontend
typically set up some DB for storing some state of your business app.

Those steps are “easy” but not a little time-consuming, and the initial configuration and setup can be still pretty tricky for new developers.

Simplifying this is the main reason I wrote this tool.

In the below picture, a schema of a typical app using Communication APIs, in this case using the so-called Conversation API and the Voice API. THere’s also a front end using the Client SDK:

What the tool is doing for me? the short version

This tool requires just some minimal configuration once, then you will be able to develop and execute those javascript examples, that from now on I’m gonna call conversation function, in a super-easy way, and they are gonna be testable in your local machine!.

Do you want to share an example with someone else? just publish it on Github, if another person wants to test it, he can just download it, eventually run `npm install` and run the example. You are gonna run the same code, but you will not share any data or information!.

You may already have everything you need at this point, and you may prefer digging into the examples rather than reading the rest of the article. It’s fine! do it! Possibly have fun and create a new example of a use case I still didn’t think about, I accept pull requests in the read me!

What the tool is doing for me?

note: again, you can use the tool without really knowing all of the following, but is gonna help you in a deeper understanding of the tool and the Vonage API itself.

In general, when you use our API, you need to do the following steps:

The very first time, you need to create an account (e.g. My Company)
once you’ve got an account, (with the related api_key and api_secret), you need to create an application (e.g: My Chat Application or My Telephony Support System)
Once you create an application you get a private key, you need that to generate a JWT token.
If you want to program an incoming call or incoming Facebook message(e.g. you want to say “hello” to everyone calling you), you need to have a Vonage phone number (so-called LVN, Long Virtual Number), and you need to bind it to your application. Also, you need to configure a set of webhook URLs with your back end URL in order to be notified about something that happened in your application (e.g. someone is calling your LVN number)
if you are implementing the use case in step 4 and you want to test it locally, then you have to expose your laptop with some tool like Localtunnel or Ngrok and then update your application’s webhook in order to reach your laptop.

conversation-api-functions is gonna automatically run the steps 1/2/3 once you run the fist_config command. Every time you use run to execute your node function, steps 4 and 5 are gonna be done.

As soon as the first_config is creating a new Vonage application, this app is gonna be used for every conversation function you are gonna run on your laptop, and every device where you are gonna run that is gonna use a different application. That’s why if someone else is using your code, the data are not gonna be shared anyhow.

The anatomy of a conversation function

In the creation of this tool, I got inspired a lot from tools like AWS Lamda function , AWS SAM and Jamstack technologies and in particular Vercel.

All those things strive to let you focus only on what you are doing, without the need to be worried about details like “coding my infrastructure or “adding a CDN in front of my application” or “configure Webpack to split my Javascript code per page”. Those are concepts that you may ignore your all life and still be very successful in writing Next.js app in Vercel or lambda functions in ASW SAM.

in the same way, all you need to do when you write a conversation function is to write an index.js file where you export a js module that exports certain methods.

what those methods do, are documented here.

you may notice that excluding the handler route is a bit of an exception, every other handler has a 1:1 relationship with the webhook capabilities you can configure in your application. Check the Webhook types section in this link: https://developer.nexmo.com/application/overview, check for example the first row that shows voice property with and answer_url sub-property.
In the CLI you just need to implement the voiceAnswer handler, which is an express middleware.

As you can see you don’t need to be concerned about the part where you configure/update your Vonage app, or even spin up your express server.

In Conclusion

I’ve briefly introduced this new internal tool to quickly use the Vonage Communication API, if you have reached this part of the article, probably you now have a working example on your laptop and you’ve learned some notion about the Vonage API echo system. Your next step should now go in the Examples section here: https://github.com/jurgob/conversation-api-function#examples and see how many crazy things you can do!

Nodejs audio, lesson 5: make a phone call to your laptop with Vonage API

Sun, 08 Aug 2021 01:57:00 GMT

So that’s when I bring on what I do for living

In lesson1 and lesson2 we saw how to use row audio in nodejs, and how to use your mic and speaker.
Today we are gonna see how to make this audio going over the internet and connect it to a mobile phone.

Make it run

To make you understand deeply what we are gonna do, I have to explain you several concept of the vonage api, but first I want to you to see this working, just to get you exited.

go there https://github.com/jurgob/conversation-api-function follow the instruction to make it work.

In short, that’s a cli command to execute some examples. Now clone this repo: https://github.com/jurgob/ws-phonecall-receive rand make it run with the cli.

In the process you were required to buy and configure a phone number from vonage (the so-called LVN, Long Virtual Number). What you have to do now is start the ws-phonecall-receive example and after that dial the lvn from your phone.

You are gonna hear your phone audio through your computer speaker and you will be able to respond back!

Some context first

Before I explain what is going on, I need to explain what you are using.

The Vonage Comunication API https://www.vonage.co.uk/communications-apis/apis/?icmp=l3nav_apis_novalue#Communications Are a set of api that allows you to do video, audio, send sms, IM messages and chat in an easy way
When you work with real time api like ours, the comunication is tipical bidirectional, so you reach the api, but also the api need to be able to reach you. You typically do this adding your server address in the webhook configuration, but for doing it in your localhost, you need some trick, so to simplify this, I did the the tool called conversations-api-function.
so again, https://github.com/jurgob/conversation-api-function is a cli tool that I did for internal usage (so don’t expect support on that), it is done so you can quickly build prototype in your laptop and test them locally (is called conversation-api-function because initially I got kind of inspired by the aws lamda functions)
What the conversation-api-function is doing for you is just creating an application , and connecting it to your LVN.
The application has some webhook you can configure to notify your back end every time something happen (e.g. someone is calling you). Every time you start locally your code, your laptop is exposed on the public internet and the application is updated in order to inform your laptop

Now, let’s see the code

as you notice, the first thing you do is calling the LVN. When your lvn receive a call, the voiceAnswer callback is executed. This is a simple express middelware that should return a json response. This json response should be a valid ncco. An ncco is a set of instruction you use to program your call. It exist because is much easier using the ncco than using the api and manage all the details.
In this ncco, what you are telling to the server is just to connect the caller (your phone) to a to a websocket url that We are gonna expose in this same function

your function is expoing this websocket url. look the handler route , this is executed at your example startup, and his giving you and express app you can use to add any handler you want.

the instruction const speaker = getSpeakerStream() , which is executed at the script start up, is accessing it you your speaker.

in the line app.ws('/socket', …, I’m adding a websoket handler at the url /socket that is supposed to receive a ws stream containing the call audio.

As you can imagine, the interesting details are hidden in the getSpeakerStream() , startStreamMicAudioIntoWebSocket() and in the writeWSMsgintoSpeaker function. Let’s check them:

getSpeakerStream()

that is pretty straightforward, basically we are just getting access to the speaker same way we did in lesson1.

writeWSMsgintoSpeaker()

A lot more code here.

We start with something familiar from the lesson2, we are accessing the mic.

then we got:

var chunker = new SizeChunker({  
  chunkSize: 640   
});  
micInputStream.pipe(chunker);

this is basically taking the mic audio flow and chunking it in piece of 640 bytes.

now with chunker.on('data'… we are saying that every time I’ve got ready an audio package from my mic with the size of 640 , you should send this to Vonage via websoket.

writeWSMsgIntoSpeaker()

this also should be simple, we are “writing” every data package we receive from the backend in our speaker, so we can ear the voice coming from the phone. notice we are doing this only if this check pass: if(isBuffer(msg)) , that’s because audio is not the only thing Vonage is sending you via web socket but that’s the only thing you want to pass to your speaker.

That’s all Folks

It was long but we did it!

Let me know if you have any comment, feedback question!

Nodejs audio, lesson 4: apply some audio effects to your voice

Wed, 04 Aug 2021 02:33:00 GMT

As we learned in lesson 1 and lesson 2, your mic is a readable stream and your speakers are a writable stream, to make them work together you just need to pipe them.

But what if we want to apply some audio effects to our voice?

for this we are gonna put `something` in the between of those 2 streams. this something is gonna be an npm library called sox-audio

let’s install it with

npm install -s sox-audio

then let’s create a file:

touch lesson_04__p1_audio_effects.js

and let’s add this code in it:

find the full code here

now run

node lesson_04__p1_audio_effects.js

and try to talk: you should hear your voice like you are inside of a garage. I suggest you to use an headset during your tests, if you don’t you will add an echo in your voice and you will probably not be able to appreciate reverb effect.

Tell me more about audio effects

In general, sox-audio is just a wrapper on top of sox, so you can search online how to apply effects, but when you call addEffect you are colling the cli command under the hood, so you can take any example of sox usage and apply the same params. here is a good article to start: https://h3manth.com/2009/01/08/sox-sound-exchange-2

check out the lesson 4 part 2 file here: https://github.com/jurgob/nodejs_audio_examples/blob/main/lesson_04__p2_multiple_audio_effects.js

you can specify a number from 0 to 3, corrisponding to a different effect:

node lesson_04__p2_multiple_audio_effects.js 3

Nodejs audio, lesson 3: math and music, baudio for the win

Wed, 04 Aug 2021 00:30:00 GMT

Before you read this, be sure you read the lesson 1 and lesson 2

What is audio? in unix everything is a file, even programs and devices. the way those things comunicate with each other, are strings (or numbers in this case).

that means basically you can “play” everything. That’s more or less the concept behind the npm package baudio.

disclaimer: I m gonna beefily cover this topic, so if you don’t understand it, just skim or skip. The porpouse here is just to show you that your microphone or music files are not the only thing you can use to produce audio.

create a file with

touch lesson_03__math_music_baudio.js

now put this code in it:

find the full code here

now just hear your “music” running:

node lesson_03__math_music_baudio.js

you are gonna listen some white noise.

if you want to hear a different sound, just run

node lesson_03__math_music_baudio.js 4

pass a number from 0 to 4 for different noises.

What we did?

As usual, our speaker is a writable stream. baudio is basically a library that given a a callback is generating a readable stream.

const music = baudio(musicSelected);

music.pipe(speaker)

musicSeleceted in the end is the selected callback to generate the music we want, we use the operator .pipe as usual to play our music in our speakers.

Some notes about baudio

basically doing ”music” with baudio means implement a function that is accepting a t (is a point in time, is a float number that is gonna be bigger at every call) and must return a float number between -1 and 1.

If you are curious about the topic and you can to compose something more complicated that what I did , checkout this: https://www.youtube.com/watch?v=2oz_SwhBixs

next lesson: Lesson 4: Apply some audio effects to your voice

Nodejs audio, lesson 2: ear your voice from your speakers

Tue, 03 Aug 2021 20:24:00 GMT

In the previous lesson we did the setup of our project, and we learned how to acquire audio from our mic and dump it into a file.

In this article, we are gonna use your microphone.

Let’s start creating a file for this lesson:

touch lesson_02__speaker.js

then lets install an npm packege calledspeaker:

npm install -s speaker

remember, to make this package work, you neet to be sure you have installed sox. That’s the same tool we have installed in the previous lesson to make the mic package work, so if you did the lesson 1, you don’t need to install sox now.

now inside the lesson_02_spkeaker.js add the following code:

go here to find the full code

run the file with the command:

node lesson_02__speaker.js

if you talk now, you will ear back your voice. press ctrl + c to close the application.

What have we done?

the mic is initialized as the previous lesson.

with those line we are gonna initialize the speaker:

const speaker = new Speaker({  
    sampleRate: audioConfig.rate,  
    channels: audioConfig.channels,  
    bitDepth: audioConfig.bitDepth  
  });

the object `speaker` is now a Writable stream so we can “write” our audio in our speakers with the line:

micInputStream.pipe(speaker);

next lesson: Nodejs audio lesson 3: Math and Music, baudio for the win

Nodejs audio, lesson 1: enter the mic

Tue, 03 Aug 2021 20:15:00 GMT

This is gonna be a series of article teaching your how to use audio with nodejs

Click here to go to the final Github repo.

In my work at Vonage I deal with audio a lot. Despite this, I m very far from being an audio expert. I don’t work with the details or even with the media part, so I decided to do some experiment to understand it better. During those experiments, I’ve realized that is something very fun, but not very documented. There are few libraries we are gonna use written by different people that are just managing what is called “raw audio”, when I make them work together, I felt like some kind of magic was happening. In this series of article, I m gonna share with you my experience, I hope you are gonna feel the same joy I felt.

Getting started

we are gonna need to following tools installed in your laptop

sox
nodejs 14

Installing sox

The majority of the npm package we are gonna use rely heavily on sox which is a multi-platform cli tool to manage audio (they define it the Swiss Army knife of sound processing programs). you can download it here: http://sox.sourceforge.net/ but if you are on mac and you have brew installed, just run brew install sox . Once you have installed it, let’s verify the installation is completed (you may need to open another terminal before you do that):

run:

sox --version

That’s what you should see:

Installing Node.js 14.

You can install Node.js in many ways, but if you are on mac, I suggest you to install `nvm` (https://github.com/nvm-sh/nvm)

is better if you read how to install nvm in the guide, but If you are on mac and you trust me, and run;

install nvm

curl -o- [https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh](https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh) | bash

open a new terminal and run nvm -v``. if this is not working be sure you have in your ~~/.zsrcor in your~~/.bashrc“the following lines:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"  
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

when added, open another shell and it should work.

2. install node 14

Once nvm is installed just run

nvm install 14.15.0

and then node -v to confirm you have the right version

You can probably use any other version of node, but if you want to minimize the risk of having this code not working, I suggest you to use exactly the same node.js version I’ve used.

Let’s start coding!

we are gonna do the following:

create a new project
install some dependencies
access to our laptop mic, record 15 seconds of voice
create a new project

mkdir nodejs_audio_examples  
cd nodejs_audio_examples

npm init

respond to all of the questions leaving the default option.

now let’s install this amazing library to access our mic:

npm install -s mic

now let’s create our first file:

touch lesson_01__enter_the_mic.js

here is the code we are gonna put there:

find the full code here: https://github.com/jurgob/nodejs_audio_examples/blob/main/lesson_01__enter_the_mic.js

Let’s try it

if you now run

node lesson_01__enter_the_mic.js

the program will run, starting to record for 15 seconds. once the program is done, you will see a file output.row that you can play with the command

play -b 16 -e signed -c 1 -r 16000 output.raw

here is a screenshot of what you should see after 15 secs:

So congrats, you have successfully recorded and played your voice!.

What’s going on!?!

let’s explain some of the code.

const audioConfig = {  
    rate: '16000',  
    channels: '1'  
}

const micInstance = mic({  
    rate: audioConfig.rate,  
    channels: audioConfig.channels,  
    debug: false,  
    exitOnSilence: 6  
});

with this code we are instantiating the microphone, we are instructing it to take the audio to a sample rate of 16k and 1 channel. Those params are important, because when you are gonna play the file, you need to play the audio with into the speaker you will need to specify those params and they will need to be exactly the same.

const micInputStream = micInstance.getAudioStream();

const fileName = ‘output.raw’  
const outputFileStream = fs.WriteStream(fileName);

micInputStream.pipe(outputFileStream);

This is an important bit to understand. The audio coming from the microphone is a continuous flow of data. To operate in data flow, Node.js offers you an object called Stream. Streams are everywhere in Node.js, you use them when you write/read files, you use then when you send/ receive http requests. But usually, you are using simpler library on top of streams, because it is hard to reason in terms of streams and you don’t always need.
But now the time has come, we can’t avoid using them, let’ see what those streams are.

here is the stream documentation:

Stream | Node.js v16.6.1 Documentation_Almost all Node.js applications, no matter how simple, use streams in some manner. The following is an example of using…_nodejs.org

here they are defined in this way: “A stream is an abstract interface for working with streaming data in Node.js. The stream module provides an API for implementing the stream interface.”.

There are several type of stream but we are interested in just 2 types,

Writable Stream: streams to which data can be written
Readable Stream: streams from which data can be read

As you can imagine, in our example, we are getting a readable stream from the microphone with micInstance.getAudioStream() , we are generating a writable stream for the file output.raw with fs.WriteStream(fileName) and finally, we are “writing” the audio coming from the microphone in the file stream, with micInputStream.pipe(outputFileStream)

next lesson: nodejs audio lesson 2: Ear your voice from your speakers

Nodejs and Audio

Mon, 02 Aug 2021 19:19:00 GMT

Hello, I m Jurgo and I work as a node.js developer at Vonage. What I do there is this Conversation API. Sometimes I describe it as “an API for doing your own slack”.

Because of this product, sometimes I have to deal with audio. I found that audio is a very scary topic in the beginning, mainly because of the lack of documentation.

I m far from being an audio expert, but over the years I‘ve managed to make some working code using the few audio-related libraries you can find in NPM, so I’ve decided to share what I’ve learned in this series of articles.

This is gonna be our journey:

Lesson 1: enter the mic

Lesson 2: Ear your voice from your speakers

Lesson 3: Math and Music, baudio for the win

Lesson 4: Apply some audio effects to your voice

Lesson 5 Make a phone call to your laptop with Vonage API

Click here to go to the final Github repo with all the lessons

Reduxerit — trying to reduce redux boilerplate

Sat, 16 Apr 2016 18:13:00 GMT

Basically, the idea is to easily create a reducer who expect an action with type [REDUCER_NAME]_SET_STATE. the payload of this action will be a partial state witch will be merged with the old state.

The idea is trying to reduce the redux boilerplate as much as is possible.

It’s still possible to enrich the reducer to use the classic approach for some actions.

WITHOUT REDUX UTILS:

reducers/index.js

undefined

actions/index.js

export const toogleEditorExpanded = () => {
 return {
   type:ACT.LAYOUT_TOOGLE_EDITOR_EXPANDED,
 }
}

export const toogleLayoutDirection => {
  return {
    type: ACT.LAYOUT_TOOGLE_DIRECTION
  }
}

WITH UTILS:

reducers/index.js

const layoutDefState = {
 isEditorExpanded: false,
 direction:"horizontal"
}
const layout = createBasicReducer(‘LAYOUT’,layoutDefState)

actions/index.js

const createLayoutAction = createUpdateStateAction(‘LAYOUT’);
const getLayoutState = getReducerState(store, ‘LAYOUT’)

export const toogleEditorExpanded = () => {
 const isEditorExpanded = !getLayoutState().isEditorExpanded;
 return updateLayoutState({
  isEditorExpanded
 })
}

export const toogleLayoutDirection = () => {
 const direction = getLayoutState().direction === 'vertical'
   ? 'horizontal'
   : 'vertical'

 return createLayoutAction({
   direction
 })
}

CONS:
more responsability to the actions (is it a problem?)

actions payload are bigger

probably is harder to debug (e.g. in )

PRO:

you don’t need a lot of string constant for events name

every time you add an action, you just modify one file, non need to modify

the last point it will generate really less code. Imagine if you have to add the events “enable” and “disable” for both the property…

the utils:

function createReducer(initialState, handlers) {
 return function reducer(state = initialState, action) {
  if (handlers.hasOwnProperty(action.type)) {
   return handlers[action.type](state, action)
  }
  else {
   return state
  }
 }
}

export const createBasicReducer = (reducerName , initialState) => {
 
 const _initialState = {
  …initialState,
  reducerName
 }
 
 return createReducer(
  _initialState,
  {
   [reducerName+’_SET_STATE’] : (state, action) => ({
   …state,
   …action.state
  }
 )
 
})}

export const getReducerState = (store, reducerName) => {
 return function(){
  const globalState = store.getState()
  const stateReducerName = Object.keys(globalState).find((p) => globalState[p].reducerName === reducerName )
  return globalState[stateReducerName]
 }
}

export const createUpdateStateAction = (reducerName) => {
 return (state) => ({
  type:reducerName+’_SET_STATE’,
  state
 })
}

Casual Programming RSS Feed

Types in Typescript should make your life easier

Zod Is the De‑Facto Standard

Validate What You Don’t Control

Never Use any

Strings Are Overused

Avoid Enums: They Kill Composability

Prefer type Over interface

Strict Types Aren’t Expensive — Duplication Is

Use Discriminated Unions

Zod Example

Explicit Environment Variable Validation

Share Types in a Monorepo

Network Validation with ts‑rest

Minimal Monorepo Example (Conceptual)

Final Takeaways

Progressive React: When Your App Still Works with JS Disabled

Why This Matters: Beyond Just “Working Without JavaScript”

Escaping the Uncanny Valley

Real Performance Benefits

Accessibility by Default

SEO and Crawlability

Developer Benefits

The Philosophy: Progressive Enhancement as Modern Best Practice

About the Matrix Protocol

React Router 7: The Bridge Between Server and Client

The Anatomy of a Route

Server vs. Client Execution

A Practical Example

Key Components and Hooks

Progressive Enhancement in Practice

Without JavaScript: Nearly Full Functionality

With JavaScript: Enhanced Experience

Feature Comparison: Matrix Chat Implementation

Implementation Deep Dive

Login/Register

Create Room

Search Rooms

Room Messages and Real-time Updates

The Evolution of Separation of Concerns

Why This Matters for Backend-for-Frontend

Key Takeaways

More Belongs in Loaders and Actions Than You Think

Embrace URL State

Progressive Enhancement Isn’t Just Nice-to-Have

The Framework Handles the Hard Parts

Conclusion

Thinking in React in few words

Thinking in React

The “Minimal State” Principle

A Better Approach

The React Tic Tac Toe Challenge

Defining Types

But Who Made the Move?

Determining Game Status

That’s All, Folks!

A Note on Performance

Loose Types Make Your Code Verbose — Type Narrowing to the Rescue!

Loose Types Make Your Code Verbose — Type Narrowing to the Rescue!

TL;DR Version

The User Object: Starting Simple

unknown to the Rescue

What About object?

✅ Use Record<string, unknown>

How you use it:

Bonus tip

Narrowing with Union Types

Summary

Implementing a Node.js/Express Server Using MinIO for Image Uploads

Implementing a Node.js/Express Server Using MinIO for Image Uploads

What We’re Going to Do

For the Impatient

Introduction to S3, MinIO and Pre-signed URLs

Amazon S3 and Minio

Pre-signed URLs?

Example: PUT Pre-signed URL

Why Are Pre-signed URLs Needed?

Architecture Quick Overview

Setting up the server dependencies with docker compose

Explaining the Docker Compose File

Never Use `any`

Prefer `type` Over `interface`

The `User` Object: Starting Simple

`unknown` to the Rescue

What About `object`?

✅ Use `Record<string, unknown>`

Understanding: `src/index.ts`

The complete `src/index.ts` file:

Understanding `src/server.ts`

Endpoint: `/api/uploads/images`

Endpoint: `/api/urls/:key`

The entire `scr/server.ts`:

Update `package.json`

Enter the `never`

Using `never` in Functions

Using `never` in Switch Statements