Why Does a Custom Image Format Exist?

The short answer is GPU efficiency. Standard image formats like PNG or JPEG are optimized for storage and transmission — they compress well and decode fast on a CPU. But a GPU doesn't want PNG. It wants textures in a format it can load directly into VRAM and sample from without any further decompression.

Blizzard needed a format that could:

• Store compressed texture data the GPU can use natively
• Bundle multiple resolutions of the same image (mipmaps)
• Handle both photographic textures and palette-based art
• Be fast to load on 2002-era hardware

BLP is the result. It's a container format that wraps one of several internal compression schemes depending on what the texture contains.

The Compression Variants

BLP2 (the version used in WoW) supports three compression types:

DXT (also called S3TC) is the interesting one. It's a block-based compression scheme designed specifically for GPU hardware. The image is divided into 4×4 pixel blocks, and each block is encoded as a pair of endpoint colors plus a 2-bit index per pixel that interpolates between them. The result is a fixed compression ratio regardless of image content — 4:1 for DXT1, 2:1 for DXT3 and DXT5 — and crucially, GPUs can decompress it on the fly in hardware while sampling.

Three variants handle different alpha needs:

• DXT1 — no alpha or 1-bit alpha (transparent/opaque only). Most space-efficient.
• DXT3 — explicit 4-bit alpha per pixel. Good for sharp alpha edges.
• DXT5 — interpolated alpha, same block scheme as the color data. Best for smooth gradients and soft transparency.

RAW1 (palettized) is the legacy format, used heavily in Warcraft III and early WoW content. It stores 256 colors in a palette and one byte per pixel pointing into it — the same approach as GIF. Compact for textures with limited color ranges, but not GPU-native.

RAW3 is uncompressed RGBA — no tricks, just raw pixel data. Largest files, fastest conversion.

import { decodeBlpData, encodeToBLP } from "@pinta365/blp";

// Read a BLP file and get raw RGBA pixel data
const blpBytes = await Deno.readFile("texture.blp");
const { width, height, rgba } = await decodeBlpData(blpBytes);

// Convert a PNG back to BLP (DXT5 with alpha)
const pngBytes = await Deno.readFile("texture.png");
const blpOutput = await encodeToBLP(pngBytes, { compression: "dxt5" });
await Deno.writeFile("texture_new.blp", blpOutput);

Mipmaps

Every BLP file bundles a mipmap chain — pre-computed half-resolution copies of the texture, all the way down to 1×1. So a 512×512 texture ships with versions at 256×256, 128×128, 64×64, and so on, all inside the same file.

The GPU uses these automatically. When a texture is rendered small (far away, small on screen), the engine samples from a smaller mipmap instead of downscaling the full texture at runtime. This reduces aliasing and is far cheaper to compute.

The library gives you access to all mipmap levels, which matters if you're doing texture processing pipelines or want to inspect what the engine is actually using.

The Power-of-2 Requirement

BLP (like most GPU texture formats) requires image dimensions to be powers of two: 64, 128, 256, 512, 1024, and so on. This constraint goes back to how graphics hardware addresses texture memory.

If you try to convert a 300×200 PNG to BLP, something has to give. The library handles this automatically with configurable padding modes that preserve the entire image — no cropping, no distortion. The padding approach matters especially for texture atlases, where the actual content might not fill a power-of-2 canvas but all of it needs to survive the round-trip.

Smart Format Detection

When encoding to BLP, picking the right compression variant isn't always obvious. The library analyzes the source image and recommends a format:

• If the image has no alpha channel → DXT1
• If it has sharp, binary transparency → DXT1 with punch-through alpha
• If it has smooth alpha gradients → DXT5
• If the image uses fewer than 256 colors → RAW1 (palette)

You can override this, but the auto-detection handles the common cases correctly without requiring knowledge of the compression internals.

blp-toolkit: Conversion in the Browser

All of the above is available at blp.pinta.land without installing anything. Upload a BLP file to get a PNG preview with full metadata inspection — compression type, dimensions, mipmap count, all of it. Or upload a PNG and convert it to BLP with control over the target compression format and padding mode.

Everything runs client-side. Your files never leave the browser.

It's built in TypeScript with @pinta365/blp as the engine, so the same parsing and conversion logic that runs in your Deno or Node.js pipeline works identically in the browser.

Using the Library

# Deno
deno add @pinta365/blp

# Node.js / Bun
npx jsr add @pinta365/blp

Source for both projects is on GitHub: blp and blp-toolkit.

Who Is This For?

Primarily WoW modders and addon developers who work with game assets — either extracting textures from the client to reference in UI work, or creating custom textures to ship with an addon. But it's also useful for anyone building tooling around Blizzard game data more broadly: map editors, model viewers, asset pipelines.

The BLP format isn't going anywhere. Two decades of game content means two decades of BLP files out there, and the modding community still actively creates and converts them. Having a modern, cross-runtime TypeScript library for it felt like a gap worth filling.

What Is Steganography?

Cryptography hides the meaning of a message. Steganography hides the fact that a message exists at all. Instead of encrypting "meet me at noon" into an unreadable blob, you embed it invisibly into a cover medium — an image, a document, or even plain text — and the result looks completely normal to anyone who doesn't know to look.

The word comes from Greek: steganos (covered) + graphia (writing). The practice goes back centuries, from invisible ink to microdots in wartime espionage. Today it shows up in digital watermarking, copyright protection, and — for our purposes — hiding messages inside image files.

Hiding Data in Images: LSB Encoding

The most common technique for image steganography is Least Significant Bit (LSB) encoding. To understand why it works, consider how a PNG stores color.

Each pixel has red, green, blue, and alpha channels, each an 8-bit value from 0 to 255. The most significant bits carry most of the visual information. The least significant bit contributes almost nothing — flipping it changes a channel value by 1 out of 255, a difference no human eye can detect.

That means you can overwrite the LSB of each channel with your own data without visibly changing the image. A 1000×1000 PNG has 1,000,000 pixels × 4 channels = 4,000,000 bits available — enough to hide roughly 500 KB of data.

import { embedTextInImage, extractTextFromImage } from "@pinta365/steganography";

// Hide a message in a PNG
const encoded = await embedTextInImage(imageBytes, "Hello, world!");

// Retrieve it later
const message = await extractTextFromImage(encoded);
// → "Hello, world!"

The library also supports adjustable bit depth: instead of using just 1 bit per channel, you can use 2, 3, or 4. More bits means more capacity, but also more visible distortion — a trade-off you tune depending on how sensitive the image is and how much data you need to hide.

LSB works great for lossless formats: PNG, WebP, BMP, GIF. But send that image through JPEG compression and the hidden data is destroyed — because JPEG doesn't preserve exact pixel values.

The JPEG Problem: DCT Encoding

JPEG compression works by dividing an image into 8×8 pixel blocks, applying the Discrete Cosine Transform (DCT) to convert each block into frequency components, and then quantizing (rounding) those components to discard detail the eye won't miss. That rounding step is exactly what kills LSB-encoded data.

To survive JPEG compression, you need to embed data in the DCT coefficients themselves — before quantization is applied. The library does this by making small, deliberate modifications to the DCT coefficients in a way that survives a re-encode at the target quality level. The result is a JPEG that retains your hidden data even after it's been re-saved.

This is significantly more robust than pixel-domain embedding, which is why it's used in real-world watermarking systems.

Hiding Data in Text: Zero-Width Characters

Here's the one that genuinely surprises people: you can hide data in plain text, with no images involved.

Unicode includes a set of zero-width characters — code points that render as nothing visible. Characters like U+200B (zero-width space), U+200C (zero-width non-joiner), and U+200D (zero-width joiner) are completely invisible in any rendered text. But they're still there in the raw string.

The library uses sequences of these characters to encode binary data and distributes them throughout normal text. Copy-paste the result anywhere text is accepted — a tweet, a comment, a document — and the hidden message travels with it, invisible to readers but extractable by anyone with the right tool.

import { encodeText, decodeText } from "@pinta365/steganography";

const cover = "Nothing to see here.";
const stego = await encodeText(cover, "secret payload", { encrypt: true, password: "hunter2" });

// stego looks identical to cover when rendered
const decoded = await decodeText(stego, "hunter2");
// → "secret payload"

Text steganography optionally layers AES-256-CTR encryption on top, so even if someone knows to look for hidden data, they can't read it without the password.

UnderByte: A Web UI for All of This

All of the above is available through a browser at underbyte.pinta.land. Upload an image, type your message, optionally set a password, download the result. The app shows you real-time capacity statistics and lets you tune the bit depth — useful for getting a feel for the LSB trade-offs without writing any code.

It's built on Deno with the Fresh framework, using @pinta365/steganography as the underlying engine.

Using the Library

The steganography library is runtime-agnostic and available on JSR and npm:

The full source for both projects is on GitHub: steganography and UnderByte.

When Would You Actually Use This?

Steganography has legitimate practical uses beyond the obvious "secret messages" scenario:

• Digital watermarking — embed an invisible ownership mark in images you distribute.
• Covert channels in research — testing whether a system leaks data through unexpected means.
• Privacy in hostile environments — hiding the existence of a message can matter as much as hiding its content.

It's also just a genuinely interesting space to build in. The gap between "this looks like any other image" and "this image contains a hidden document" is surprisingly narrow — a few bit flips per pixel is all it takes.

What Are AI Coding Agents?

Before we dive in, let's clarify what makes these tools different from the chatbots you might have used before. A traditional AI chat can answer questions about code and generate snippets you copy-paste into your editor. An agentic coding tool goes further — it can browse your project files, execute terminal commands, create and edit files, and reason across your entire codebase to implement changes autonomously.

Three major players right now are:

• Claude Code — A command-line interface from Anthropic that runs directly in your terminal. It follows the Unix philosophy of composability, letting you pipe logs, chain commands, and work where your code actually lives.
• Cursor — An IDE with a built-in "Agent Mode" that combines a full editor experience with autonomous code generation. Its Plan Mode lets you review the agent's approach before it writes a single line.
• GitHub Copilot — Offers both local IDE integration and cloud-based agents that can work on GitHub issues and pull requests asynchronously.

Setting Up Your First Agent

Getting started is surprisingly straightforward. Each tool has its own setup flow, but the general pattern is similar: install the tool, authenticate, and let it analyze your project.

Claude Code

Claude Code runs in your terminal. After installing it, you simply navigate to your project directory and run the claude command. The first time you do this, it opens your browser for authentication — no need to manually manage API keys. Once authenticated, run /init and the agent will crawl your project, identify your tech stack from marker files like package.json or deno.json, and generate a CLAUDE.md file that serves as its persistent memory about your project.

Cursor

Cursor is a standalone IDE. After installation, you can open your project and access Agent Mode through the Composer interface. To get the most out of it, activate Plan Mode (Shift+Tab) which forces the agent to research your codebase and present an implementation plan before making changes. Configuration lives in .cursor/rules/ as .mdc files where you can scope rules to specific file patterns.

GitHub Copilot

If you're already using VS Code, Copilot integrates directly into your editor. The /init command generates a .github/copilot-instructions.md file for your repository. On GitHub.com, you can assign issues directly to Copilot, and it will create pull requests for you to review — great for routine tasks like documentation updates or minor fixes.

The Key Concept: Instruction Files

Here's where things get interesting. The single most impactful thing you can do to improve your AI coding experience is to maintain good instruction files. These are markdown files that tell the agent how your project works.

Think of it this way: when a new developer joins your team, they need to learn the build commands, the coding conventions, the project structure, and the workflow rules. An AI agent needs the same onboarding, and instruction files are how you provide it.

A good instruction file should include:

• Build and test commands — the exact CLI commands, not paraphrased versions.
• Coding conventions — preferred libraries, naming patterns, file organization.
• Workflow rules — things like "always create a new branch for features" or "run tests before committing."

Keep it concise. The agent reads this file every session, and a bloated instruction file wastes the agent's context window — the limited memory it has available for each conversation.

Your First AI-Assisted Task

Let's walk through a practical workflow. Say you want to add a new feature to your project.

1. Describe what you want. Be specific. Instead of "add authentication," try "add a login endpoint using JWT tokens that validates against the users table." The more precise your prompt, the better the result.

2. Let the agent plan. In Cursor, use Plan Mode. In Claude Code, describe the feature and ask it to outline an approach before implementing. Review the plan — does it match your expectations? Are the right files being modified?

3. Watch and redirect. As the agent works, keep an eye on the changes. If it starts heading in the wrong direction, interrupt and correct course. You're the architect; the agent is the builder.

4. Verify the result. Run your tests. Review the diffs. Don't blindly trust the output — treat it like a pull request from a junior developer who writes decent code but occasionally misses edge cases.

Common Pitfalls for Beginners

As you start incorporating AI agents into your workflow, watch out for these common traps:

Over-trusting the output. AI-generated code can look perfectly reasonable while being subtly wrong. Always review diffs and run your test suite. The agent is a powerful assistant, not an infallible oracle.

Vague prompts. "Make it better" or "fix the bugs" gives the agent very little to work with. Specific, contextual prompts produce dramatically better results. Reference specific files, error messages, or behaviors you want to change.

Ignoring the context window. Every message, file read, and command output consumes space in the agent's working memory. In long sessions, the agent may start "forgetting" earlier instructions. Use features like /compact in Claude Code to compress the conversation, or start a fresh session for new tasks.

Skipping the instruction file. Many developers install the tool and start prompting without setting up a CLAUDE.md or equivalent. This is like onboarding a new team member without telling them anything about the project. Spend the time upfront — it pays for itself immediately.

Developing the Right Mindset

Working effectively with AI coding agents requires a subtle shift in how you think about development. You're moving from writing every line yourself to directing behavior. This means thinking at a higher level — about architecture, requirements, and constraints — while delegating the implementation details.

This doesn't mean you stop understanding the code. Quite the opposite. You need to understand it well enough to review what the agent produces, catch mistakes, and steer it in the right direction. The developers who get the most out of these tools are the ones who combine strong fundamentals with clear communication.

Where to Go from Here

Once you're comfortable with the basics, there's a lot more to explore:

• MCP (Model Context Protocol) — An open standard that lets agents connect to external data sources like documentation servers, databases, or project management tools.
• Subagents — Some tools like Claude Code support spawning specialized agents that work on different parts of a task simultaneously.
• Custom rules and scoping — As your projects grow, learn to scope your instruction files so the agent only loads relevant context for the task at hand.

The landscape of AI-assisted development is evolving rapidly, but the fundamentals stay the same: give the agent clear context, review its work carefully, and think of it as a capable collaborator rather than a magic solution. Start small, build confidence, and gradually expand how you use these tools in your daily workflow.

Happy coding with your new AI partner!

What is BoxFrame?

BoxFrame is a DataFrame library for JavaScript/TypeScript, built with WebAssembly (WASM) compiled from Rust. It provides an intuitive API for data manipulation, analysis, and processing that works across different JavaScript environments - from browsers to Node.js to Deno.

Inspired by Python's pandas library, BoxFrame brings structured data manipulation to the JavaScript ecosystem with native performance.

Key Features

BoxFrame is a DataFrame implementation for JavaScript. The library uses WebAssembly compiled from Rust for core operations, which provides better performance than pure JavaScript implementations. When WebAssembly is not available, it automatically falls back to pure JavaScript implementations. It works in multiple JavaScript environments including Deno, Node.js, Bun, and browsers.

The library automatically infers data types and supports int32, float64, strings, booleans, and dates. It provides a fluent API with method chaining for data transformations, along with operations like GroupBy, aggregation, filtering, and sorting. Data can be imported from CSV files, JSON, and Google Sheets.

Getting Started with BoxFrame

Installation

# For Deno
deno add jsr:@pinta365/boxframe

# For Node.js
npx jsr add @pinta365/boxframe

# For Bun
bunx jsr add @pinta365/boxframe

# For browsers (ESM)
import { DataFrame } from "https://esm.sh/jsr/@pinta365/boxframe@0.0.1";

Your First DataFrame

import { DataFrame } from "@pinta365/boxframe";

// Create a DataFrame from an object
const sales = new DataFrame({
  product: ["Laptop", "Phone", "Tablet", "Laptop", "Phone"],
  price: [999, 699, 399, 1099, 799],
  region: ["North", "South", "North", "South", "West"],
  quantity: [5, 12, 8, 5, 15],
});

console.log(sales.toString());

Data Analysis

// Find best selling products by region
const topProducts = sales
  .groupBy("region")
  .agg({
    price: "mean",
    quantity: "sum",
  })
  .sortValues("quantity_sum", false);

console.log(topProducts.toString());
/*
DataFrame
shape: [3, 2]

      price_mean quantity_sum
South 899        17
West  799        15
North 699        13
*/

Advanced Features

Method Chaining

BoxFrame's fluent API makes complex data transformations readable:

const result = sales
  .query("price > 700") // Filter expensive items
  .groupBy("region") // Group by region
  .agg({ quantity: "sum" }) // Sum quantities
  .sortValues("quantity_sum", false) // Sort by total quantity
  .head(2); // Get top 2 regions

console.log(result);

Data Sources

Read data from various sources:

// Read CSV file
const df = await BoxFrame.readCsv("data.csv");

// Parse CSV content
const df2 = BoxFrame.parseCsv("name,age\nAlice,25\nBob,30");

// Read from Google Sheets
const df3 = await BoxFrame.readGoogleSheet("your-sheet-id");

// Create from array of objects
const df4 = BoxFrame.fromObjects([
  { name: "Alice", age: 25, city: "New York" },
  { name: "Bob", age: 30, city: "London" },
]);

Performance with WebAssembly

BoxFrame automatically uses WebAssembly for performance-critical operations:

// Check if WASM engine is enabled
console.log(BoxFrame.isWasmEngineEnabled()); // true

const largeData = new DataFrame({
  values: Array.from({ length: 100000 }, () => Math.random()),
});

// This operation uses WASM for better performance
const sorted = largeData.sortValues("values");

Try It Live!

Experience BoxFrame in your browser: JSFiddle Demo

The demo showcases:

• WASM engine detection
• Google Sheets integration
• DataFrame creation and manipulation
• GroupBy and aggregation operations
• Real-time output display

Cross-Platform Compatibility

BoxFrame works everywhere Modern JavaScript runs:

Browser

<script type="module">
  import { DataFrame } from "https://esm.sh/jsr/@pinta365/boxframe@0.0.1";
  // Use DataFrame in your browser app
</script>

Node.js

import { DataFrame } from "@pinta365/boxframe";
// Full Node.js support with file system operations

Deno

import { DataFrame } from "@pinta365/boxframe";
// Native Deno support with modern JavaScript features

Start Building Today!

BoxFrame makes data analysis accessible in JavaScript. Whether you're building data visualization tools, analytics dashboards, or processing large datasets, BoxFrame provides the tools you need.

Ready to get started? Check out the complete documentation with API reference, examples, and guides.

You can find the library source code on GitHub and install it from JSR.

Let us know if you have any questions or feedback!

Sandbox: Your Testing Playground

The Oura API sandbox is a simulated environment that provides you with sample Oura Ring data. This lets you experiment with the API, build prototypes, and thoroughly test your application's logic before going live. All this without needing an Oura user account or access token.

Getting Started with the Sandbox

To access the Oura sandbox with @pinta365/oura-api is as simple as creating a new Oura client with the useSandbox option set to true:

Installation

# For Deno
deno add @pinta365/oura-api

# For Bun
bunx jsr add @pinta365/oura-api

# For Node.js
npx jsr add @pinta365/oura-api

Usage

import { Oura } from "@pinta365/oura-api";

const sandboxClient = new Oura({ useSandbox: true });

That's it! You can now start making API calls using the sandboxClient object, just like you would with a regular client. Explore the JSR documentation for possible methods.

Example:

try {
  const dailyActivityData = await sandboxClient.getDailyActivityDocuments(
    "2024-01-01",
    "2024-01-10",
  );
  console.log(dailyActivityData);
} catch (error) {
  console.error("Error fetching data:", error);
}

Important Note:

• Limited Endpoints: Not all Oura API endpoints are supported in the sandbox. Please refer to the Oura API documentation for a list of available sandbox endpoints.

Start Building Today!

The Oura API library with its sandbox environment makes Oura Ring data integration accessible to everyone. Start experimenting, testing, and building your next great application today!

You can also try the sandbox in the browser via this simple Deno playground.

You can find the library source code on GitHub.

Let us know if you have any questions or feedback!

In programming, immutability means an object's state cannot be changed after it's created. This can help prevent accidental modifications and make your code more predictable. JavaScript provides a few ways to achieve this, with freeze() and seal() being two prominent methods.

Object.freeze(): Preventing Object Modifications

Object.freeze() takes your object and encases it in an unbreakable shell. Here's what happens:

1. Non-extensible: You cannot add new properties to the object.
2. Non-configurable: Existing properties cannot be deleted or have their attributes (configurable, writable, enumerable) changed.
3. Non-writable: Values of existing properties cannot be modified.

Example: Frozen Settings

const appConfig = Object.freeze({
  theme: "dark",
  version: "1.0.0",
  maxItems: 100,
});

appConfig.theme = "light"; // Fails silently
appConfig.language = "en"; // Fails silently
delete appConfig.version; // Fails silently

Here, appConfig is like a locked-down configuration file. Even trying to change its properties directly has no effect.

Object.seal(): Preventing Property Addition and Deletion

Object.seal() offers a slightly less restrictive form of immutability. Here's how it differs from freeze():

1. Non-extensible: Just like freeze(), you cannot add new properties.
2. Non-configurable: Existing properties cannot be deleted or have their attributes changed.
3. Writable: The values of existing properties can still be modified.

Example: Modifiable Data Record

const userProfile = Object.seal({
  name: "Alice",
  email: "alice@example.com",
  isAdmin: false,
});

userProfile.email = "newalice@example.com"; // Succeeds
userProfile.age = 30; // Fails silently
delete userProfile.isAdmin; // Fails silently

Here, userProfile is like a sealed record where you can update the information but not add new fields or remove existing ones.

How to Choose: freeze() or seal()?

• Object.freeze(): Use when you need absolute immutability for values that should never change under any circumstances. Think of configuration settings, mathematical constants, or any data you want to protect from accidental modifications.

• Object.seal(): Use when you want a fixed structure for your object but need the flexibility to update the values of existing properties. This is suitable for data records, entities, or objects where the shape is fixed, but the data it holds might evolve over time.

Important Considerations:

• Shallow vs. Deep Immutability: Both freeze() and seal() provide shallow immutability. If your object has nested objects or arrays, those nested structures are not automatically made immutable. You'd need to recursively apply freeze() or seal() to achieve deep immutability.

• Object.isFrozen() and Object.isSealed(): You can use these functions to check if an object has been frozen or sealed.

Object.isFrozen(appConfig); // true
Object.isSealed(userProfile); // true

In Conclusion

Immutability is a powerful concept in JavaScript, and Object.freeze() and Object.seal() are valuable tools to help you enforce it. Choose the right one based on your specific needs, and remember to handle nested structures for deep immutability. By embracing immutability, you can make your code more robust, predictable, and easier to reason about.

Oura API Library

The Oura API Library is a cross-platform solution designed to make Oura Ring data integration a breeze. Source code available at GitHub.

Key Features

• Simplified Access: Providing clean and easy-to-use methods for fetching your Oura data.
• Cross-Platform Compatibility: Write once, run anywhere! Our library works seamlessly across Deno, Bun, and Node.js environments.
• Sandbox Support: Safely test your integration using the Oura sandbox environment without affecting real user data.
• TypeScript Support: Enjoy the benefits of static typing and improved code maintainability.

Installation

# For Deno
deno add @pinta365/oura-api

# For Bun
bunx jsr add @pinta365/oura-api

# For Node.js
npx jsr add @pinta365/oura-api

Quick Start

import { Oura } from "@pinta365/oura-api";

const accessToken = "YOUR_ACCESS_TOKEN";
const ouraClient = new Oura(accessToken); // Or use options object for sandbox

try {
  const dailyActivityData = await ouraClient.getDailyActivityDocuments(
    "2023-01-01",
    "2023-01-10",
  );
  console.log(dailyActivityData);
} catch (error) {
  console.error("Error fetching data:", error);
}

Using the Sandbox for Testing

You can use the sandbox without user account or access token, perfect for development and testing.

const ouraSandboxClient = new Oura({ useSandbox: true }); // No access token needed for sandbox

You can try the sandbox in the browser via this simple Deno playground.

Note: Not all Oura API endpoints are available in the sandbox environment. Refer to the Oura documentation for details.

See documentation for more examples and explainations

Real-World Applications

• Personalized Health Dashboards: Create custom dashboards to visualize and track Oura data. See a very simple example on this blog post.
• Fitness and Wellness Apps: Enhance your apps with detailed sleep and activity insights.
• Research and Data Analysis: Easily collect and analyze Oura data for academic or commercial purposes.

Documentation

Complete library documentation and examples can be found at the JSR documentation page.

Get Started Today!

Start building amazing applications with Oura Ring data. We can't wait to see what you create!

GitHub repository

Let us know if you have any questions or need further assistance!

@cross/jwt

Introducing @cross/jwt, a cross-platform JWT library designed to bring secure, consistent, and easy-to-use JWT handling to your projects. Source code available at GitHub.

Key Features for Robust Security

• Strong Cryptography: @cross/jwt supports a range of industry-standard signing algorithms, including HMAC, RSA, RSA-PSS, and ECDSA, ensuring the integrity and authenticity of your tokens.
• Cross-Platform Confidence: Your security practices don't need to change between Deno, Bun, and Node.js environments. @cross/jwt provides the same robust functionality everywhere.
• Intuitive API: Security shouldn't be complex. The library's clear functions for signing, verifying, and managing keys make it easy to integrate JWTs correctly.
• Flexible Options: Customize token behavior, such as expiration and validation rules, using JWTOptions.

Installation

# For Deno
deno add @cross/jwt

# For Bun
bunx jsr add @cross/jwt

# For Node.js
npx jsr add @cross/jwt

API at a glance

See detailed documentation on https://jsr.io for the complete API, but here's a quick look with a simple HMAC Example:

import { signJWT, validateJWT } from "@cross/jwt";

// A base64-encoded secret.
const secret = "y69uNvF9lbHE2disEqeYCBYOUmzJvr75txhxbUL5W0k=";
// Generate and sign the JWT.
const token = await signJWT({ userId: 123 }, secret);
// Verify and validate it.
const data = await validateJWT(token, secret);

Real-World Use Cases

1. Secure API Authentication: Implement bearer token authentication in your REST APIs, ensuring that only requests with valid JWTs are authorized.
2. Microservice Communication: Use JWTs to securely pass context and authorization data between microservices, especially across different runtimes.
3. Distributed Data Sharing: Transmit sensitive data (e.g., configuration, limited-access resources) between applications in a secure and verifiable format.

Oak example (Simplified)

import { Application } from "jsr:@oak/oak/application";
import { signJWT, validateJWT } from "@cross/jwt";
import type { JWTPayload } from "@cross/jwt";

const app = new Application();
// Replace with a secure secret
const secret = "y69uNvF9lbHE2disEqeYCBYOUmzJvr75txhxbUL5W0k=";

// ... Your routes and other logic ...

1. Login Route

app.use(async (ctx, next) => {
  if (ctx.request.url.pathname === '/login' && ctx.request.method === 'POST') {
     // ... your login validation logic ...
     
     const payload: JWTPayload = {
       userId: 123, 
       role: "user" 
     };
     const jwt = await signJWT(payload, secret);
     ctx.response.body = { token: jwt };
   } else {
     await next();
   }
});

2. Authentication Middleware

const authMiddleware = async (ctx: any, next: any) => {
  const authHeader = ctx.request.headers.get('Authorization');
  if (!authHeader) {
    ctx.response.status = 401;  // Unauthorized
    return; 
  }

  const token = authHeader.split(' ')[1];  // Assuming 'Bearer token' format
  try {
    const payload = await validateJWT(token, secret) as JWTPayload; 

    // Attach user data to the context for downstream routes/logic
    ctx.state.user = { 
      id: payload.userId,
      role: payload.role
    }; 

    await next();
  } catch (error) {
    ctx.response.status = 401; // Unauthorized
  }
};

3. Protected Route

app.use(authMiddleware);

app.use((ctx) => {
  if (ctx.request.url.pathname === "/protected") {
    // Access user info
    const userId = ctx.state.user.id;
    const userRole = ctx.state.user.role;

    // ... logic using the authenticated user data ...
  }
});

console.log("Server running on port 8000");
await app.listen({ port: 8000 });

Explanation

1. Login: Simulates a login process. Upon success, a JWT containing user information is generated.
2. Middleware: Intercepts requests, extracts the JWT from the 'Authorization' header, and validates it. Unauthorized requests get a 401 response.
3. Protected Route: Routes using the authMiddleware now require a valid JWT to access.

Important Notes:

• Store JWTs securely on the client: Typically in cookies (with HttpOnly flag).
• Secret Management: Use environment variables and proper secret handling.
• Error Handling: Implement more detailed error responses in production.

A beginner's guide to generators

• Generators are special functions marked with an asterisk (*).
• Instead of the return keyword, they use yield to pause execution and return a value.
• Each time a generator's next() method is called, it resumes from where it left off, until it's finished.

Why use generators?

1. Efficiently Handling Large or On-Demand Data: Generators excel at handling infinitely generated sequences or processing data in chunks without needing to store entire datasets in memory. This is perfect for scenarios with massive files, real-time data streams, or computationally intensive value generation.

2. Resource Management and Control: Unlike regular functions, generators enable fine-grained control over when computations happen and when resources are released. This can help optimize pipelines where you need to manage intermediate results without sacrificing memory efficiency.

3. Cleaner Iterations in Special Cases: While generators are iterable, their true power lies in custom iterators where you want logic inside the iteration itself, rather than iterating over a pre-existing collection. This is particularly useful for building recursive structures or complex sequences.

4. Creating Coroutines (Advanced): Generators provide a foundation for implementing coroutines. Coroutines are like functions that can pause, yield control to each other, and resume seamlessly. This enables cooperative multitasking – switching between tasks without the complexity of full-blown threads.

A simple example

function* numberGenerator() {
  yield 1;
  yield 2;
  yield 3;
}

const generator = numberGenerator();

console.log(generator.next().value); // Output: 1
console.log(generator.next().value); // Output: 2
console.log(generator.next().value); // Output: 3
console.log(generator.next().value); // Output: undefined (generator is done)

Real-world use case

Imagine fetching posts from a social media API. Instead of trying to load all the posts at once, a generator could:

1. Fetch a set number of posts and yield them.
2. Pause and wait for a user's request to see more.
3. Resume, fetch the next batch, and yield those.

Key takeaways so far

• Generators introduce the concept of pausing and resuming code execution.
• They improve memory management and streamline asynchronous flows.
• If you're dealing with large datasets, asynchronous patterns, or need custom iterators, generators are worth exploring.

More advanced techniques

If you've grasped the basics of JavaScript generators (if not, consider revisiting the idea of yield and next()), it's time to level up! In this post, we'll explore how generators can supercharge your programming with advanced patterns:

1. Two-way communication with yield

• Remember, yield doesn't only output values. You can send values back into a running generator using generator.next(value).
• Use case: Creating dialog-like interactions; the external code controls the flow of the generator by feeding data back to it.

Example:

function* questionGenerator() {
  const name = yield "What's your name?";
  const quest = yield `Hi ${name}, what is your quest?`;
  yield `To seek the ${quest}!`;
}

const generator = questionGenerator();

console.log(generator.next().value); // "What's your name?"
console.log(generator.next("Arthur").value); // "Hi Arthur, what is your quest?"
console.log(generator.next("Holy Grail").value); // "To seek the Holy Grail!"

2. Delegating execution with yield*

• yield* lets you delegate control to another generator (or iterable).
• Use case: Composing complex generators from smaller, more manageable ones.

Example:

function* numberGenerator() {
  yield 1;
  yield 2;
}

function* alphabetGenerator() {
  yield "a";
  yield "b";
}

function* combinedGenerator() {
  yield* numberGenerator();
  yield* alphabetGenerator();
}

for (const value of combinedGenerator()) {
  console.log(value); // Output:  1, 2, 'a', 'b'
}

3. Error handling within generators

Generators offer flexibility when it comes to error handling. You can use both traditional try...catch blocks and carefully control error propagation using yield and generator.throw():

A. Inside the Generator: try...catch

• Place potentially error-prone code within a try...catch block just as you would in regular functions.
• Example:

function* riskyGenerator() {
  try {
    const someData = yield fetchData(); // Assume fetchData() could throw an error
    // Proceed with more logic if no error
  } catch (error) {
    yield `An error occurred: ${error.message}`;
  }
}

B. Outside the Generator: generator.throw()

• The code consuming a generator can signal an error back into the generator using generator.throw(error).
• This will cause an exception to be raised at the point of the current yield inside the generator.
• Example:

const generator = riskyGenerator();
let result = generator.next();

if (!result.value.isValid()) {
  generator.throw(new Error("Invalid data received"));
}

C. Choosing Between yield and throw

• Yielding Errors:
  • Provides the caller of the generator more control to decide how to handle the error.
  • Gives the potential to recover from the error within the generator, depending on its design.
• Throwing Errors:
  • Stops execution of the generator immediately.
  • Useful for signaling unrecoverable errors, where the generator cannot meaningfully continue.

Illustrative Example:

function* processFile(filename) {
  // ... file opening and setup ...
  try {
    for await (const line of file) {
      if (isInvalidLine(line)) {
        yield { error: "Invalid Line", lineNumber };
      } else {
        yield processValidLine(line);
      }
    }
  } catch (error) {
    generator.throw(new Error(`Critical file error: ${error.message}`));
  }
}

Explanation: The example above uses a mix:

• Non-critical line errors are yield-ed, allowing the caller to filter/log them while proceeding.
• Critical file errors (e.g., permissions, corrupt file) are throw-n, as the generator cannot continue.

Generators give you fine-grained control over how your code responds to errors. Choose the technique that aligns with the desired error handling strategy for your specific use case.

4. Generators and Promises:

async and await provide a beautifully clear way to work with promises and generators:

• async Functions: When you mark a function as async, it automatically returns a promise. Inside an async function, you can use the await keyword.
• await Magic: The await keyword pauses the execution of the async function until a promise resolves. It then unwraps the resolved value and lets your code continue as if it were dealing with synchronous code.

Example: Fetching API Data

Let's see how this works with a simplified API fetching example:

async function* fetchPostsPage(pageNumber) {
  const response = await fetch(
    `https://api.example.com/posts?page=${pageNumber}`,
  );
  const data = await response.json();
  yield data;
}

async function displayPosts() {
  let currentPage = 1;

  while (true) {
    const generator = fetchPostsPage(currentPage);
    const result = await generator.next();
    const posts = result.value;

    if (posts.length === 0) {
      // No more posts
      break;
    }

    // Process and display the fetched posts
    for (const post of posts) {
      // ... display post logic here ...
    }

    currentPage++;
  }
}

Notice how the code within displayPosts reads almost like synchronous code, even though it's dealing with asynchronous operations under the hood!

Error Handling

Error handling within async functions and generators works smoothly with try...catch blocks:

async function* riskyDataFetch() {
  try {
    const response = await fetch("https://nonexistent-api.example.com/data"); // Forced error
    const data = await response.json();
    yield data;
  } catch (error) {
    yield error;
  }
}

async function handleFetch() {
  const generator = riskyDataFetch();
  const result = await generator.next();

  if (result.done) {
    console.error("An error occurred:", result.value);
  } else {
    console.log("Data:", result.value);
  }
}

Debugging is the process of finding and fixing errors or "bugs" in your code. It's an essential skill for any programmer, akin to a detective unraveling a complex mystery. While the promise of bringing your ideas to life through code is exhilarating, the path to programming proficiency is not always smooth. In fact, it's riddled with frustrating debugging challenges that can test the mettle of even the most ardent beginners.

In this article, we'll dive into the debugging dilemma, exploring why so many aspiring programmers give up when faced with real code debugging. We'll dissect the initial excitement of learning to code, the harsh reality of debugging, the learning plateau, and the common reasons why some learners throw in the towel. But fear not, for we'll also offer strategies to overcome these challenges and encourage resilience in your coding journey.

So, let's journey through the highs and lows of programming, the thrill of creation, and the vexing world of debugging—a true rite of passage for aspiring coders.

The Initial Excitement of Learning Programming

The initial stages of learning programming are akin to setting out on a grand adventure. Armed with a fresh IDE (Integrated Development Environment), a slew of online tutorials, and boundless curiosity, beginners often feel invincible. It's the era of "Hello World!" programs, where the smallest snippet of code can produce a sense of accomplishment that's hard to describe.

The allure of programming lies in its creative potential. The ability to translate ideas into lines of code that can perform tasks, solve problems, and entertain is a powerful draw. Many newcomers are thrilled at the prospect of building websites, mobile apps, games, or automating everyday tasks.

In these early stages, the world of programming seems full of promise, excitement, and endless opportunities. The euphoria of writing your first lines of code and seeing them execute successfully is intoxicating. It's like having the keys to a digital kingdom, where you're the master builder and architect of your creations.

The Reality of Debugging

Debugging, in essence, is the process of hunting down and exterminating bugs—those elusive errors and glitches that lurk within your code, causing it to misbehave or crash. Debugging can be an arduous task, often resembling a puzzle with missing pieces or a maze with unforeseen dead ends.

As beginners transition from simple "Hello World!" programs to more complex projects, they quickly discover that coding isn't just about writing instructions for a computer to follow. It's also about deciphering cryptic error messages, identifying logical flaws, and patiently tracing the execution flow of their programs.

Common debugging scenarios include:

1. Syntax Errors: These errors occur when your code violates the rules of the programming language. They often manifest as red squiggly lines and cryptic error messages that leave beginners scratching their heads.

2. Logic Bugs: Logic bugs are the trickiest, as they involve flawed reasoning in your code. Programs may run without errors, but they produce incorrect results due to logical errors.

3. Runtime Errors: These occur when a program is running and encounters issues. They can lead to crashes, unhandled exceptions, or unexpected behavior.

The frustration that accompanies debugging can be overwhelming. It's not uncommon to spend hours hunting for a single misplaced semicolon or an elusive missing parenthesis. For many beginners, this is the first major test of their patience and problem-solving skills.

The Learning Plateau

The learning plateau is a phase in the programming journey where initial excitement gives way to a sense of stagnation. It's a period when the complexities of programming become more apparent, and progress seems to slow down or even come to a halt.

During this phase, learners may begin to doubt their abilities and question whether they have what it takes to become proficient programmers. The initial thrill of coding can fade as they grapple with increasingly complex projects and debugging challenges. It's a crucial turning point where many aspiring programmers face a make-or-break decision.

In reality, the learning plateau is a natural part of the programming journey. It's the point where the initial burst of enthusiasm needs to be supplemented with perseverance and a willingness to confront debugging head-on. It's where the distinction between those who persevere and those who give up often becomes clear.

Common Reasons for Giving Up

Unfortunately, not all beginners make it past the learning plateau. There are several common reasons why some aspiring programmers throw in the towel.

1. Lack of Patience: Debugging can be a time-consuming process that demands patience. Some beginners become frustrated when they can't immediately solve a problem, leading to a loss of interest.

2. Imposter Syndrome: Many learners experience imposter syndrome, a feeling of not being "good enough" compared to more experienced developers. This self-doubt can erode confidence and motivation.

3. Overwhelm: The vast landscape of programming languages, libraries, and frameworks can be overwhelming, especially for beginners. It's easy to feel lost in the sea of options and information.

4. Unrealistic Expectations: Some newcomers enter the world of programming with unrealistic expectations, thinking they can master it overnight. When they realize the depth of the subject, they may become disheartened.

These reasons, individually or in combination, can lead to a sense of defeat. But the truth is, they are all challenges that can be overcome with the right mindset and strategies.

Strategies to Overcome Debugging Challenges

While the debugging dilemma is real, it's important to know that it's not an insurmountable obstacle. There are strategies and approaches that can help aspiring programmers overcome these challenges and stay on the path to coding proficiency.

1. Seek Help: Don't hesitate to reach out for assistance when you're stuck. Online communities, forums, and programming mentors can provide valuable guidance and solutions.

2. Break It Down: Divide complex problems into smaller, more manageable parts. This makes debugging less daunting and allows you to tackle one issue at a time.

3. Embrace Failure: Understand that making mistakes and encountering bugs is an inherent part of programming. Every bug you conquer is a lesson learned.

4. Continuous Learning: Programming is a lifelong journey. Stay curious and committed to learning, and don't be discouraged by temporary setbacks.

5. Mentorship: Consider finding a mentor who can offer guidance, share experiences, and provide insights into effective debugging techniques.

By adopting these strategies and fostering a mindset of perseverance, you can navigate the debugging dilemma with greater confidence and resilience.

Conclusion: Encouraging Resilience

In this exploration of the debugging dilemma and the challenges faced by beginners in the world of programming, it's important to recognize that the road to coding proficiency is rarely a straight line. It's more like a winding path with obstacles, detours, and occasional setbacks. However, it's precisely these challenges that can shape you into a skilled and resilient programmer.

As you've learned, the initial excitement of coding often gives way to the reality of debugging—a process that can test your patience and problem-solving abilities. The learning plateau can be disheartening, and common hurdles like frustration, imposter syndrome, overwhelm, and unrealistic expectations can make you question your journey.

But here's the good news: every programmer, from the beginners to the seasoned experts, has faced these challenges at some point. What sets successful programmers apart is their ability to persist in the face of adversity. They understand that debugging is not a sign of incompetence; it's a badge of honor earned through trial and error.

Closing Thoughts

1. Embrace the Process: Debugging is not a sign of failure; it's a crucial part of the coding process. Each bug you conquer is a step forward in your programming journey.

2. Learn from Mistakes: Every error, every setback, and every frustrating bug is an opportunity to learn and grow as a programmer. Take the lessons from each experience and apply them to future projects.

3. Seek Support: Don't hesitate to seek help when you're stuck. Join programming communities, connect with peers, and consider finding a mentor who can guide you through the challenges.

4. Stay Curious: Programming is a field that's constantly evolving. Maintain your curiosity and explore new technologies, languages, and frameworks. There's always something new to discover.

5. Persevere: The path to becoming a proficient programmer may have its ups and downs, but it's the determination to persevere that ultimately leads to success.

Remember, the debugging dilemma is not unique to you; it's a shared experience among programmers worldwide. In fact, it's these very challenges that make the coding journey so rewarding. The satisfaction of solving a complex problem, fixing a stubborn bug, or creating a functional piece of software is immeasurable.

So, if you're a beginner feeling frustrated by debugging, know that you're not alone. Keep pushing forward, keep learning, and keep coding. The programming world is waiting for your unique contributions and innovations, and the debugging challenges you overcome today will be the stepping stones to your success tomorrow.

In the grand tapestry of programming, each bug fixed and each problem solved adds to your expertise and shapes you into a resilient and capable coder. Embrace the debugging dilemma, for it's an integral part of your journey to becoming a proficient programmer.

Happy coding, and may your debugging adventures be both challenging and rewarding!

Additional Tips

Before we conclude, here are some additional tips and parting thoughts to carry with you on your programming journey:

1. Celebrate Your Wins: Whether it's fixing a bug, completing a project, or learning a new concept, take a moment to celebrate your achievements, no matter how small they may seem.

2. Stay Curious: The world of programming is vast and ever-changing. Maintain your curiosity and explore new technologies, languages, and frameworks. There's always something new to discover.

3. Build Projects: Practical application is one of the most effective ways to learn. Create personal projects that challenge and inspire you. These projects not only reinforce your skills but also serve as a portfolio to showcase your abilities.

4. Share Your Knowledge: As you progress in your programming journey, consider giving back to the community. Share your experiences, write tutorials, and help fellow learners. Teaching others is a powerful way to solidify your understanding.

5. Take Breaks: Programming can be mentally taxing. Don't forget to take regular breaks to recharge your mind and prevent burnout. A fresh perspective often leads to better problem-solving.

6. Network and Collaborate: Building connections in the programming community can open doors to new opportunities. Collaborate with others on projects, attend meetups or conferences, and participate in open-source initiatives.

7. Keep Learning: Learning in programming is a continuous process. Stay updated with industry trends, take online courses, and consider pursuing advanced studies or certifications when you're ready.

In conclusion, the debugging dilemma is not a barrier to your programming success; it's a rite of passage. As you navigate the highs and lows of this journey, remember that every challenge you face is an opportunity for growth. Embrace the debugging process, stay persistent, and let your passion for coding drive you forward.

The world of technology and programming is waiting for your contributions, innovations, and solutions. Keep coding, keep learning, and never lose sight of your programming goals.