DEV Community: jsmanifest

Teaching AI Agents to Batch React State Updates with ESLint

jsmanifest — Sat, 10 Jan 2026 00:00:00 +0000

While I was reviewing some React components generated by Claude the other day, I noticed a pattern that made me pause. The AI had created a perfectly functional settings panel with validation, loading states, error handling, and auto-save—but it used seven separate useState calls. On the surface, everything worked. But I knew this was a performance time bomb waiting to explode.

Little did I know, this discovery would lead me down a rabbit hole of teaching AI agents to write better React code automatically. In this post, I'll show you how to prevent AI coding assistants from creating useState render waterfalls by combining custom ESLint rules with Claude-specific instructions.

By the end, you'll have a copy-paste ESLint rule and a Claude configuration that enforces useImmer for batched state updates—catching the problem at lint time and teaching your AI assistant to use better patterns from the start.

1. The Problem: When AI Agents Generate useState Waterfalls

Here's what the AI-generated component looked like:

// ❌ AI-generated component with multiple useState calls
function SettingsPanel() {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [confirmPassword, setConfirmPassword] = useState('')
  const [saveStatus, setSaveStatus] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
  const [errorMessage, setErrorMessage] = useState<string | null>(null)
  const [isDirty, setIsDirty] = useState(false)
  const [lastSaved, setLastSaved] = useState<Date | null>(null)

  const handleSave = async () => {
    setSaveStatus('saving')
    setErrorMessage(null)
    setIsDirty(false)

    try {
      await api.saveSettings({ email, password })
      setSaveStatus('saved')
      setLastSaved(new Date())
    } catch (error) {
      setSaveStatus('error')
      setErrorMessage(error.message)
    }
  }

  // Component JSX...
}

The problem? In handleSave(), we're calling four separate state setters in rapid succession. Even though React 18 introduced automatic batching, there are edge cases where this can still trigger multiple renders—especially in async callbacks, effects, and event handlers with complex timing.

I cannot stress this enough: each setState call is a potential render cycle. Seven pieces of state means seven opportunities for React to decide it needs to re-render your component tree.

2. Understanding React Render Batching (And Its Limits)

Let's look at what's actually happening under the hood:

// ❌ Demonstrating the render waterfall
function ProblematicComponent() {
  const [count, setCount] = useState(0)
  const [status, setStatus] = useState('idle')
  const [data, setData] = useState(null)

  useEffect(() => {
    console.log('Component rendered!')
  })

  const fetchData = async () => {
    console.log('Starting fetch...')

    setStatus('loading')  // Render #1
    setCount(c => c + 1)  // Render #2

    const result = await api.fetch()

    setData(result)       // Render #3 (after Promise resolves)
    setStatus('success')  // Render #4
  }

  return (
    <div>
      <button onClick={fetchData}>Fetch</button>
      <p>Renders: {count}</p>
      <p>Status: {status}</p>
    </div>
  )
}

When you click the button, the console shows:

Starting fetch...
Component rendered!  // After setStatus('loading')
Component rendered!  // After setCount(c => c + 1)
Component rendered!  // After setData(result)
Component rendered!  // After setStatus('success')

React 18's automatic batching helps, but it's not magic. Updates in async callbacks (like after await) are not automatically batched together. Each state setter after the Promise resolves triggers its own render.

In other words, more state variables = more chances for render waterfalls. When I came across this in the AI-generated code, I realized we needed a systematic solution.

3. The Solution: useImmer for Batched Updates

Luckily we can consolidate all related state into a single object and use useImmer from the use-immer package. This gives us two massive benefits:

Single state object = single render cycle (one updateState() call, one render)
Immutable updates without spread operator hell (Immer handles the immutability)

Here's the refactored version:

// ✅ Refactored with useImmer - single state object
import { useImmer } from 'use-immer'

function SettingsPanel() {
  const [state, updateState] = useImmer({
    email: '',
    password: '',
    confirmPassword: '',
    saveStatus: 'idle' as 'idle' | 'saving' | 'saved' | 'error',
    errorMessage: null as string | null,
    isDirty: false,
    lastSaved: null as Date | null,
  })

  const handleSave = async () => {
    // Batch all pre-save updates into ONE render
    updateState((draft) => {
      draft.saveStatus = 'saving'
      draft.errorMessage = null
      draft.isDirty = false
    })

    try {
      await api.saveSettings({
        email: state.email,
        password: state.password
      })

      // Batch all post-save updates into ONE render
      updateState((draft) => {
        draft.saveStatus = 'saved'
        draft.lastSaved = new Date()
      })
    } catch (error) {
      // Single render for error state
      updateState((draft) => {
        draft.saveStatus = 'error'
        draft.errorMessage = error.message
      })
    }
  }

  // Component JSX...
}

What changed?

Seven useState calls → One useImmer call
Four separate setState calls in handleSave → Three batched updateState calls (pre-save, success, error)
Potential 4+ renders → Maximum 3 renders (and usually just 2)

The beauty of Immer is that you write code that looks like you're mutating the state (draft.saveStatus = 'saving'), but Immer produces a new immutable object behind the scenes. No more spread operator pyramids!

4. Advanced useImmer Patterns with Lodash

For complex state with nested objects, you can combine useImmer with lodash utilities for even cleaner updates:

// ✅ Advanced useImmer with lodash helpers
import { useImmer } from 'use-immer'
import get from 'lodash/get.js'
import set from 'lodash/set.js'
import assign from 'lodash/assign.js'

function ComplexForm() {
  const [state, updateState] = useImmer({
    user: {
      profile: {
        firstName: '',
        lastName: '',
        email: '',
      },
      settings: {
        theme: 'light',
        notifications: true,
      }
    },
    meta: {
      isDirty: false,
      lastSaved: null,
    }
  })

  // Pattern #1: Multiple shallow updates in one line
  const handleMetaUpdate = () => {
    updateState((draft) => void assign(draft.meta, {
      isDirty: true,
      lastSaved: new Date()
    }))
  }

  // Pattern #2: Deep nested updates
  const handleEmailChange = (email: string) => {
    updateState((draft) => set(draft, 'user.profile.email', email))
  }

  // Pattern #3: Safe nested reads
  const userEmail = get(state, 'user.profile.email', '')
  const isDirty = get(state, 'meta.isDirty', false)

  return <div>{/* Form JSX */}</div>
}

Why this matters: When AI agents generate forms or complex UIs, they often create separate state variables for every field. With this pattern, you can have deeply nested state that updates atomically—all with a single render.

5. Building the ESLint Rule: Catching the Pattern Automatically

Now here's where it gets interesting. We can teach ESLint to detect when developers (or AI agents) are using multiple useState calls that should be consolidated into useImmer.

First, let's configure ESLint to enable our custom rule:

// .eslintrc.json
{
  "plugins": ["@your-org/eslint-plugin"],
  "rules": {
    "@your-org/use-immer-state": ["warn", {
      "minProperties": 3,
      "minUseStateCount": 4,
      "ignoreArrays": false,
      "ignorePrimitiveArrays": true
    }]
  }
}

What these options mean:

minProperties: 3 - Warn if useState is initialized with an object containing 3+ properties
minUseStateCount: 4 - Warn if a component has 4+ useState calls
ignoreArrays: false - Don't ignore array state
ignorePrimitiveArrays: true - But DO ignore primitive arrays like string[]

6. Implementing the ESLint Rule: Detection Logic

Here's a simplified version of the ESLint rule to understand the core concept:

// Simplified ESLint visitor pattern
export const useImmerState = {
  meta: {
    type: 'suggestion',
    messages: {
      preferImmer: 'Consider using useImmer instead of useState for complex state objects.',
      preferImmerMultiple: 'Multiple useState calls detected. Consider consolidating into useImmer.',
    },
  },

  create(context) {
    const scopeUseStateCount = new Map()

    return {
      CallExpression(node) {
        // Only check useState calls
        if (node.callee.name !== 'useState') return

        // Track how many useState calls in this component
        const functionScope = getFunctionScope(node)
        const count = (scopeUseStateCount.get(functionScope) || 0) + 1
        scopeUseStateCount.set(functionScope, count)

        // Warn if too many useState in same component
        if (count >= 4) {
          context.report({
            node,
            messageId: 'preferImmerMultiple',
          })
        }

        // Check if useState is initialized with a large object
        const initialState = node.arguments[0]
        if (initialState?.type === 'ObjectExpression') {
          const propCount = initialState.properties.length
          if (propCount >= 3) {
            context.report({
              node,
              messageId: 'preferImmer',
            })
          }
        }
      },
    }
  },
}

The detection strategy:

Visit every function call in the AST
Filter for useState calls only
Track how many useState calls exist in the current component scope
Check if useState is initialized with an object with 3+ properties
Report a warning when thresholds are exceeded

In other words, ESLint walks the abstract syntax tree (AST) of your code—think of it like a family tree of your code structure—and checks each useState call against our rules.

7. Full ESLint Rule Implementation

Here's the complete production-ready implementation with all edge cases handled:

// packages/eslint-plugin/src/rules/use-immer-state.js
/** @type {import('eslint').Rule.RuleModule} */
export const useImmerState = {
  meta: {
    type: 'suggestion',
    docs: {
      description: 'Suggest useImmer for complex state instead of useState with objects/arrays',
      recommended: false,
    },
    messages: {
      preferImmer: 'Consider using useImmer instead of useState for complex state objects. Import from "use-immer" package.',
      preferImmerArray: 'Consider using useImmer instead of useState for array state. Import from "use-immer" package.',
      preferImmerMultiple: 'Multiple related useState calls detected. Consider consolidating into a single useImmer state object.',
    },
    schema: [
      {
        type: 'object',
        properties: {
          minProperties: {
            type: 'integer',
            minimum: 1,
            description: 'Minimum object properties to trigger warning (default: 3)',
          },
          minUseStateCount: {
            type: 'integer',
            minimum: 2,
            description: 'Minimum useState calls in same scope to suggest consolidation (default: 4)',
          },
          ignoreArrays: {
            type: 'boolean',
            description: 'Whether to ignore array state (default: false)',
          },
          ignorePrimitiveArrays: {
            type: 'boolean',
            description: 'Ignore arrays of primitives like string[] (default: true)',
          },
        },
        additionalProperties: false,
      },
    ],
  },

  create(context) {
    const options = context.options[0] || {}
    const minProperties = options.minProperties || 3
    const minUseStateCount = options.minUseStateCount || 4
    const ignoreArrays = options.ignoreArrays || false
    const ignorePrimitiveArrays = options.ignorePrimitiveArrays !== false

    const scopeUseStateCount = new Map()

    function getFunctionScope(node) {
      let current = node
      while (current) {
        if (
          current.type === 'FunctionDeclaration' ||
          current.type === 'FunctionExpression' ||
          current.type === 'ArrowFunctionExpression'
        ) {
          return current
        }
        current = current.parent
      }
      return null
    }

    function isPrimitiveArrayType(typeAnnotation) {
      if (!typeAnnotation) return false

      if (
        typeAnnotation.type === 'TSTypeReference' &&
        typeAnnotation.typeName.name === 'Array'
      ) {
        const typeParam = typeAnnotation.typeParameters?.params?.[0]
        if (typeParam && isPrimitiveType(typeParam)) return true
      }

      if (typeAnnotation.type === 'TSArrayType') {
        return isPrimitiveType(typeAnnotation.elementType)
      }

      return false
    }

    function isPrimitiveType(typeNode) {
      if (!typeNode) return false
      const primitiveTypes = ['TSStringKeyword', 'TSNumberKeyword', 'TSBooleanKeyword']
      return primitiveTypes.includes(typeNode.type)
    }

    function countObjectProperties(node) {
      if (node.type !== 'ObjectExpression') return 0
      return node.properties.filter(p => p.type === 'Property').length
    }

    function isArrayOfPrimitives(node) {
      if (node.type !== 'ArrayExpression') return false
      if (node.elements.length === 0) return true
      return node.elements.every(el =>
        el && (el.type === 'Literal' || el.type === 'Identifier')
      )
    }

    return {
      CallExpression(node) {
        if (node.callee.type !== 'Identifier' || node.callee.name !== 'useState') return

        const scope = getFunctionScope(node)
        if (scope) {
          const count = (scopeUseStateCount.get(scope) || 0) + 1
          scopeUseStateCount.set(scope, count)

          if (count === minUseStateCount) {
            context.report({ node, messageId: 'preferImmerMultiple' })
          }
        }

        const args = node.arguments
        if (args.length === 0) return

        const initialState = args[0]

        // Check for object state
        if (initialState.type === 'ObjectExpression') {
          const propCount = countObjectProperties(initialState)
          if (propCount >= minProperties) {
            context.report({ node, messageId: 'preferImmer' })
          }
          return
        }

        // Check for arrow function returning object (lazy init)
        if (initialState.type === 'ArrowFunctionExpression') {
          const body = initialState.body
          if (body.type === 'ObjectExpression') {
            const propCount = countObjectProperties(body)
            if (propCount >= minProperties) {
              context.report({ node, messageId: 'preferImmer' })
            }
          }
          if (body.type === 'BlockStatement') {
            const returnStmt = body.body.find(s => s.type === 'ReturnStatement')
            if (returnStmt?.argument?.type === 'ObjectExpression') {
              const propCount = countObjectProperties(returnStmt.argument)
              if (propCount >= minProperties) {
                context.report({ node, messageId: 'preferImmer' })
              }
            }
          }
          return
        }

        // Check for array state
        if (!ignoreArrays && initialState.type === 'ArrayExpression') {
          if (ignorePrimitiveArrays && isArrayOfPrimitives(initialState)) return

          if (node.parent?.type === 'VariableDeclarator') {
            const id = node.parent.id
            if (id.typeAnnotation) {
              const typeAnn = id.typeAnnotation.typeAnnotation
              if (isPrimitiveArrayType(typeAnn)) return
            }
          }

          if (initialState.elements.length > 0) {
            const hasComplexElements = initialState.elements.some(el =>
              el && (el.type === 'ObjectExpression' || el.type === 'ArrayExpression')
            )
            if (hasComplexElements) {
              context.report({ node, messageId: 'preferImmerArray' })
            }
          }
        }
      },
    }
  },
}

export default useImmerState

This rule handles:

✅ Multiple useState calls in the same component
✅ useState initialized with objects that have 3+ properties
✅ Lazy initialization via arrow functions
✅ TypeScript type annotations
✅ Arrays of complex objects (but ignores primitive arrays)
✅ Configurable thresholds via ESLint config

8. Teaching Claude with Custom Rules

Here's where it gets really powerful. ESLint catches the problem after the code is written, but we can teach Claude to use the right pattern proactively by adding instructions to .claude/rules/code-style.md:

## Use useImmer for Complex State

**RULE:** Single `useImmer({ state })` + one `updateState()` = 1 render. Multiple `useState` = N renders. ESLint enforces automatically (`@your-org/use-immer-state: error`).

\```

typescript
import get from 'lodash/get.js'
import set from 'lodash/set.js'
import assign from 'lodash/assign.js'
import { useImmer } from 'use-immer'

// ✅ CORRECT - Single state object with batched updates
const [state, updateState] = useImmer({
  password: '',
  saveStatus: 'idle',
  errorMessage: null
})

// Batch multiple updates
updateState((draft) => {
  draft.saveStatus = 'saving'
  draft.errorMessage = null
})

// Batch multiple updates with lodash #1 (one-line multiple key update)
updateState((draft) => void assign(draft, {
  saveStatus: 'saving',
  errorMessage: null
}))

// Nested updates with lodash #2
updateState((draft) => set(draft, 'nested.field', value))

// Read nested state
const value = get(state, 'nested.path', defaultValue)

// ❌ WRONG - Multiple useState = multiple renders
const [password, setPassword] = useState('')
const [saveStatus, setSaveStatus] = useState('idle')
// Calling 2 setters = 2 render passes!
\




**Why this works:** Claude reads project-specific rules from `.claude/rules/` and applies them when generating code. When I ask Claude to "create a settings form," it now automatically uses `useImmer` instead of multiple `useState` calls.

The combination is powerful:
- **ESLint** catches violations when code is written (by humans OR AI)
- **Claude rules** teach the AI to use the right pattern proactively

Make no mistake about it—this is how you scale good coding practices across your team AND your AI assistants.

![Detailed close-up of a hand pointing at colorful charts with a blue pen on wooden surface.](https://jsmanifest.s3.us-west-1.amazonaws.com/posts/enforcing-ai-agents-to-batch-react-state-updates-for-performance/performance-optimization-chart.jpg)

## 9. Integration Workflow: Putting It All Together

Here's how to set this up in your project:

**Step 1: Install dependencies**



```json
// package.json
{
  "devDependencies": {
    "@your-org/eslint-plugin": "^1.0.0",
    "use-immer": "^0.9.0",
    "lodash": "^4.17.21"
  }
}

Step 2: Configure ESLint

// .eslintrc.json
{
  "plugins": ["@your-org/eslint-plugin"],
  "rules": {
    "@your-org/use-immer-state": ["warn", {
      "minProperties": 3,
      "minUseStateCount": 4
    }]
  }
}

Step 3: Create Claude rule

# Create the rules directory
mkdir -p .claude/rules

# Add the code style rule
cat > .claude/rules/code-style.md << 'EOF'
## Use useImmer for Complex State

**RULE:** Single `useImmer({ state })` = 1 render. Multiple `useState` = N renders.

[Include the examples from section 8]
EOF

Step 4: Run ESLint and see it in action

$ npm run lint

  src/components/SettingsPanel.tsx
    12:7  warning  Multiple related useState calls detected. Consider consolidating into a single useImmer state object  @your-org/use-immer-state

✖ 1 problem (0 errors, 1 warning)

Step 5: Let Claude refactor it

Now when you ask Claude to "refactor SettingsPanel to follow our code standards," it reads the ESLint warnings AND the .claude/rules/code-style.md file, then automatically converts multiple useState to useImmer.

10. Real-World Before/After Comparison

Let me show you the difference this makes in a real production component.

Before (AI-generated with 7 useState):

Component file size: 245 lines
Number of useState calls: 7
Number of state setters called in handleSave: 4
Potential render cycles: 4+ (in async callback)
Lines of state initialization: 14 lines

After (with useImmer):

Component file size: 198 lines (19% reduction)
Number of useImmer calls: 1
Number of updateState calls in handleSave: 3 (batched)
Guaranteed render cycles: 3 maximum
Lines of state initialization: 9 lines (36% reduction)

Developer experience improvements:

✅ All related state co-located in one object
✅ No need to remember which setter goes with which state
✅ Refactoring state shape doesn't require updating 7 different variables
✅ ESLint catches the pattern automatically
✅ Claude generates the right pattern from the start

Performance wins:

✅ Fewer renders = smoother UI
✅ Less work for React's reconciliation algorithm
✅ Easier to optimize with React.memo (single state object dependency)

The numbers speak for themselves. But beyond the metrics, there's something powerful about teaching your tools—both ESLint and AI assistants—to guide you toward better patterns.

11. When NOT to Use This Pattern

I'd be doing you a disservice if I didn't mention when this pattern might NOT be the right choice:

1. Simple components with 1-2 primitive state values

// ❌ Overkill for simple state
const [isOpen, updateState] = useImmer({ isOpen: false })

// ✅ Just use useState
const [isOpen, setIsOpen] = useState(false)

2. Form libraries with their own state management

If you're using React Hook Form, Formik, or similar libraries, they manage state internally. Don't fight their abstractions.

3. Third-party components expecting specific APIs

Some components expect [value, setValue] from useState. Don't break their contracts.

4. Performance-critical animations

For frame-by-frame animations, sometimes you want granular control over which state updates trigger renders. In these cases, multiple useState calls (or useReducer) might be more appropriate.

5. State that truly belongs in separate concerns

// These are genuinely separate concerns
const [userData, setUserData] = useState(null)  // User profile
const [themePreference, setTheme] = useState('light')  // UI preference

Don't force-fit unrelated state into a single object just to satisfy the linter. Use your judgment.

Conclusion

And that concludes the end of this post! Let's recap what we covered:

The Problem: AI agents (and developers) often create React components with multiple useState calls, leading to render waterfalls and performance issues.

The Solution: Use useImmer to batch related state into a single object, guaranteeing single-render updates.

The Enforcement: Combine a custom ESLint rule that detects the anti-pattern with Claude-specific rules that teach the AI to use the right pattern proactively.

The Benefits:

🚀 Fewer renders = better performance
🧹 Cleaner code with consolidated state
🤖 Teachable AI that follows your standards
⚡ Automatic enforcement at lint time

The bigger picture? AI agents are powerful tools, but they need guard rails just like human developers. By combining automated linting with explicit instructions, we create systems that guide both humans and AI toward better patterns.

I hope you found this valuable and look out for more in the future!

5 Real-Life Problems Solved with Async Generators in JavaScript

jsmanifest — Tue, 06 Jan 2026 02:47:08 +0000

While I was looking over some data fetching code the other day, I came across a pattern that immediately caught my attention. A colleague was fetching paginated results from an API, and the code looked something like this massive recursive function with callbacks nested inside callbacks. It worked, but boy was it hard to follow.

That's when I remembered async generators—a feature I had learned about years ago but rarely used. Little did I know that pulling this tool out of my toolbox would completely transform how I think about handling streams of asynchronous data.

If you're like me and have heard of async generators but never quite found the right moment to use them, this post is for you. We're going to look at 5 real-world problems where async generators shine, and I promise you'll walk away with practical patterns you can use today.

What Are Async Generators?

Before we dive into the problems, let's quickly cover what async generators actually are. An async generator is a function that combines two powerful JavaScript features:

async function* myAsyncGenerator() {
  yield await fetchSomething()
  yield await fetchSomethingElse()
}

The async function* syntax tells JavaScript: "This function can pause, yield values, and also await promises." You consume it with for await...of:

for await (const value of myAsyncGenerator()) {
  console.log(value)
}

Here's what makes this so powerful: when you call an async generator function, it doesn't execute the body immediately. Instead, it returns an async iterator—an object with a next() method that returns a promise. Each time you call next() (or iterate with for await), the function runs until it hits a yield, pauses, and hands you the yielded value. The next call resumes right where it left off.

This "pause and resume" behavior is what enables all the elegant patterns we're about to explore.

Now let's see how this elegant pattern solves real problems.

1. Paginated API Fetching

This is probably the most common use case, and it's the one that opened my eyes to the power of async generators.

The Problem:

You need to fetch all results from an API that uses cursor-based pagination. The typical approach looks something like this:

// The "before" approach - messy and hard to follow
async function fetchAllUsers() {
  const allUsers = []
  let cursor = null

  do {
    const response = await fetch(`/api/users?cursor=${cursor || ''}`)
    const data = await response.json()
    allUsers.push(...data.users)
    cursor = data.nextCursor
  } while (cursor)

  return allUsers
}

// Usage - you have to wait for ALL users before processing any
const users = await fetchAllUsers()
users.forEach((user) => processUser(user))

The problem? You're loading everything into memory before you can do anything with it. If you have 10,000 users, you're holding all 10,000 in memory before processing a single one. Even worse, if you only needed the first 50 users that match some criteria, you've wasted time and bandwidth fetching all of them.

The Async Generator Solution:

async function* fetchUsers() {
  let cursor = null

  do {
    const response = await fetch(`/api/users?cursor=${cursor || ''}`)
    const data = await response.json()

    for (const user of data.users) {
      yield user
    }

    cursor = data.nextCursor
  } while (cursor)
}

// Usage - process users as they arrive!
for await (const user of fetchUsers()) {
  await processUser(user)
  // Memory efficient: only one user in memory at a time
}

Why This Works:

The magic here is in the yield statement inside the inner for loop. Each time we yield user, the generator pauses execution entirely. It doesn't fetch the next page until the consumer asks for more users. This creates a beautiful "pull-based" system—data only flows when you request it.

Here's what's happening step by step:

You start iterating with for await
The generator fetches the first page
It yields the first user and pauses
You process that user
The loop asks for the next user
The generator resumes, yields the second user, pauses again
When the page is exhausted, it fetches the next page
And so on...

The difference is night and day. With the async generator, you process each user as it arrives. If you need to stop early (maybe you found the user you were looking for), you can just break out of the loop. The generator immediately stops—no more API calls, no wasted memory.

for await (const user of fetchUsers()) {
  if (user.email === targetEmail) {
    console.log('Found them!')
    break // Generator stops here - no more fetching!
  }
}

I cannot stress this enough—once you start thinking in terms of async generators for pagination, you'll never go back.

2. Processing Large Files Line by Line

Here's a scenario that comes up all the time in Node.js: you need to process a large log file, CSV, or JSON Lines file.

The Problem:

// The naive approach - loads entire file into memory
const fs = require('fs').promises

async function processLogFile(filepath) {
  const content = await fs.readFile(filepath, 'utf-8')
  const lines = content.split('\n')

  for (const line of lines) {
    await processLine(line)
  }
}

If your log file is 2GB, you just loaded 2GB into memory. Your server will not be happy. In fact, on a typical Node.js process with default memory limits, this will crash with a heap out of memory error. And even if it doesn't crash, while you're waiting for the entire file to load, your application is doing nothing useful.

The Async Generator Solution:

const fs = require('fs')
const readline = require('readline')

async function* readLines(filepath) {
  const fileStream = fs.createReadStream(filepath)
  const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity,
  })

  for await (const line of rl) {
    yield line
  }
}

// Usage - memory stays flat regardless of file size
for await (const line of readLines('./massive-log-file.log')) {
  if (line.includes('ERROR')) {
    await alertTeam(line)
  }
}

Why This Works:

Under the hood, fs.createReadStream reads the file in small chunks (typically 64KB at a time). The readline interface takes those chunks and intelligently splits them into lines, handling the messy details of lines that span multiple chunks.

By wrapping this in an async generator, we get a clean abstraction: "give me lines one at a time." The file is never fully loaded into memory—we're processing a stream. Whether your file is 1KB or 100GB, your memory usage stays roughly constant.

The crlfDelay: Infinity option, by the way, ensures that we correctly handle Windows-style line endings (\r\n) by treating \r followed by \n as a single line break, no matter how much time passes between reading them.

This pattern is beautiful because it composes so well. Want to filter lines? Add another async generator:

async function* filterLines(lines, predicate) {
  for await (const line of lines) {
    if (predicate(line)) {
      yield line
    }
  }
}

// Compose them together
const lines = readLines('./server.log')
const errors = filterLines(lines, (line) => line.includes('ERROR'))

for await (const error of errors) {
  console.log('Found error:', error)
}

Notice how we're not storing any intermediate arrays. The filterLines generator consumes from readLines one item at a time, checks the predicate, and only yields matching lines. It's like a pipeline of transformations, but with zero memory overhead for buffering.

Trust me, when you start composing async generators like this, it's noticeably different in a positive way. Your code becomes declarative pipelines instead of imperative loops.

3. Real-Time Event Streams

Modern applications often need to handle real-time data—WebSocket messages, Server-Sent Events, or even database change streams.

The Problem:

// Traditional callback approach
const ws = new WebSocket('wss://api.example.com/stream')

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  // Hard to compose, hard to test, hard to reason about
  processMessage(data)
}

ws.onerror = (error) => {
  // Error handling is separate from data handling
  handleError(error)
}

Callbacks are fine for simple cases, but they don't compose well. What if you want to batch messages? Filter them? Transform them? You end up with spaghetti code. And testing becomes a nightmare—how do you simulate a sequence of messages arriving over time?

The fundamental issue is that callbacks are "push-based"—the WebSocket pushes data to you whenever it wants. You have no control over the pace. This is the opposite of what we want for composition.

The Async Generator Solution:

async function* websocketMessages(url) {
  const ws = new WebSocket(url)
  const messageQueue = []
  let resolve = null

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data)
    if (resolve) {
      // Someone is waiting for a message - give it to them directly
      resolve(data)
      resolve = null
    } else {
      // No one waiting - queue it for later
      messageQueue.push(data)
    }
  }

  ws.onerror = (error) => {
    throw error
  }

  // Wait for connection before yielding anything
  await new Promise((res) => (ws.onopen = res))

  try {
    while (ws.readyState === WebSocket.OPEN) {
      if (messageQueue.length > 0) {
        // Messages waiting in queue - yield immediately
        yield messageQueue.shift()
      } else {
        // No messages - wait for the next one
        yield await new Promise((res) => (resolve = res))
      }
    }
  } finally {
    // Cleanup: always close the connection when done
    ws.close()
  }
}

// Now you can use it like any other async iterable!
for await (const message of websocketMessages('wss://api.example.com/stream')) {
  console.log('Received:', message)

  if (message.type === 'shutdown') {
    break // Clean shutdown, finally block closes connection
  }
}

Why This Works:

This pattern converts a "push-based" API (WebSocket callbacks) into a "pull-based" API (async iteration). The key insight is the messageQueue and resolve variables working together:

When a WebSocket message arrives and someone is already waiting (via for await), we resolve their promise immediately with the data.
When a message arrives but no one is waiting, we queue it.
When the consumer asks for the next message and the queue has data, we yield immediately.
When the consumer asks but the queue is empty, we create a promise that will be resolved when the next message arrives.

This creates backpressure—if your consumer is slow, messages queue up rather than being dropped or causing the callback to block. And the finally block ensures the WebSocket is always properly closed, even if you break out of the loop or an error occurs.

The beauty here is that your WebSocket handling now looks just like any other data processing code. You can compose it with the same filter, map, and batch generators we built earlier. You can write unit tests that just yield mock messages. The mental model becomes unified.

4. Rate-Limited API Calls

Here's a problem I've run into countless times: you need to call an external API for each item in a list, but you can't hammer the API or you'll get rate limited.

The Problem:

// This will get you rate limited fast
async function enrichAllUsers(userIds) {
  const results = await Promise.all(
    userIds.map((id) => fetch(`/api/external/user/${id}`))
  )
  return results
}

If you have 1,000 user IDs, this fires off 1,000 concurrent requests instantly. Most APIs will reject the vast majority of them with 429 (Too Many Requests) errors.

Or the other extreme:

// This is painfully slow - one at a time
async function enrichAllUsers(userIds) {
  const results = []
  for (const id of userIds) {
    const result = await fetch(`/api/external/user/${id}`)
    results.push(result)
    await sleep(100) // Manual rate limiting
  }
  return results
}

This works but has two problems: the rate limiting is mixed in with the business logic, and you've hard-coded the timing. What if the API allows bursts? What if different endpoints have different limits?

The Async Generator Solution:

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms))
}

async function* rateLimited(items, requestsPerSecond) {
  const delay = 1000 / requestsPerSecond
  let lastRequest = 0

  for (const item of items) {
    const now = Date.now()
    const timeSinceLastRequest = now - lastRequest

    if (timeSinceLastRequest < delay) {
      await sleep(delay - timeSinceLastRequest)
    }

    yield item
    lastRequest = Date.now()
  }
}

async function* enrichUsers(userIds) {
  for await (const id of rateLimited(userIds, 10)) {
    // 10 requests per second
    const response = await fetch(`/api/external/user/${id}`)
    yield await response.json()
  }
}

// Usage
for await (const enrichedUser of enrichUsers(userIds)) {
  await saveToDatabase(enrichedUser)
  // Results stream in at a controlled pace
}

Why This Works:

The rateLimited generator is a reusable "throttle valve" that you can wrap around any iterable. It tracks the timestamp of the last yielded item and waits if necessary before yielding the next one. The beauty is that this logic is completely decoupled from what you're actually doing with the items.

Let's break down the timing logic:

We calculate the minimum delay between items (for 10 requests/second, that's 100ms)
Before yielding each item, we check how long it's been since the last yield
If not enough time has passed, we sleep for the remainder
We yield the item and record the current timestamp

The key insight is that we only wait when necessary. If the consumer is slow (maybe saveToDatabase takes 200ms), we don't add extra delay—we're already under the rate limit. The throttling only kicks in when the consumer would otherwise be too fast.

What I love about this approach is that the rate limiting logic is completely separate from the business logic. You could swap in a different rate limiting strategy without changing your enrichment code:

// Token bucket for bursty traffic
async function* tokenBucket(items, tokensPerSecond, maxTokens) {
  let tokens = maxTokens
  let lastRefill = Date.now()

  for (const item of items) {
    // Refill tokens based on time passed
    const now = Date.now()
    const elapsed = now - lastRefill
    tokens = Math.min(maxTokens, tokens + (elapsed / 1000) * tokensPerSecond)
    lastRefill = now

    // Wait if no tokens available
    while (tokens < 1) {
      await sleep(100)
      const now = Date.now()
      tokens += ((now - lastRefill) / 1000) * tokensPerSecond
      lastRefill = now
    }

    tokens -= 1
    yield item
  }
}

Same interface, different strategy. Your business logic doesn't change at all.

5. Database Cursor Iteration

When you're dealing with large datasets in a database, loading everything into memory is a recipe for disaster. Most databases support cursors for this exact reason.

The Problem:

// MongoDB example - the memory-hungry way
async function processAllOrders() {
  const orders = await Order.find({ status: 'pending' }).exec()

  // If you have 100,000 pending orders, you're in trouble
  for (const order of orders) {
    await processOrder(order)
  }
}

When you call .exec() on a Mongoose query, it fetches ALL matching documents into memory at once. With 100,000 orders, each containing nested products and customer info, you might be looking at several gigabytes of data. This is a common source of production outages—the query works fine in development with 100 records, then crashes in production with 100,000.

The Async Generator Solution:

async function* findOrdersWithCursor(query) {
  const cursor = Order.find(query).cursor()

  for await (const order of cursor) {
    yield order
  }
}

// Usage - memory-efficient iteration over millions of records
for await (const order of findOrdersWithCursor({ status: 'pending' })) {
  await processOrder(order)

  // Can stop early if needed
  if (reachedDailyLimit()) {
    break
  }
}

Why This Works:

When you call .cursor() instead of .exec(), MongoDB uses a server-side cursor. Instead of sending all documents at once, the database sends them in batches (typically 101 documents at a time by default). When you exhaust one batch, it automatically fetches the next.

The Mongoose cursor implements the async iterable protocol, so we can use for await directly. By wrapping it in our own generator, we get a clean abstraction that hides the MongoDB-specific details.

In other words, the database sends you records one at a time (or in small batches), and you process them as they arrive. Your memory usage stays flat regardless of how many records match your query.

Here's an even more powerful pattern—combining cursor iteration with batching:

async function* batch(asyncIterable, size) {
  let currentBatch = []

  for await (const item of asyncIterable) {
    currentBatch.push(item)

    if (currentBatch.length >= size) {
      yield currentBatch
      currentBatch = []
    }
  }

  // Don't forget the final partial batch!
  if (currentBatch.length > 0) {
    yield currentBatch
  }
}

// Process orders in batches of 100
const orders = findOrdersWithCursor({ status: 'pending' })

for await (const orderBatch of batch(orders, 100)) {
  // Bulk operations are often more efficient
  await Order.bulkWrite(
    orderBatch.map((order) => ({
      updateOne: {
        filter: { _id: order._id },
        update: { $set: { processedAt: new Date() } },
      },
    }))
  )

  console.log(`Processed batch of ${orderBatch.length} orders`)
}

Why batching matters: While processing one-at-a-time is memory-efficient, it's often not the most efficient for throughput. Database operations have overhead (network round-trips, transaction handling), and bulk operations amortize that overhead across many records. The batch generator gives us the best of both worlds: we never hold more than 100 orders in memory, but we get the efficiency of bulk writes.

This is a done deal for handling large datasets efficiently.

The Composability Superpower

If there's one thing I want you to take away from this post, it's that async generators compose beautifully. Let me show you what I mean:

// These are all reusable building blocks
async function* map(iterable, fn) {
  for await (const item of iterable) {
    yield await fn(item)
  }
}

async function* filter(iterable, predicate) {
  for await (const item of iterable) {
    if (await predicate(item)) {
      yield item
    }
  }
}

async function* take(iterable, count) {
  let taken = 0
  for await (const item of iterable) {
    if (taken >= count) break
    yield item
    taken++
  }
}

// Now compose them into a pipeline
const pipeline = take(
  filter(
    map(fetchUsers(), async (user) => ({
      ...user,
      enriched: await enrichUser(user.id),
    })),
    async (user) => user.enriched.isActive
  ),
  100 // Only need first 100 active users
)

for await (const user of pipeline) {
  console.log(user)
}

What's happening in this pipeline:

fetchUsers() yields users one at a time from the paginated API
map enriches each user by calling another API
filter only passes through users where isActive is true
take stops after 100 users (which stops the entire pipeline!)

The profound thing here is lazy evaluation. If only 100 of the first 150 fetched users are active, we only fetch 150 users. If the 100th active user is on page 3, we stop fetching after page 3. The take(100) at the end propagates "stop" signals all the way back through the pipeline.

Luckily, we can build these utilities once and reuse them everywhere. The declarative nature makes the code self-documenting—you can see exactly what transformations are being applied just by reading the pipeline.

When NOT to Use Async Generators

I'd be doing you a disservice if I didn't mention when async generators might not be the right choice:

Simple, one-time fetches: If you're just fetching one page of data, a regular async function is simpler. Don't add abstraction when it doesn't help.
When you need all data upfront: Some operations genuinely need all the data before they can proceed (like sorting or calculating totals). You can't sort a stream—you need the complete dataset. In these cases, just collect everything into an array first.
Highly parallel operations: Async generators are inherently sequential—you process one item, then the next. If you need to process 100 items in parallel, Promise.all with p-limit for concurrency control is a better fit.
Simple event handlers: For simple click handlers or one-off events, callbacks are perfectly fine. Not every event stream needs to be an async iterable.
When performance is critical: The generator machinery does add a small amount of overhead. For extremely hot paths processing millions of items per second, a tight loop might be faster. Profile first, optimize second.

Conclusion

Async generators are one of those features that seem unnecessary until you need them—and then they're absolutely indispensable. They give you:

Memory efficiency: Process data as it arrives instead of loading everything into memory
Composability: Build pipelines of transformations that are easy to read and maintain
Control: Pause, resume, or cancel iteration at any point
Elegance: Turn callback-based APIs into clean, linear code
Lazy evaluation: Only do work when the consumer asks for more data

The mental model shift is from "collect everything, then process" to "process as it flows." Once that clicks, you'll start seeing opportunities to use async generators everywhere.

The next time you find yourself dealing with paginated APIs, large files, real-time streams, rate limiting, or database cursors, give async generators a try. I think you'll be pleasantly surprised.

And that concludes the end of this post! I hope you found this valuable and look out for more in the future!

[Boost]

jsmanifest — Sun, 28 Dec 2025 21:31:49 +0000

jsmanifest

Dec 28 '25

How to Monitor Any URL for Dead Links (Including Tricky Soft 404s)

#javascript #webdev #api #programming

Comments

9 min read

How to Monitor Any URL for Dead Links (Including Tricky Soft 404s)

jsmanifest — Sun, 28 Dec 2025 20:54:59 +0000

The Problem: Not All Dead Links Return 404

When a webpage goes down, most developers expect a 404 Not Found response. But many services don't play by those rules.

Soft 404s return 200 OK with error content:

Request: GET https://example.com/deleted-page
Response: 200 OK
Body: <html>...Page not found...</html>

Standard uptime monitors see 200 OK and report everything as healthy. The link is actually dead.

This happens everywhere:

Any website: Custom error pages, removed content, expired pages
Documentation sites: Outdated links, reorganized docs, deprecated APIs
E-commerce: Out-of-stock products, discontinued items
File hosts: K2S, Nitroflare, Rapidgator, MEGA, MediaFire
Video platforms: YouTube ("Video unavailable"), Vimeo, Dailymotion
Social media: Deleted posts, suspended accounts
Cloud storage: Expired Google Drive shares, revoked permissions
APIs & webhooks: Deprecated endpoints, changed URLs

Anyone managing external links—whether it's a documentation site, resource page, or link directory—has likely experienced users reporting dead links that monitoring tools missed.

The Solution: Universal Link Monitoring

DeadLinkRadar monitors any URL with smart dead link detection. It works in two ways:

Universal monitoring: Any URL gets checked with smart soft-404 detection
Deep integrations: 30+ platforms (YouTube, file hosts, social media) get specialized detection

This tutorial covers:

Building a JavaScript API client
Bulk importing links (any URL type)
Setting up Discord and Telegram alerts
Automating daily link audits

Building the API Client

First, create an API key from the DeadLinkRadar dashboard. Then build a client class:

// deadlinkradar-client.js
const API_BASE = 'https://deadlinkradar.com/api/v1'

class DeadLinkRadarClient {
  constructor(apiKey) {
    this.apiKey = apiKey
  }

  async request(endpoint, options = {}) {
    const response = await fetch(`${API_BASE}${endpoint}`, {
      ...options,
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    })

    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.error?.message || 'API request failed')
    }

    return response.json()
  }

  // Account & Usage
  getAccount = () => this.request('/account')
  getUsage = () => this.request('/usage')

  // Links
  getLinks = (params = {}) => {
    const query = new URLSearchParams(params).toString()
    return this.request(`/links${query ? `?${query}` : ''}`)
  }

  createLink = (url, groupId = null) =>
    this.request('/links', {
      method: 'POST',
      body: JSON.stringify({ url, group_id: groupId }),
    })

  deleteLink = (id) => this.request(`/links/${id}`, { method: 'DELETE' })

  checkLinkNow = (id) => this.request(`/links/${id}/check`, { method: 'POST' })

  getLinkHistory = (id) => this.request(`/links/${id}/history`)

  // Batch operations
  batchCreateLinks = (links) =>
    this.request('/links/batch', {
      method: 'POST',
      body: JSON.stringify({ action: 'create', links }),
    })

  // Groups
  getGroups = () => this.request('/groups')

  createGroup = (name, description = '') =>
    this.request('/groups', {
      method: 'POST',
      body: JSON.stringify({ name, description }),
    })

  // Webhooks
  getWebhooks = () => this.request('/webhooks')

  createWebhook = (url, events = ['link.dead']) =>
    this.request('/webhooks', {
      method: 'POST',
      body: JSON.stringify({ url, events }),
    })

  testWebhook = (id) => this.request(`/webhooks/${id}/test`, { method: 'POST' })
}

export default DeadLinkRadarClient

Importing Links

With the client ready, bulk import links from any source—websites, APIs, file hosts, anything:

import DeadLinkRadarClient from './deadlinkradar-client.js'

const client = new DeadLinkRadarClient(process.env.DEADLINKRADAR_API_KEY)

// Mix of link types - all supported
const linksToMonitor = [
  // Regular websites
  'https://docs.example.com/api/v2/authentication',
  'https://blog.company.com/2024/product-launch',
  'https://partner-site.com/integration-guide',

  // APIs and webhooks
  'https://api.stripe.com/v1/status',
  'https://hooks.slack.com/services/T00/B00/XXX',

  // File hosting (deep integration)
  'https://k2s.cc/file/abc123/archive.zip',
  'https://mega.nz/file/ABC123',
  'https://drive.google.com/file/d/1234/view',

  // Video platforms (deep integration)
  'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  'https://vimeo.com/123456789',

  // Social media (deep integration)
  'https://bsky.app/profile/user.bsky.social/post/abc123',
  'https://github.com/owner/repo',
]

async function importLinks() {
  // Create groups to organize different link types
  const { data: docsGroup } = await client.createGroup(
    'Documentation',
    'External documentation and API references',
  )

  const { data: downloadsGroup } = await client.createGroup(
    'Downloads',
    'File hosting and download links',
  )

  console.log(`Created groups: ${docsGroup.name}, ${downloadsGroup.name}`)

  // Batch import (up to 1000 URLs per request)
  // Format: array of objects with url (required), group_id (optional), check_frequency (optional)
  const linksPayload = linksToMonitor.map((url) => ({ url }))
  const { data: result } = await client.batchCreateLinks(linksPayload)

  console.log(`Imported: ${result.success}`)
  console.log(`Failed: ${result.failed}`)

  if (result.errors?.length) {
    console.log('Errors:', result.errors)
  }

  if (result.created?.length) {
    console.log(
      `Created links:`,
      result.created.map((l) => l.url),
    )
  }
}

importLinks()

How Detection Works

DeadLinkRadar automatically determines the best detection strategy for each URL:

URL Type	Detection Method
Known platforms (YouTube, K2S, etc.)	Specialized platform detection
Any other URL	Smart soft-404 detection

This catches most dead links even on sites without proper 404 responses.

Setting Up Discord Alerts

Discord webhooks provide instant notifications when any link dies. Create a webhook in Discord (Server Settings → Integrations → Webhooks), then register it:

import DeadLinkRadarClient from './deadlinkradar-client.js'

const client = new DeadLinkRadarClient(process.env.DEADLINKRADAR_API_KEY)

async function setupDiscordAlerts() {
  const discordWebhookUrl = process.env.DISCORD_WEBHOOK_URL

  // Register webhook for dead link and recovery events
  const { data: webhook } = await client.createWebhook(discordWebhookUrl, [
    'link.dead',
    'link.alive',
  ])

  console.log('Discord webhook registered')
  console.log(`Webhook ID: ${webhook.id}`)
  console.log(`Signing secret: ${webhook.signing_secret}`) // Store securely

  // Send a test notification
  await client.testWebhook(webhook.id)
  console.log('Test notification sent')
}

setupDiscordAlerts()

When a link dies, Discord receives the webhook payload:

{
  "event": "link.dead",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "linkId": "550e8400-e29b-41d4-a716-446655440001",
    "url": "https://docs.example.com/api/v2/authentication",
    "previousStatus": "active",
    "currentStatus": "dead",
    "checkedAt": "2024-01-15T10:30:00Z"
  }
}

Setting Up Telegram Alerts

For Telegram notifications, create a webhook receiver that forwards to the Telegram Bot API. This can run on Vercel, Cloudflare Workers, or any serverless platform:

// api/telegram-forwarder.js
const TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN
const TELEGRAM_CHAT_ID = process.env.TELEGRAM_CHAT_ID

export default async function handler(req) {
  if (req.method !== 'POST') {
    return new Response('Method not allowed', { status: 405 })
  }

  const payload = await req.json()

  // Format the message
  const emoji = payload.event === 'link.dead' ? '🔴' : '🟢'
  const status = payload.event === 'link.dead' ? 'Dead Link' : 'Link Alive'

  const message = `
${emoji} *${status}*

*URL:* \`${payload.data.url}\`
*Previous:* ${payload.data.previousStatus}
*Checked:* ${new Date(payload.data.checkedAt).toLocaleString()}
`.trim()

  // Forward to Telegram
  await fetch(`https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chat_id: TELEGRAM_CHAT_ID,
      text: message,
      parse_mode: 'Markdown',
    }),
  })

  return new Response('OK', { status: 200 })
}

await client.createWebhook('https://your-domain.com/api/telegram-forwarder', [
  'link.dead',
  'link.alive',
])

To get the Telegram bot token and chat ID:

Create a bot with @BotFather
Start a chat with the bot
Get the chat ID from https://api.telegram.org/bot<TOKEN>/getUpdates

Querying Link Status

Check the current state of monitored links:

import DeadLinkRadarClient from './deadlinkradar-client.js'

const client = new DeadLinkRadarClient(process.env.DEADLINKRADAR_API_KEY)

async function getDeadLinks() {
  // Fetch all dead links with pagination
  const { data: links, pagination } = await client.getLinks({
    status: 'dead',
    per_page: 100,
  })

  console.log(`Found ${pagination.total} dead links:\n`)

  for (const link of links) {
    console.log(`URL: ${link.url}`)
    console.log(`Service: ${link.service}`) // "generic" for regular URLs
    console.log(`Last checked: ${link.last_checked_at}`)
    console.log('---')
  }
}

getDeadLinks()

Filter by service, group, or search:

// Get all dead links from regular websites (generic detection)
const genericLinks = await client.getLinks({
  status: 'dead',
  service: 'generic',
})

// Get all dead YouTube links (specialized detection)
const youtubeLinks = await client.getLinks({
  status: 'dead',
  service: 'youtube',
})

// Get links in a specific group
const groupLinks = await client.getLinks({
  group_id: '550e8400-e29b-41d4-a716-446655440000',
})

// Search by URL substring
const searchResults = await client.getLinks({
  search: 'docs.example.com',
})

Investigating Link History

When a link dies, check its history to understand when and why:

async function investigateLink(linkId) {
  const { data: history } = await client.getLinkHistory(linkId)

  console.log('Check history:\n')

  for (const check of history) {
    const emoji = check.status === 'active' ? '🟢' : '🔴'
    console.log(`${emoji} ${check.checked_at}`)
    console.log(`   Status: ${check.status}`)
    console.log(`   Response time: ${check.response_time_ms}ms`)

    if (check.error_message) {
      console.log(`   Error: ${check.error_message}`)
    }
    console.log()
  }
}

investigateLink('550e8400-e29b-41d4-a716-446655440000')

Automated Daily Audit

Combine everything into a daily audit script that posts a summary to Discord:

import DeadLinkRadarClient from './deadlinkradar-client.js'

const client = new DeadLinkRadarClient(process.env.DEADLINKRADAR_API_KEY)
const DISCORD_WEBHOOK = process.env.DISCORD_SUMMARY_WEBHOOK

async function dailyAudit() {
  // Fetch usage and dead links
  const { data: usage } = await client.getUsage()
  const { data: deadLinks, pagination } = await client.getLinks({
    status: 'dead',
    per_page: 100,
  })

  // Group dead links by service
  const byService = deadLinks.reduce((acc, link) => {
    acc[link.service] = acc[link.service] || []
    acc[link.service].push(link)
    return acc
  }, {})

  const summary = {
    monitored: usage.links.used,
    dead: pagination.total,
    byService: Object.entries(byService).map(([service, links]) => ({
      service,
      count: links.length,
    })),
  }

  console.log('Daily Audit Summary')
  console.log(`Monitored: ${summary.monitored}`)
  console.log(`Dead: ${summary.dead}`)

  // Post to Discord
  if (DISCORD_WEBHOOK) {
    const embed = {
      title: '📊 Daily Link Audit',
      color: summary.dead > 0 ? 0xff0000 : 0x00ff00,
      fields: [
        { name: 'Monitored', value: summary.monitored.toString(), inline: true },
        { name: 'Dead', value: summary.dead.toString(), inline: true },
      ],
      timestamp: new Date().toISOString(),
    }

    if (summary.dead > 0) {
      embed.fields.push({
        name: 'By Type',
        value: summary.byService.map((s) => `**${s.service}**: ${s.count}`).join('\n'),
      })
    }

    await fetch(DISCORD_WEBHOOK, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ embeds: [embed] }),
    })

    console.log('Summary posted to Discord')
  }

  return summary
}

dailyAudit()

Run this with a cron job or scheduled task:

# crontab - run daily at 9am
0 9 * * * node /path/to/daily-audit.js

Webhook Signature Verification

For production use, verify webhook signatures to ensure requests come from DeadLinkRadar:

import crypto from 'crypto'

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))
}

// In the webhook handler
export default async function handler(req) {
  const signatureHeader = req.headers.get('x-deadlinkradar-signature')
  // Format: "sha256=<hex>"
  const signature = signatureHeader?.replace('sha256=', '')
  const payload = await req.json()

  if (!signature || !verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return new Response('Invalid signature', { status: 401 })
  }

  // Process the webhook...
}

Real-World Example: Docusaurus Documentation Monitor

Documentation sites often link to external APIs, libraries, and resources that can go offline without notice. Here's a complete example for monitoring all external links in a Docusaurus documentation site.

Step 1: Extract Links from Markdown Files

First, create a utility to recursively scan documentation files and extract external URLs:

// extract-docs-links.js
import fs from 'fs'
import path from 'path'

/**
 * Recursively find all markdown files in a directory
 */
function findMarkdownFiles(dir, files = []) {
  const entries = fs.readdirSync(dir, { withFileTypes: true })

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name)
    if (entry.isDirectory()) {
      findMarkdownFiles(fullPath, files)
    } else if (entry.name.match(/\.(md|mdx)$/)) {
      files.push(fullPath)
    }
  }

  return files
}

/**
 * Extract external links from markdown content
 */
function extractLinks(content, filePath) {
  const links = []

  // Match markdown links: [text](url)
  const linkRegex = /\[([^\]]*)\]\(([^)]+)\)/g
  let match

  while ((match = linkRegex.exec(content)) !== null) {
    const url = match[2]

    // Only include external https:// links
    if (url.startsWith('https://') || url.startsWith('http://')) {
      links.push({
        url,
        text: match[1],
        file: filePath,
        section: path.dirname(filePath).split(path.sep).pop() || 'root',
      })
    }
  }

  return links
}

/**
 * Extract all external links from Docusaurus docs directory
 */
export function extractLinksFromDocs(docsDir = './docs') {
  const markdownFiles = findMarkdownFiles(docsDir)
  const allLinks = []

  for (const file of markdownFiles) {
    const content = fs.readFileSync(file, 'utf-8')
    const links = extractLinks(content, file)
    allLinks.push(...links)
  }

  // Deduplicate by URL
  const uniqueUrls = new Map()
  for (const link of allLinks) {
    if (!uniqueUrls.has(link.url)) {
      uniqueUrls.set(link.url, link)
    }
  }

  return Array.from(uniqueUrls.values())
}

Step 2: Setup Monitoring with Groups

Now import the links into DeadLinkRadar, organized by documentation section:

// setup-docs-monitoring.js
import DeadLinkRadarClient from './deadlinkradar-client.js'
import { extractLinksFromDocs } from './extract-docs-links.js'

const client = new DeadLinkRadarClient(process.env.DEADLINKRADAR_API_KEY)

async function setupDocsMonitoring() {
  console.log('Extracting links from documentation...')
  const links = extractLinksFromDocs('./docs')
  console.log(`Found ${links.length} unique external links`)

  // Get unique sections
  const sections = [...new Set(links.map((l) => l.section))]

  // Create a group for each documentation section
  const groupIds = {}
  for (const section of sections) {
    const { data: group } = await client.createGroup(
      `docs-${section}`,
      `External links from ${section} documentation`,
    )
    groupIds[section] = group.id
    console.log(`Created group: ${group.name}`)
  }

  // Prepare links with group assignments
  const linksPayload = links.map((link) => ({
    url: link.url,
    group_id: groupIds[link.section] || null,
  }))

  // Batch import (API supports up to 1000 per request)
  const { data: result } = await client.batchCreateLinks(linksPayload)

  console.log(`\nImport complete:`)
  console.log(`  Imported: ${result.success}`)
  console.log(`  Failed: ${result.failed}`)

  if (result.errors?.length) {
    console.log(`  Errors:`, result.errors.slice(0, 5))
  }

  // Set up webhook for dead link alerts
  const webhookUrl = process.env.DOCS_ALERT_WEBHOOK_URL
  if (webhookUrl) {
    const { data: webhook } = await client.createWebhook(webhookUrl, ['link.dead', 'link.alive'])
    console.log(`\nWebhook configured: ${webhook.id}`)
    console.log(`Signing secret: ${webhook.signing_secret}`)
  }

  return result
}

setupDocsMonitoring().catch(console.error)

Running the Monitor

# Set environment variables
export DEADLINKRADAR_API_KEY="your-api-key"
export DOCS_ALERT_WEBHOOK_URL="https://your-server.com/api/docs-webhook"

# Run the setup script
node setup-docs-monitoring.js

Example output:

Extracting links from documentation...
Found 47 unique external links
Created group: docs-getting-started
Created group: docs-api-reference
Created group: docs-guides

Import complete:
  Imported: 47
  Failed: 0

Webhook configured: 550e8400-e29b-41d4-a716-446655440000
Signing secret: whsec_abc123...

Once configured, DeadLinkRadar checks each link daily. When a documentation link dies, the webhook fires with the full context—allowing automated Slack alerts, GitHub issues, or custom notification flows.

The free tier includes 25 links with daily checks—enough to validate the solution before scaling up.

Summary

Traditional uptime monitors fail because they only check HTTP status codes. DeadLinkRadar provides:

Universal monitoring for any URL with smart soft-404 detection
Deep integrations for 30+ platforms (YouTube, file hosts, social media) with specialized detection
REST API for programmatic link management
Webhooks for Discord, Slack, Telegram, and custom integrations
Batch operations for bulk imports
Link groups for organization
Check history for debugging

Whether monitoring documentation links, API endpoints, download pages, or social media posts—the JavaScript client above covers the full API surface. Adapt it to any workflow.

Resources:

Combining the Command Pattern with State Pattern in JavaScript

jsmanifest — Thu, 24 Nov 2022 17:59:00 +0000

JavaScript is a popular language known for its flexibility. It's thanks to this that makes patterns like the command pattern easier to implement in our apps.

When there's a design pattern out there that goes well hand-in-hand with the state pattern, it's arguably the command pattern.

If you've read one of my previous blog posts about the state pattern you might remember this sentence: "The State Pattern ensures an object to behave in a predictable, coordinated way depending on the current "state" of the application."

In the command pattern the main goal is to separate the communication between two important participants:

The initiator (also called the invoker)
The handler

We are going to incorporate the command pattern together with the state pattern in this post. If you're learning either of the two, my best advice to you in order to get the most out of this post is to make sure you understand the flow of the state pattern before continuing to the command pattern implementation to better feel how the behavior of the code drastically changes while the functionality remains in tact.

Let's start off with an example using the state pattern so that we can see this in a clearer perspective:

let state = { backgroundColor: 'white', profiles: [] }
let subscribers = []

function notifySubscribers(...args) {
  subscribers.forEach((fn) => fn(...args))
}

function setBackgroundColor(color) {
  setState((prevState) => ({
    ...prevState,
    backgroundColor: color,
  }))
}

function setState(newState) {
  let prevState = state
  state =
    typeof newState === 'function'
      ? newState(prevState)
      : { ...prevState, ...newState }

  notifySubscribers(prevState, state)
}

function subscribe(callback) {
  subscribers.push(callback)
}

function addProfile(profile) {
  setState((prevState) => ({
    ...prevState,
    profiles: prevState.profiles.concat(profile),
  }))
}

subscribe(
  (function () {
    function getColor(length) {
      if (length >= 5 && length <= 8) return 'blue' // Average
      if (length > 8 && length < 10) return 'orange' // Reaching limit
      if (length > 10) return 'red' // Limit reached
      return 'white' // Default
    }

    return (prevState, newState) => {
      const prevProfiles = prevState?.profiles || []
      const newProfiles = newState?.profiles || []
      if (prevProfiles.length !== newProfiles.length) {
        setBackgroundColor(getColor(newProfiles.length))
      }
    }
  })(),
)

console.log(state.backgroundColor) // 'white'

addProfile({ id: 0, name: 'george', gender: 'male' })
addProfile({ id: 1, name: 'sally', gender: 'female' })
addProfile({ id: 2, name: 'kelly', gender: 'female' })

console.log(state.backgroundColor) // 'white'

addProfile({ id: 3, name: 'mike', gender: 'male' })
addProfile({ id: 4, name: 'bob', gender: 'male' })

console.log(state.backgroundColor) // 'blue'

addProfile({ id: 5, name: 'kevin', gender: 'male' })
addProfile({ id: 6, name: 'henry', gender: 'male' })

console.log(state.backgroundColor) // 'blue'

addProfile({ name: 'ronald', gender: 'male' })
addProfile({ name: 'chris', gender: 'male' })
addProfile({ name: 'andy', gender: 'male' })
addProfile({ name: 'luke', gender: 'male' })

console.log(state.backgroundColor) // 'red'

In the example above we have a state and subscribers object. The subscribers object holds a collection of callback functions. These callback functions are called whenever the setState function is called:

Every time the state updates, all of the registered callbacks are called with the previous state (prevState) and the new state (newState) in arguments.

We registered one callback listener so that we can watch updates to the state and update the background color whenever the amount of profiles hits a certain length. The table below shows a clearer picture lining up the profile counts with the associated color:

Minimum Threshold	Background Color
0	white
5	blue
9	orange
10	red

So how can the command pattern fit into this? Well, if we look back into our code we can see that we defined some functions responsible for both calling and handling this logic:

function notifySubscribers(...args) {
  subscribers.forEach((fn) => fn(...args))
}

function setBackgroundColor(color) {
  setState((prevState) => ({
    ...prevState,
    backgroundColor: color,
  }))
}

function addProfile(profile) {
  setState((prevState) => ({
    ...prevState,
    profiles: prevState.profiles.concat(profile),
  }))
}

We can abstract these into commands instead. In the upcoming code example it will show the same code with the command pattern implemented in harmony with the state pattern. When we do that there are only 2 functions left untouched: setState and subscribe.

Let's go ahead and introduce the command pattern and commandify our abstracted functions:

let state = { backgroundColor: 'white', profiles: [] }
let subscribers = []
let commands = {}

function setState(newState) {
  let prevState = state
  state =
    typeof newState === 'function'
      ? newState(prevState)
      : { ...prevState, ...newState }

  dispatch('NOTIFY_SUBSCRIBERS', { prevState, newState: state })
}

function subscribe(callback) {
  subscribers.push(callback)
}

function registerCommand(name, callback) {
  if (commands[name]) commands[name].push(callback)
  else commands[name] = [callback]
}

function dispatch(name, action) {
  commands[name]?.forEach?.((fn) => fn?.(action))
}

registerCommand(
  'SET_BACKGROUND_COLOR',
  function onSetState({ backgroundColor }) {
    setState((prevState) => ({ ...prevState, backgroundColor }))
  },
)

registerCommand('NOTIFY_SUBSCRIBERS', function onNotifySubscribers(...args) {
  subscribers.forEach((fn) => fn(...args))
})

registerCommand('ADD_PROFILE', function onAddProfile(profile) {
  setState((prevState) => ({
    ...prevState,
    profiles: prevState.profiles.concat(profile),
  }))
})

subscribe(
  (function () {
    function getColor(length) {
      if (length >= 5 && length <= 8) return 'blue' // Average
      if (length > 8 && length < 10) return 'orange' // Reaching limit
      if (length > 10) return 'red' // Limit reached
      return 'white' // Default
    }

    return ({ prevState, newState }) => {
      const prevProfiles = prevState?.profiles || []
      const newProfiles = newState?.profiles || []
      if (prevProfiles.length !== newProfiles.length) {
        dispatch('SET_BACKGROUND_COLOR', {
          backgroundColor: getColor(newProfiles.length),
        })
      }
    }
  })(),
)

console.log(state.backgroundColor) // 'white'

dispatch('ADD_PROFILE', { id: 0, name: 'george', gender: 'male' })
dispatch('ADD_PROFILE', { id: 1, name: 'sally', gender: 'female' })
dispatch('ADD_PROFILE', { id: 2, name: 'kelly', gender: 'female' })

console.log(state.backgroundColor) // 'white'

dispatch('ADD_PROFILE', { id: 3, name: 'mike', gender: 'male' })
dispatch('ADD_PROFILE', { id: 4, name: 'bob', gender: 'male' })

console.log(state.backgroundColor) // 'blue'

dispatch('ADD_PROFILE', { id: 5, name: 'kevin', gender: 'male' })
dispatch('ADD_PROFILE', { id: 6, name: 'henry', gender: 'male' })

console.log(state.backgroundColor) // 'blue'

dispatch('ADD_PROFILE', { id: 7, name: 'ronald', gender: 'male' })
dispatch('ADD_PROFILE', { id: 8, name: 'chris', gender: 'male' })
dispatch('ADD_PROFILE', { id: 9, name: 'andy', gender: 'male' })
dispatch('ADD_PROFILE', { id: 10, name: 'luke', gender: 'male' })

console.log(state.backgroundColor) // 'red'

It's much clearer now determining which functions we need to update the state. We can separate everything else into their own separate command handlers. That way we can isolate them to be in their own separate file or location so we can work with them easier.

Here were the steps demonstrated in our updated example to get to that point:

Create the commands variable. This will store registered commands and their callback handlers.
Define registerCommand. This will register new commands and their callback handlers to the commands object.
Define dispatch. This is responsible for calling the callback handlers associated with their command.

With these three steps we perfectly set up our commands to be registered by the client code, allowing them to implement their own commands and logic. Notice how how our registerCommand and dispatch functions don't need to be aware of anything related to our state objects.

We can easily take advantage of that and continue with isolating them into a separate file:

commands.js

// Private object hidden within this scope
let commands = {}

export function registerCommand(name, callback) {
  if (commands[name]) commands[name].push(callback)
  else commands[name] = [callback]
}

export function dispatch(name, action) {
  commands[name]?.forEach?.((fn) => fn?.(action))
}

As for the actual logic written in these lines:

registerCommand(
  'SET_BACKGROUND_COLOR',
  function onSetState({ backgroundColor }) {
    setState((prevState) => ({ ...prevState, backgroundColor }))
  },
)

registerCommand('NOTIFY_SUBSCRIBERS', function onNotifySubscribers(...args) {
  subscribers.forEach((fn) => fn(...args))
})

registerCommand('ADD_PROFILE', function onAddProfile(profile) {
  setState((prevState) => ({
    ...prevState,
    profiles: prevState.profiles.concat(profile),
  }))
})

Normally this would all be left to the client code to decide that (technically, our last code snippet are representing the client code). Some library authors also define their own command handlers for internal use but the same concept still applies. One practice I see often is having their internal logic put into a separate file with its file name prefixed with "internal" (example: internalCommands.ts). It's worth noting that 99% of the time the functions in those files are never exported out to the user. That's why they're marked internal.

The image below is a diagram of what our code looked like before implementing the command design pattern to it:

The bubbles in the purple represent functions. The two functions setBackgroundColor and addProfile are included amongst them. Specifically for those two however call setState directly to facilitate changes to state. In other words they both call and handle the state update logic to specific slices of the state they're interested in.

Now have a look at the diagram below. This image shows how our code looks like after implementing the pattern:

The functions notifySubscribers, addProfile, and setBackgroundColor are gone, but all of their logic still remains. They're now written as command handlers:

Command handlers define their logic separately and become registered. Once they're registered, they are "put on hold" until they are called by the dispatch function.

Ultimately, the code functionality stays the same and only the behavior was changed.

Who uses this approach?

One example that immediately pops up in my mind is the lexical package by Facebook here. Lexical is an "extensible JavaScript web text-editor framework with an emphasis on reliability, accessibility, and performance".

In lexical, commands for the editor can be registered and become available for use. The handling logic is defined when they get registered so they can be identified for the dispatch call.

Conclusion

And that concludes the end of this post! I hope you found this to be valuable and look out for more in the future!

The Bridge Design Pattern in JavaScript

jsmanifest — Sat, 30 Apr 2022 23:49:04 +0000

In this article we will be going over the Bridge Design Pattern in JavaScript. This is one of the top used patterns that make a significant impact in softare applications. It is a pattern that easily promotes a separation of concerns in its implementation and it's scalable.

Here is diagram depicting this pattern:

There are usually two main participants (or entity, whichever you want to call it) that are involved in the Bridge Pattern.

The first and top most part is the abstract layer. This can be implemented simply as a class:

class Person {
  constructor(name) {
    this.name = name
  }

  talk(message) {
    console.log(message)
  }
}

In the Bridge Pattern, the abstract layer declares the base interface methods and/or properties. However, they do not care about the implementation details because that isn't their job. To be able to reap the advantages of this pattern it must be kept this way so that our code later does not become tightly coupled and remains manageable.

The abstract layer instead opens bridges which then leads to the second main part of the pattern: the implementation layers (which are often implemented as classes in practice) are attached to these bridges, which the client (or you) call the shots. The word "attached" is my form of a human readable term to understand the code term which are references or pointers:

The "bridge" can visibly appear in code like this:

class Theme {
  constructor(colorScheme) {
    this.colorScheme = colorScheme // Bridge declared
  }

  getColorScheme() {
    return this.colorScheme // Bridge reference/pointer
  }
}

If you've visited websites like https://dev.to or https://medium.com they have a theme feature that you can access inside your profile. There is usually a toggle theme button. The theme is the abstract layer. The actual implementation in toggling between light and dark are most likely located outside of the abstract layer location within the implementation layer(s).

Where and when should the Bridge Pattern be used?

Some implementations in the real world are coded in a way where the "bridge effect" goes "live" during run time. When you need this type of coupling / binding between two objects this is when you can use the Bridge Pattern to your advantage.

A good example of this is twilio-video, a JavaScript library that lets you add real time voice and video to your web applications (like Zoom). In this library, The Room always instantiates as an empty room. The class keeps a pointer to a LocalParticipant, (when you join a video chat room you are the LocalParticipant on your screen) but the LocalParticipant doesn't actually run or become instantiated yet until it connects and is finished subscribing to the room which is only possible in running code.

If you scan through their code you will spot bridges in a lot of areas. A video chat session cannot be created without a Room, and a room does not start until there are at least two Participants. But a Participant cannot begin streaming until they start their local audio/video MediaTracks. These classes work together in a top down hierarchy. When you start to have multiple classes that are coupled together this is also a good time to consider the Bridge Pattern.

Another scenario where the Bridge Pattern is useful is when you want to share an implementation of some object with multiple objects.

For example, the MediaStreamTrack class represents a media track for a stream. The two most common implementations that "bridge" from it are audio and video tracks.

In addition, the implementation details are usually hidden within the derived classes.

Implementation

Let's implement our own variation of the Bridge Pattern to get a good feel of a problem and solution it brings to the table.

Let's start with a generic Thing class which can represent any thing:

class Thing {
  constructor(name, thing) {
    this.name = name
    this.thing = thing
  }
}

We can create a high level abstraction class that extends Thing. We can call this LivingThing and will define a method called eat. All living things in the real world are born with the ability to eat in order to stay alive. We can mimic this in our code. This will stay in the high level abstract layer:

class LivingThing extends Thing {
  constructor(name, bodyParts) {
    super(name, this)
    this.name = name
    // Bridge
    this.mouth = bodyParts?.mouth || null
  }

  eat(food) {
    this.mouth.open()
    this.mouth.chew(food)
    this.mouth.swallow()
    return this
  }
}

We can see that we opened a bridge to the Mouth class. Let's define that class next:

class Mouth extends Thing {
  constructor() {
    super('mouth', this)
  }

  chew() {}
  open() {}
  swallow() {}
}

The thing (no pun intended) to consider now is that our Mouth will be an implementation layer where we write the logic for communicating between the mouth and food.

This implementation is entirely based in Mouth. The LivingThing does not care about these implementation details and instead delegates this role entirely to its implementation classes which in our case is Mouth.

Let's pause and talk about this part for a moment. If LivingThing is not involved in any of its implementations this is actually a useful concept to us. If we can make other LivingThings that only need to provide the interface for implementations to derive from, then we can make a wider range of classes for other scenarios.

In an MMORPG game we can use the LivingThing and make more of them where they all inherit a pointer to a mouth automatically:

class Character extends LivingThing {
  constructor(name, thing) {
    super(name, this)
    this.thing = thing
    this.hp = 100
    this.chewing = null
  }

  attack(target) {
    target.hp -= 5
    return this
  }

  chew(food) {
    this.chewing = food
    return this
  }

  eat(food) {
    this.hp += this.chewing.hpCount
    return this
  }
}

class Swordsman extends Character {}
class Rogue extends Character {}
class Archer extends Character {}
class Sorceress extends Character {}

class Potion {
  constructor(potion) {
    this.potion = potion
  }

  consume(target) {
    if (this.potion) {
      this.eat(this.potion)
      this.potion = null
    }
  }
}

class Food {...}

const sally = new Sorceress()
const mike = new Rogue()

mike.attack(sally)
sally.eat(new Food(...))

The bridge pattern is well known to enable developers to build cross-platform applications. We can already see this capability in our examples. We can build this same MMORPG game by reusing LivingThing on a new code base. We only need to re-implement the implementation layers like Mouth in order to create bindings to different platforms.

We aren't limited to games. Since our LivingThing is generic and makes sense for anything that moves it's possible we can use it to create something entirely different like a robot as an IoT device program and simulate eating behavior with LivingThing.

Going back into our pretend MMORPG game, bridges can be used to create more bridges. MMORPG usually have some profile page where users can edit their settings.

This Profile can itself utilize the Bridge Design Pattern to define a suite of pieces to make it function like a profile api:

let key = 0

class Profile {
  constructor({ avatar, character, gender, username }) {
    this.character = null // Bridge
    this.gender = null
    this.username = username
    this.id = ++key
  }

  setCharacter(value) {
    this.character = value
    return this
  }

  setGender(value) {
    this.gender = value
    if (value === 'female') {
      this.showRecommendedEquipments('female')
    } else {
      this.showRecommendedEquipments('male')
    }
    return this
  }

  setUsername(value) {
    this.username = value
    return this
  }

  showRecommendedEquipments() {
    // Do something with this.character
  }

  save() {
    return fetch(`https://some-database-endpoint.com/v1/profile/${key}`, {
      method: 'POST',
      body: JSON.stringify({
        character: this.character,
        gender: this.gender,
        username: this.username,
      }),
    })
  }
}

If you've read some of my other articles this might feel similar to the Adapter or Strategy pattern.

There are distinct differences that solve different problems however:

In the Adapter pattern the problem it solves starts from the code (or prior to runtime) where we would construct the Adapter first then immediately start with the rest:

axios-mock-adapter

function adapter() {
  return function (config) {
    var mockAdapter = this
    // axios >= 0.13.0 only passes the config and expects a promise to be
    // returned. axios < 0.13.0 passes (config, resolve, reject).
    if (arguments.length === 3) {
      handleRequest(mockAdapter, arguments[0], arguments[1], arguments[2])
    } else {
      return new Promise(function (resolve, reject) {
        handleRequest(mockAdapter, resolve, reject, config)
      })
    }
  }.bind(this)
}

Compare that with our earlier snippets of twilio-video and you will feel the difference immediately.

Conclusion

And that concludes the end of this post! I hope you found this to be valuable and look out for more in the future!

The Power of Template Design Pattern in JavaScript

jsmanifest — Sat, 23 Apr 2022 22:42:31 +0000

If you've used nodejs before then you know that packages are at the heart of this platform. Every day and every second there is either a new update or a new package published to the npm registry. The majority of these packages are reusable and extensible. The way they do this can be one of many ways but there's one common trait that they all share: They can be seen as templates that are waiting for you to execute them.

This post will go over the Template Design Pattern in JavaScript. We will understand more in detail the approach of this pattern and one scenario of when we should use it. We will also see a diagram of how the the structure look like "outside the box". And finally, we will implement the pattern in code so that by the end of this article you will be comfortable about templating in JavaScript.

How does the Template Pattern work?

When we are implementing this pattern a useful way to approach this is to think about the start phase of something and the end phase.

When we write functions the first thing we think about sometimes is to decide on its parameters and how variables will be initialized. Eventually we decide how to end that function.

What happens in the middle depends on the implementation.

This is similar to how the flow of the Template works.

In more official terms it's essentially a bare interface that is given to the consumer where they can implement one or more steps of the algorithm without changing the structure.

After they define those steps and follows execution, the "end" phase is reached, just like a basic function.

When is the Template Pattern needed?

It's most needed in scenarios where two functions have important similarities in an implementation or interface but share the same problem where they aren't able to reuse those similarities. This means that when there is an update to one of the function's implementation, the other function needs to update its implementation as well. This is a bad practice and eventually becomes unmaintainable if not dealt with.

This is where the Template Pattern comes in. It encapsulates those similarities in itself and delegates the responsibilities of the other parts out for those that derive and implement them themselves.

That way if there was a change to the implementation of the encapsulated parts all derived classes don't have to be involved in them.

How does the Template Pattern look like in code?

In this section we will be implementing the Template Pattern ourselves.

Like I mentioned before, this can be implemented in a lot of ways because the pattern in its implementation is closely relative to the problem it is addressing. However they all have the same objective when we look at it in a bigger perspective.

Let's pretend we are building a function that runs a series of "transform" functions on a collection of dates of any date format. These can look like this:

const dates = [
  357289200000,
  989910000000,
  'Tue Jan 18 2005 00:00:00 GMT-0800 (Pacific Standard Time)',
  new Date(2001, 1, 03),
  new Date(2000, 8, 21),
  '1998-02-08T08:00:00.000Z',
  new Date(1985, 1, 11),
  '12/24/1985, 12:00:00 AM',
  new Date(2020, 6, 26),
  'Tue May 15 2001 00:00:00 GMT-0700 (Pacific Daylight Time)',
  1652252400000,
  '2005-01-18T08:00:00.000Z',
  new Date(2022, 7, 14),
  '1999-02-01T08:00:00.000Z',
  1520668800000,
  504259200000,
  '4/28/1981, 12:00:00 AM',
  '2015-08-08T07:00:00.000Z',
]

Our function will implement the Template Pattern and our task is to define the base skeleton holding these "empty" placeholders:

reducer
transformer
finalizer
sorter

When objects are created and derive from one of them they can provide their own algorithm that will be run when our function executes.

The consumer will have to implement the reducer as a function that takes an accumulator and a value and returns some accumulated result.

transformer is a function that transforms and returns a value of any data type.

finalizer takes in a value and also returns a value of any data type. But this time this value will be used to perform the final step.

The sorter is a function that takes in one item in the first argument and another item in the second argument. This function is the same as how you would implement the function in the native .Array.sort method.

Our function with the template implementation will be named createPipeline and takes in those functions if provided by the caller. If the caller doesn't provide one or more of them we must substitute them with a default implementation so that our algorithm can still run:

function createPipeline(...objs) {
  let transformer
  let reducer
  let finalizer
  let sorter

  objs.forEach((o) => {
    const id = Symbol.keyFor(_id_)
    if (o[id] === _t) transformer = o
    else if (o[id] === _r) reducer = o
    else if (o[id] === _f) finalizer = o
    else if (o[id] === _s) sorter = o
  })

  if (!transformer) transformer = { transform: identity }
  if (!reducer) reducer = { reduce: identity }
  if (!finalizer) finalizer = { finalize: identity }
  if (!sorter) sorter = { sort: (item1, item2) => item1 - item2 }

  return {
    into(initialValue, ...items) {
      return items
        .reduce((acc, item) => {
          return reducer.reduce(
            acc,
            finalizer.finalize(transformer.transform(item)),
          )
        }, initialValue)
        .sort((item1, item2) => sorter.sort(item1, item2))
    },
  }
}

This simple function is a template where callers can pass in their own algorithms. It allows them to choose not to pass in any implementation or allow them to pass in one or all of the 4 functions involved in the pipeline.

When they call the into function with a collection of items, the next step is to immediately run all of them through the pipeline and are eventually accumulated into a new collection.

Something we often see from libraries that provide some form of template interface to consumers is that they try to make it as easy as possible to be worked with.

For example, the createStore in the redux library provides several overloads that developers can work with for instantiation. This is a very useful thing to do and it improves their reusability but also demonstrates the nature of a template in practice.

Inside template pattern implementations when there is a strict flow that an algorithm requires it is usually hidden within the implementation like the createStore in redux.

When we go back to our previous example we noticed something in these lines:

objs.forEach((o) => {
  const id = Symbol.keyFor(_id_)
  if (o[id] === _t) transformer = o
  else if (o[id] === _r) reducer = o
  else if (o[id] === _f) finalizer = o
  else if (o[id] === _s) sorter = o
})

This was not required or had anything to do with our pipeline but because we created a helper to distinguish them we allowed the caller to pass in any of the transformer,reducer, finalizer and sorter functions in any order even though they need to be in order when it runs the functions.

So any of these calls all return the same exact result even though they are ordered differently:

console.log(getResult(reducer, transformer, finalizer, sorter))
console.log(getResult(transformer, reducer, finalizer, sorter))
console.log(getResult(finalizer, sorter, transformer, reducer))
console.log(getResult(sorter, finalizer, transformer, reducer))

In the internal implementation it doesn't work as expected if they were to be called in different orders because the sorter needs to be the final operation. The finalizer needs to be run before the final (the sorter) operation and the transformer needs to be run before the finalizer.

This is how the higher level implementation looks like:

function createFactories() {
  const _id_ = Symbol.for('__pipeline__')
  const identity = (value) => value

  const factory = (key) => {
    return (fn) => {
      const o = {
        [key](...args) {
          return fn?.(...args)
        },
      }

      Object.defineProperty(o, Symbol.keyFor(_id_), {
        configurable: false,
        enumerable: false,
        get() {
          return key
        },
      })

      return o
    }
  }

  const _t = 'transform'
  const _r = 'reduce'
  const _f = 'finalize'
  const _s = 'sort'

  return {
    createTransformer: factory(_t),
    createReducer: factory(_r),
    createFinalizer: factory(_f),
    createSorter: factory(_s),
    createPipeline(...objs) {
      let transformer
      let reducer
      let finalizer
      let sorter

      objs.forEach((o) => {
        const id = Symbol.keyFor(_id_)
        if (o[id] === _t) transformer = o
        else if (o[id] === _r) reducer = o
        else if (o[id] === _f) finalizer = o
        else if (o[id] === _s) sorter = o
      })

      if (!transformer) transformer = { transform: identity }
      if (!reducer) reducer = { reduce: identity }
      if (!finalizer) finalizer = { finalize: identity }
      if (!sorter) sorter = { sort: (item1, item2) => item1 - item2 }

      return {
        into(initialValue, ...items) {
          return items
            .reduce((acc, item) => {
              return reducer.reduce(
                acc,
                finalizer.finalize(transformer.transform(item)),
              )
            }, initialValue)
            .sort((item1, item2) => sorter.sort(item1, item2))
        },
      }
    },
  }
}

One of several key parts of the internal implementation are these lines:

Object.defineProperty(o, Symbol.keyFor(_id_), {
  configurable: false,
  enumerable: false,
  get() {
    return key
  },
})

This makes our template "official" because it hides the identifier from being seen from the outside and only exposes createTransformer, createReducer, createFinalizer, createSorter, and createPipeline to the consumer.

Another part that helps the template is the object above it:

const o = {
  [key](...args) {
    return fn?.(...args)
  },
}

This helps to structure a fluent api that reads like english:

into(initialValue, ...items) {
    return items
        .reduce((acc, item) => {
            return reducer.reduce(
                acc,
                finalizer.finalize(transformer.transform(item)),
            )
        }, initialValue)
        .sort((item1, item2) => sorter.sort(item1, item2))
}

Lets pretend we are the consumer and we want to use this template on this collection of dates as we've seen earlier:

const dates = [
  357289200000,
  989910000000,
  'Tue Jan 18 2005 00:00:00 GMT-0800 (Pacific Standard Time)',
  new Date(2001, 1, 03),
  new Date(2000, 8, 21),
  '1998-02-08T08:00:00.000Z',
  new Date(1985, 1, 11),
  '12/24/1985, 12:00:00 AM',
  new Date(2020, 6, 26),
  'Tue May 15 2001 00:00:00 GMT-0700 (Pacific Daylight Time)',
  1652252400000,
  '2005-01-18T08:00:00.000Z',
  new Date(2022, 7, 14),
  '1999-02-01T08:00:00.000Z',
  1520668800000,
  504259200000,
  '4/28/1981, 12:00:00 AM',
  '2015-08-08T07:00:00.000Z',
]

We have some issues:

They are in different data types. We want them all to be in ISO date format.
They are not sorted. We want them all to be sorted in ascending order.

We can use the code that implements the template design pattern to solve these issues so that we can get an ordered collection of dates in ISO format:

const isDate = (v) => v instanceof Date
const toDate = (v) => (isDate(v) ? v : new Date(v))
const subtract = (v1, v2) => v1 - v2
const concat = (v1, v2) => v1.concat(v2)

const reducer = factory.createReducer(concat)
const transformer = factory.createTransformer(toDate)
const finalizer = factory.createFinalizer(toDate)
const sorter = factory.createSorter(subtract)

const getResult = (...fns) => {
  const pipe = factory.createPipeline(...fns)
  return pipe.into([], ...dates)
}

console.log(getResult(reducer, transformer, finalizer, sorter))
console.log(getResult(transformer, reducer, finalizer, sorter))
console.log(getResult(finalizer, sorter, transformer, reducer))
console.log(getResult(sorter, finalizer, transformer, reducer))

It doesn't require much code and all of our executions return the same result:

[
  "1981-04-28T07:00:00.000Z",
  "1981-04-28T07:00:00.000Z",
  "1985-02-11T08:00:00.000Z",
  "1985-12-24T08:00:00.000Z",
  "1985-12-24T08:00:00.000Z",
  "1998-02-08T08:00:00.000Z",
  "1999-02-01T08:00:00.000Z",
  "2000-09-21T07:00:00.000Z",
  "2001-02-03T08:00:00.000Z",
  "2001-05-15T07:00:00.000Z",
  "2001-05-15T07:00:00.000Z",
  "2005-01-18T08:00:00.000Z",
  "2005-01-18T08:00:00.000Z",
  "2015-08-08T07:00:00.000Z",
  "2018-03-10T08:00:00.000Z",
  "2020-07-26T07:00:00.000Z",
  "2022-05-11T07:00:00.000Z",
  "2022-08-14T07:00:00.000Z"
]

Here is a diagram depicting our template:

And there you go!

Another Example

I like to use snabbdom to demonstrate concepts in several of my posts because it is short, simple, powerful and uses several techniques that are relative to the topics I wrote about in the past. Snabbdom is a front end JavaScript library that lets you work with a virtual DOM to create robust web applications. They focus on simplicity, modularity and performance.

They provide a module api where developers can create their own modules. They do this by providing to consumers a template that provides hooks that hook onto the lifecycle of a "patching" phase where DOM elements are passed around to life cycles. This is a simple but powerful way to work with the virtual DOM. It is a great example of one variation of a template pattern.

This is their template:

const myModule = {
  // Patch process begins
  pre() {
    //
  },
  // DOM node created
  create(_, vnode) {
    //
  },
  // DOM node is being updated
  update(oldVNode, vnode: VNode) {
    //
  },
  // Patching is done
  post() {
    //
  },
  // DOM node is being directly removed from DOM via .remove()
  remove(vnode, cb) {
    //
  },
  // DOM node is being removed by any method including removeChild
  destroy(vnode) {
    //
  },
}

Conclusion

And that concludes the end of this post! I hope you got something out of it and look out for more posts from me in the future!

The Power of Strategy Design Pattern in JavaScript

jsmanifest — Wed, 13 Apr 2022 03:20:31 +0000

JavaScript is a language that is very well known for its flexibility. You've probably heard people that say its one of JavaScript weaknesses or even some that say the total opposite. I tend to be more on the latter side because we tend to use this to our advantage to do amazing things that hardly seemed possible many years ago.

React is already a factual proof that backs that up as amazing tools were invented thereafter. There is also Electron which powers today's booming technology like Visual Studio Code and Figma.

Every JavaScript library uses some form of a design pattern nowadays which is also a hot topic in the modern JavaScript ecosystem. One design pattern that we will focus on in this post is the Strategy Design Pattern. And because JavaScript is so flexible it makes design patterns like the Strategy robust as we will see in this post.

In this post, we will be going over the Strategy Design Pattern. This is a well known pattern that encapsulates one or more strategies (or algorithms) to do a task. These encapsulated strategies all have the same signature so the context (the one who provides the interface) never knows when they are dealing with the same or different object (or strategy). This means that each strategy can be swapped together many times without our program ever realizing it during the lifetime of our app.

What kind of objects are involved?

In the Strategy pattern, these two objects are always involved:

Context
Strategy

The Context must always have a reference or pointer to the current strategy being used. That means if we have 200 strategies then it's optional that the other 199 are used. You can think of them as being "inactive".

The Context also provides the interface to the caller. The caller is the client. The caller can use any of the strategies to perform their work and they can also switch the current strategy with another strategy at any time on demand.

The actual Strategy implements the execution logic for itself that will be used when executed.

Strengths

In a normal function implementation the function is usually doing something and returns a value. In the Strategy Design Pattern when there is a base (Context) class and one Strategy it is like a function that calls the Strategy and returns the result (in other the words the same thing).

But when there are two or more strategies, the point is that the strategy can be one of many strategies controlled by the caller.

The major benefit here is that we can define as many strategies as we want and swap between each one to be used on demand without inflicting a single hint of change in behavior of code as long as the pattern is written the way it should.

Implementations of a Strategy can change but as long as they keep the same signature as expected by the context then there is no need to experience unnecessary changes to code.

Here is a diagram depicting this flow:

Implementation

Our first implementation will focus on fetching. We'll define a createFetcher function that returns the interface to create fetchers. These fetchers can be spawned by the client and can be implemented however they desire as long as they take in a url, retrieve and returns its response.

We'll be using the axios request library, node's native https module and the node-fetch library to implement as one strategy each.

In total we will have 3 strategies:

const axios = require('axios').default
const https = require('https')
const fetch = require('node-fetch')

function createFetcher() {
  const _identifer = Symbol('_createFetcher_')
  let fetchStrategy

  const isFetcher = (fn) => _identifer in fn

  function createFetch(fn) {
    const fetchFn = async function _fetch(url, args) {
      return fn(url, args)
    }
    fetchFn[_identifer] = true
    return fetchFn
  }

  return {
    get fetch() {
      return fetchStrategy
    },
    create(fn) {
      return createFetch(fn)
    },
    use(fetcher) {
      if (!isFetcher(fetcher)) {
        throw new Error(`The fetcher provided is invalid`)
      }
      fetchStrategy = fetcher
      return this
    },
  }
}

const fetcher = createFetcher()

const axiosFetcher = fetcher.create(async (url, args) => {
  try {
    return axios.get(url, args)
  } catch (error) {
    throw error
  }
})

const httpsFetcher = fetcher.create((url, args) => {
  return new Promise((resolve, reject) => {
    const req = https.get(url, args)
    req.addListener('response', resolve)
    req.addListener('error', reject)
  })
})

const nodeFetchFetcher = fetcher.create(async (url, args) => {
  try {
    return fetch(url, args)
  } catch (error) {
    throw error
  }
})

fetcher.use(axiosFetcher)

Inside our createFetcher function we created this line: const _identifer = Symbol('_createFetcher_')

This line is important because we want to ensure that each strategy created is actually a strategy otherwise our program will treat any passed in object as a strategy. It may sound like a positive benefit to have anything treated as a strategy but we would lose validity which makes our code more prone to errors which can easily deter our debugging experience if we misstep.

Symbol returns to us a unique variable by definition. It is also hidden within the implementation of the context, so there is no way that objects created outside of our create function will be treated as a strategy. They would have to use the method made publicly from the interface provided by the context.

When the client calls use it's submitting axiosFetcher to be the used as the current strategy and is then bound as a reference until the client swaps in another strategy via use.

Now we have three strategies for retrieving data:

const url = 'https://google.com'

fetcher.use(axiosFetcher)

fetcher
  .fetch(url, { headers: { 'Content-Type': 'text/html' } })
  .then((response) => {
    console.log('response using axios', response)
    return fetcher.use(httpsFetcher).fetch(url)
  })
  .then((response) => {
    console.log('response using node https', response)
    return fetcher.use(nodeFetchFetcher).fetch(url)
  })
  .then((response) => {
    console.log('response using node-fetch', response)
  })
  .catch((error) => {
    throw error instanceof Error ? error : new Error(String(error))
  })

Hurray! We've now seen how it can be implemented in code. But can we think of a situation in the real world where we need this? You can think of plenty actually! However if this is your first time reading about this pattern then I understand that it can be hard to think of a scenario beforehand unless we see one in practice first.

The examples we went over in this post shows the pattern implementation but anyone reading this can ask "Why bother implementing three fetcher strategies when you can just directly use one like axios to get the response and call it a day?"

In the upcoming example we will be going over a scenario where the Strategy Design Pattern is definitely needed.

Handling different data types

Where the strategy pattern shines most is when we need to handle different data types when doing something like sorting.

In the previous examples we didn't really care about any data types because we just wanted some response. But what happens when we receive a collection of something and needed to do some narrow task like categorizing them? What if they need to be sorted correctly?

When we need to sort several collections where each are a collection of another data type we can't just use the native .sort method on all of them because each value can be treated differently in terms of "less" and "greater".

We can use the Strategy Pattern and define different sets of sorting algorithms that are readily available in the runtime so that we can use them interchangeably on demand.

Consider these collections:

const nums = [2, -13, 0, 42, 1999, 200, 1, 32]
const letters = ['z', 'b', 'm', 'o', 'hello', 'zebra', 'c', '0']
const dates = [
  new Date(2001, 1, 14),
  new Date(2000, 1, 14),
  new Date(1985, 1, 14),
  new Date(2020, 1, 14),
  new Date(2022, 1, 14),
]
// Need to be sorted by height
const elements = [
  document.getElementById('submitBtn'),
  document.getElementById('submit-form'),
  ...document.querySelectorAll('li'),
]

We can create a Sort strategy class and a Sorter context class.

Note that they don't need to be classes. We're just choosing to use classes now to diversify the implementation a little:

const sorterId = Symbol('_sorter_')

class Sort {
  constructor(name) {
    this[sorterId] = name
  }

  execute(...args) {
    return this.fn(...args)
  }

  use(fn) {
    this.fn = fn
    return this
  }
}

class Sorter {
  sort(...args) {
    return this.sorter.execute.call(this.sorter, ...args)
  }

  use(sorter) {
    if (!(sorterId in sorter)) {
      throw new Error(`Please use Sort as a sorter`)
    }
    this.sorter = sorter
    return this
  }
}

const sorter = new Sorter()

It's pretty straight forward. Sorter keeps a reference to the Sort that is currently being used. This is the sort function that will be picked up when calling sort. Each Sort instance is a strategy and passed into use.

The Sorter does not know anything about the strategies. It does not know that there is a date sorter, number sorter, etc. It just calls the Sort's execute method.

However the client knows about all of the Sort instances and controls the strategies as well as the Sorter:

const sorter = new Sorter()

const numberSorter = new Sort('number')
const letterSorter = new Sort('letter')
const dateSorter = new Sort('date')
const domElementSizeSorter = new Sort('dom-element-sizes')

numberSorter.use((item1, item2) => item1 - item2)
letterSorter.use((item1, item2) => item1.localeCompare(item2))
dateSorter.use((item1, item2) => item1.getTime() - item2.getTime())
domElementSizeSorter.use(
  (item1, item2) => item1.scrollHeight - item2.scrollHeight,
)

With that said, its entirely up to us (the client) to handle this accordingly:

function sort(items) {
  const type = typeof items[0]
  sorter.use(
    type === 'number'
      ? numberSorter
      : type === 'string'
      ? letterSorter
      : items[0] instanceof Date
      ? dateSorter
      : items[0] && type === 'object' && 'tagName' in items[0]
      ? domElementSizeSorter
      : Array.prototype.sort.bind(Array),
  )
  return [...items].sort(sorter.sort.bind(sorter))
}

We now have a robust 15 line function that can sort 4 different variations of collections!

console.log('Sorted numbers', sort(nums))
console.log('Sorted letters', sort(letters))
console.log('Sorted dates', sort(dates))

And that is the power of the Strategy Design Pattern in JavaScript.

Thanks to the nature of JavaScript treating functions as values this code example blends in that capability to its advantage and works with the Strategy pattern seamlessly.

Conclusion

And that concludes the end of this post! I hope you found this to be useful and stay tuned for more useful tips in the future!!

Find me on medium

The Power of Memento Design Pattern in JavaScript

jsmanifest — Sun, 10 Apr 2022 14:03:27 +0000

The Memento Pattern in programming is useful in situations where we need a way to restore an object's state.

As a JavaScript developer we work with this concept in many situations especially now in modern web applications.

If you've been developing in the web for some time then you might have heard of the term hydration.

If you don't know what hydration is, it's a technique in web development where the client side takes static content which was stored in any programming language such as JSON, JavaScript, HTML, etc. and converts it into code where browsers are able to run during runtime. At that stage JavaScript is run and is able to do things like attach event listeners when the DOM begins running on the page.

The memento pattern is similar. In this post we are going to implement the Memento pattern for the runtime and will not be storing anything statically.

If you worked with JSON.parse and JSON.stringify chances are you might have accidentally implemented a memento before.

Usually there are three objects that implement the full flow of the Memento pattern:

Originator
Memento
Caretaker

The Originator defines the interface that triggers the creation and storing of itself as the memento.

The Memento is the internal state representation of the Originator that is passed and retrieved from the Caretaker.

The Caretaker has one job: to store or save the memento to be used later. It can retrieve the memento it stored but it does not mutate anything.

Implementing the Memento Design Pattern

Now that we described the pattern we are going to implement it to master this practice in code.

We will be creating an interactive email input field as a DOM element. We are going to add one smart behavior to our input field so that our user will immediately become aware that they need to add the @ symbol before submitting.

They will know this when their input field is in an error state which will look like this:

This is the html markup we are going to work right on top of:

<!DOCTYPE html>
<html>
  <head>
    <title>Memento</title>
    <meta charset="UTF-8" />
  </head>
  <body style="margin:50px;text-align:center;background:linear-gradient(
    76.3deg,
    rgba(44, 62, 78, 1) 12.6%,
    rgba(69, 103, 131, 1) 82.8%
  );height:250px;overflow:hidden;">
    <input type="email" id="emailInput" style="padding:12px;border-radius:4px;font-size:16px;" placeholder="Enter your email"></input>
    <script src="src/index.js"></script>
  </body>
</html>

This will start us off with this interface:

Now the first thing we are going to do is define a couple of constant variables for the error state that we will use throughout our code to assign as values to the error styles. This is to ensure that we don't make any typos when writing our code since we will be reusing them multiple times:

const ERROR_COLOR = 'tomato'
const ERROR_BORDER_COLOR = 'red'
const ERROR_SHADOW = `0px 0px 25px rgba(230, 0, 0, 0.35)`
const CIRCLE_BORDER = '50%'
const ROUNDED_BORDER = '4px'

This has nothing to do with the pattern but I think it's a good habit for me to randomly slip in some best practices just so you can get extra tips from this post, why not right? ;)

Now we are going to create a helper function that toggles between the error state and the normal state since we are going to be using this multiple times as well:

const toggleElementStatus = (el, status) => {
  if (status === 'error') {
    return Object.assign(el.style, {
      borderColor: ERROR_BORDER_COLOR,
      color: ERROR_COLOR,
      boxShadow: ERROR_SHADOW,
      outline: 'red',
    })
  }
  return Object.assign(el.style, {
    borderColor: 'black',
    color: 'black',
    boxShadow: '',
    outline: '',
  })
}

I might as well just slip in a helper to toggle the border radius while we toggle between the two style presets. This is to make our code feel more "natural" as if it was a real app so we don't just focus directly on the relationship between the colors and the memento in this post. Sometimes I think we learn better when we also see the perspective of random code vs the actual code that we are going over with:

const toggleBorderRadius = (el, preset) => {
  el.style.borderRadius =
    preset === 'rounded'
      ? ROUNDED_BORDER
      : preset === 'circle'
      ? CIRCLE_BORDER
      : '0px'
}

The next thing we are going to do is write the Originator.

Remember, the originator defines the interface that triggers the creation and storing of itself as the memento.

function createOriginator({ serialize, deserialize }) {
  return {
    serialize,
    deserialize,
  }
}

Actually, we just created a simply factory that produces the originator for us.

Here is the real originator:

const originator = createOriginator({
  serialize(...nodes) {
    const state = []

    nodes.forEach(
      /**
       * @param { HTMLInputElement } node
       */
      (node) => {
        const item = {
          id: node.id || '',
        }

        item.tagName = node.tagName.toLowerCase()

        if (item.tagName === 'input') {
          item.isError =
            node.style.borderColor === ERROR_BORDER_COLOR &&
            node.style.color === ERROR_COLOR
          item.value = node.value
        }

        item.isRounded = node.style.borderRadius === ROUNDED_BORDER
        item.isCircle = node.style.borderRadius === CIRCLE_BORDER

        state.push(item)
      },
    )

    return state
  },
  deserialize(...state) {
    const providedNode = state[state.length - 1]

    if (providedNode) state.pop()

    const nodes = []

    state.forEach((item) => {
      const node = providedNode || document.createElement(item.tagName)

      if (item.tagName === 'input') {
        if (item.isError) {
          toggleElementStatus(node, 'error')
        }
        if (item.isRounded) {
          toggleBorderRadius(node, 'rounded')
        } else if (item.isCircle) {
          toggleBorderRadius(node, 'circle')
        }
        node.value = item.value || ''
        if (item.placeholder) node.placeholder = item.placeholder
        if (item.id) node.id = item.id
      }

      nodes.push(node)
    })

    return nodes
  },
})

In the originator, the serialize method takes in a DOM node and returns us a state representation of the DOM node so that we can store it inside the local storage as a string. This is required because the local storage only accepts strings.

Right now we are the peak of this pattern in JavaScript. The serialization is the only reason why this pattern is important to us otherwise we'd be able to directly store DOM nodes to the local storage and call it a day.

Inside our serialize method we implicitly defined a couple of rules that help us determine the representation.

Here are the lines I'm referring to:

if (item.tagName === 'input') {
  item.isError =
    node.style.borderColor === ERROR_BORDER_COLOR &&
    node.style.color === ERROR_COLOR
  item.value = node.value
}

item.isRounded = node.style.borderRadius === ROUNDED_BORDER
item.isCircle = node.style.borderRadius === CIRCLE_BORDER

When storing mementos of input elements we have a choice whether to implement it that way or this way:

if (item.tagName === 'input') {
  item.style.borderColor = node.style.borderColor
  item.style.color = node.style.color
  item.value = node.value
}

item.style.borderRadius = node.style.borderRadius

Take my advice on this: A good practice is to create useful meaning out of your code especially in your design pattern implementations. When you inaugurate meaning in your code it it helps you to think of higher level abstractions that might be useful in other areas of your code.

Using item.isError to represent a preset of error styles opens up wider opportunities to make interesting reusable mementos that we can reuse as our project grows more complex over time as opposed to assigning arbitrary styles directly.

For example, it's common for forms to not submit when a crucial field is left unblank. The form must transition to some kind of state where it needs to stop itself from submitting.

If we were to save a memento of a form we need to ensure that when we restore this state the user is restored to the "disabled" state:

const originator = createOriginator({
  serialize(...nodes) {
    const state = []

    nodes.forEach(
      /**
       * @param { HTMLInputElement } node
       */
      (node) => {
        const item = {
          id: node.id || '',
        }

        item.tagName = node.tagName.toLowerCase()

        if (item.tagName === 'input') {
          item.isError =
            node.style.borderColor === ERROR_BORDER_COLOR &&
            node.style.color === ERROR_COLOR
          item.value = node.value
        }

        item.isRounded = node.style.borderRadius === ROUNDED_BORDER
        item.isCircle = node.style.borderRadius === CIRCLE_BORDER

        if (node.textContent) item.textContent = node.textContent

        state.push(item)
      },
    )

    return state
  },
  deserialize(state) {
    const nodes = []

    if (!Array.isArray(state)) state = [state]

    state.forEach((item) => {
      const node = document.createElement(item.tagName)

      if (item.style) {
        Object.entries(item.style).forEach(([key, value]) => {
          node.style[key] = value
        })
      }

      if (item.isRounded) {
        toggleBorderRadius(node, 'rounded')
      } else if (item.isCircle) {
        toggleBorderRadius(node, 'circle')
      }

      if (item.spacing) {
        node.style.padding = item.spacing
      }

      if (item.id) node.id = item.id

      if (item.tagName === 'input') {
        if (item.isError) {
          toggleElementStatus(node, 'error')
        }
        node.value = item.value || ''
        if (item.placeholder) node.placeholder = item.placeholder
      } else if (item.tagName === 'label') {
        if (item.isError) {
          node.style.color = ERROR_COLOR
        }
      } else if (item.tagName === 'select') {
        if (item.options) {
          item.options.forEach((obj) => {
            node.appendChild(...originator.deserialize(obj, node))
          })
        }
      }

      if (item.textContent) node.textContent = item.textContent

      nodes.push(node)
    })

    return nodes
  },
})

const caretaker = createCaretaker()

function restore(state, container, { onRendered } = {}) {
  let statusSubscribers = []
  let status = ''

  const setStatus = (value, options) => {
    status = value
    statusSubscribers.forEach((fn) => fn(status, options))
  }

  const renderMemento = (memento, container) => {
    return originator.deserialize(memento).map((el) => {
      container.appendChild(el)

      if (memento.isError && status !== 'error') {
        setStatus('error')
      }

      if (memento.children) {
        memento.children.forEach((mem) => {
          renderMemento(mem, el).forEach((childEl) => el.appendChild(childEl))
        })
      }

      return el
    })
  }

  const render = (props, container) => {
    const withStatusObserver = (fn) => {
      statusSubscribers.push((updatedStatus) => {
        if (updatedStatus === 'error') {
          // Do something
        }
      })

      return (...args) => {
        const elements = fn(...args)
        return elements
      }
    }

    const renderWithObserver = withStatusObserver(renderMemento)

    const elements = renderWithObserver(props, container)
    statusSubscribers.length = 0
    return elements
  }

  const elements = render(state, container)

  if (onRendered) onRendered(status, elements)

  return {
    status,
    elements,
  }
}

const container = document.getElementById('root')

const { status, elements: renderedElements } = restore(mementoJson, container, {
  onRendered: (status, elements) => {
    if (status === 'error') {
      const submitBtn = container.querySelector('#submit-btn')
      submitBtn.disabled = true
      submitBtn.textContent = 'You have errors'
      toggleElementStatus(submitBtn, 'error')
    }
  },
})

Instead of returning the elements directly we make sure that what's also returned is the current state of rendering the memento.

Looking at this in a higher level perspective we take advantage of the fact that isError can represent and overview of something like a form. A form should not be submitted if either one little required field is missing or a value was not entered correctly.

In that case we make sure that the form should not be interactive by disabling the submit button right before displaying to the user:

If you haven't noticed, our restore wraps our original deserialize method from our Originator.

What we have now is a higher level abstracted memento that supports deep children and the rendering state (isError) of our entire memento.

Conclusion

And that concludes the end of this post! I hope you found this to be valuable and look out for more in the future!

Find me on medium

State Design Pattern in JavaScript

jsmanifest — Thu, 07 Apr 2022 15:43:54 +0000

The State Pattern ensures an object to behave in a predictable, coordinated way depending on the current "state" of the application.

A behavior is defined on a state object that is responsible for running some handler when the overall state transitions to its own state. The interface that these state objects operate on is called the Context.

The way this pattern works in practice is that by delegating the work of certain actions to the state objects that represent a piece of the state, the action that represents the piece of the state is responsible for updating it from their handling of that state.

This means that the Context may have one or more handlers but ultimately the state objects that hold a reference to the Context trigger state changes entirely amongst themselves one at a time.

This is because state objects define handlers that triggers actions that can determine what the next state transitions to based on what happens from the handler.

What Problems Does The State Pattern Solve?

The most important problem it solves is when your state becomes large and there are many cases. It becomes hard to debug issues when our application's state can change in many ways especially when our application becomes enormous.

redux is a library that is succeessful in providing an easy-to-use, predictable interface to solve complex state issues.

Implementation

Pretend we are implementing some sort of state where we will be working with a counter:

const state = {
  counter: 0,
  color: 'green',
}

The counter starts at 0 and every second we will increment the counter by 1. The color stays "green" if the counter is less than 5. If the counter is between 5 and 7 the color will be "orange". And finally, if the counter is 8 or higher the color will be set to "red".

Without the state pattern this can be implemented with something like this:

function start({ onEachInterval }) {
  let color = 'green'
  let counter = 0

  let intervalRef = setInterval(() => {
    counter++
    if (color > 5) {
      if (color < 8) color = 'orange'
      else color = 'red'
    }
    onEachInterval({ counter, color })
  }, 1000)

  setTimeout(() => {
    clearInterval(intervalRef)
    console.log(`Timer has ended`)
  }, 10000)
}

start({
  onEachInterval({ counter, color }) {
    console.log(`The current counter is ${counter} `)
  },
})

It's pretty simple and gets the job done. Since this code is very short there's no need to implement the state pattern because it would be overkill.

Lets say that our code grows to 5000 lines overtime. Think about it. Do you think you would have an easy time unit testing your program? You won't if your code is perfect everytime time but there's really no such thing as a developer who never mistakes in large applications. There's bound to be some errors at some point so it is at our best interest that we should be careful and make wise decisions when writing code. Code should always be easy to test.

That's why the State Pattern is useful because it is easily testable and is scalable for applications with large or complex state.

When we run that code snippet we get this:

The current counter is 1
The current counter is 2
The current counter is 3
The current counter is 4
The current counter is 5
The current counter is 6
The current counter is 7
The current counter is 8
The current counter is 9
Timer has ended

Which means our code is working. Inside our start function the implementation is written once but there's hardly any control. Control is also another benefit of the State Pattern.

Lets see how this looks like using the State Pattern:

function createStateApi(initialState) {
  const ACTION = Symbol('_action_')

  let actions = []
  let state = { ...initialState }
  let fns = {}
  let isUpdating = false
  let subscribers = []

  const createAction = (type, options) => {
    const action = { type, ...options }
    action[ACTION] = true
    return action
  }

  const setState = (nextState) => {
    state = nextState
  }

  const o = {
    createAction(type, handler) {
      const action = createAction(type)
      if (!fns[action.type]) fns[action.type] = handler
      actions.push(action)
      return action
    },
    getState() {
      return state
    },
    send(action, getAdditionalStateProps) {
      const oldState = state

      if (isUpdating) {
        return console.log(`Subscribers cannot update the state`)
      }

      try {
        isUpdating = true
        let newState = {
          ...oldState,
          ...getAdditionalStateProps?.(oldState),
          ...fns[action.type]?.(oldState),
        }
        setState(newState)
        subscribers.forEach((fn) => fn?.(oldState, newState, action))
      } finally {
        isUpdating = false
      }
    },
    subscribe(fn) {
      subscribers.push(fn)
    },
  }

  return o
}

const stateApi = createStateApi({ counter: 0, color: 'green' })

const changeColor = stateApi.createAction('changeColor')

const increment = stateApi.createAction('increment', function handler(state) {
  return {
    ...state,
    counter: state.counter + 1,
  }
})

stateApi.subscribe((oldState, newState) => {
  if (oldState.color !== newState.color) {
    console.log(`Color changed to ${newState.counter}`)
  }
})

stateApi.subscribe((oldState, newState) => {
  console.log(`The current counter is ${newState.counter}`)
})

let intervalRef = setInterval(() => {
  stateApi.send(increment)
  const state = stateApi.getState()
  const currentColor = state.color
  if (state.counter > 8 && currentColor !== 'red') {
    stateApi.send(changeColor, (state) => ({ ...state, color: 'red' }))
  } else if (state.counter >= 5 && currentColor !== 'orange') {
    stateApi.send(changeColor, (state) => ({ ...state, color: 'orange' }))
  } else if (state.counter < 5 && currentColor !== 'green') {
    stateApi.send(changeColor, (state) => ({ ...state, color: 'green' }))
  }
}, 1000)

setTimeout(() => {
  clearInterval(intervalRef)
  console.log(`Timer has ended`)
}, 10000)

There's a couple things to pick from the example.

The line const ACTION = Symbol('_action_') is not used on the rest of the code but I wanted to mention that it's a good practice to use this strategy to validate that the actions being sent to the send method are actual actions that are intended to update the state.

For example we can immediately do this validation at the beginning of our send method:

send(action, getAdditionalStateProps) {
    if (!(ACTION in action)) {
        throw new Error(`The object passed to send is not a valid action object`)
    }
    const oldState = state

    if (isUpdating) {
        return console.log(`Subscribers cannot update the state`)
    }

If we don't do this our code can be more error prone because we can just pass in any object like this and it will still work:

function start() {
  send({ type: 'increment' })
}

This may seem like a positive thing but we want to make sure that the only actions that trigger updates to state are specifically those objects produced by the interface we provide publicly to them via createAction. For debugging purposely we want to narrow down the complexity and be ensured that errors are coming from the right locations.

The next thing we are going to look at are these lines:

const increment = stateApi.createAction('increment', function handler(state) {
  return {
    ...state,
    counter: state.counter + 1,
  }
})

Remember earlier we state (no pun intended) that:

The way this pattern works in practice is that by delegating the work of certain actions to the state objects that represent a piece of the state, the action that represents the piece of the state is responsible for updating it from their handling of that state.

We defined an increment action that is responsible for incrementing it every second when consumed via send. It receives the current state and takes the return values to merge onto the next state.

We're now able to isolated and unit test this behavior for this piece of state easily:

npx mocha ./dev/state.test.js

const { expect } = require('chai')
const { createStateApi } = require('./patterns')

describe(`increment`, () => {
  it(`should increment by 1`, () => {
    const api = createStateApi({ counter: 0 })
    const increment = api.createAction('increment', (state) => ({
      ...state,
      counter: state.counter + 1,
    }))
    expect(api.getState()).to.have.property('counter').to.eq(0)
    api.send(increment)
    expect(api.getState()).to.have.property('counter').to.eq(1)
  })
})

increment
    ✔ should increment by 1


1 passing (1ms)

In our first example we had the implementation hardcoded into the function. Again, unit testing that function is going to be difficult. We won't able to isolate separate parts of the code like we did here.

Isolation is powerful in programming. State Pattern lets us isolate. Isolation provides wider range of possibilities to compose pieces together which is easily achievable now:

it(`should increment by 5`, () => {
  const api = createStateApi({ counter: 0 })

  const createIncrementener = (amount) =>
    api.createAction('increment', (state) => ({
      ...state,
      counter: state.counter + amount,
    }))

  const increment = createIncrementener(5)
  expect(api.getState()).to.have.property('counter').to.eq(0)
  api.send(increment)
  expect(api.getState()).to.have.property('counter').to.eq(5)
})

Remember, we also mentioned that the State Pattern is scalable. As our application grows in size the pattern protects us with useful compositional capabilities to fight the scalability:

it(`should increment from composed math functions`, () => {
  const addBy = (amount) => (counter) => counter + amount
  const multiplyBy = (amount) => (counter) => counter * amount

  const api = createStateApi({ counter: 0 })

  const createIncrementener = (incrementBy) =>
    api.createAction('increment', (state) => ({
      ...state,
      counter: incrementBy(state.counter),
    }))

  const applyMathFns =
    (...fns) =>
    (amount) =>
      fns.reduceRight((acc, fn) => (acc += fn(acc)), amount)

  const increment = api.createAction(
    'increment',
    createIncrementener(applyMathFns(addBy(5), multiplyBy(2), addBy(1))),
  )

  api.send(increment)

  expect(api.getState()).to.have.property('counter').to.eq(11)
})

The moral of the story? The State Pattern works.

The bigger picture

To finalize this post here is a visual perspective of the State Design Pattern:

Conclusion

And that concludes the end of this post! I hope you found this to be valuable and look out for more in the future!

Find me on medium

The Power of Proxy Pattern in JavaScript

jsmanifest — Tue, 05 Apr 2022 14:24:37 +0000

One of the more interesting patterns I learned on a later stage of my career is the Proxy.

When you look for examples of the Proxy pattern you might often see different variations of implementations. That's because the Proxy is not limited to one use case. One proxy may act as a validator while the other may be more interested in improving performance, etc.

The idea is that by utilizing a proxy we wrap existing objects that functions the same as the original where its methods (or even properties) are exactly identical until we add additional logic inside the wrapped methods before the wrapped function is called. This is is a process completely hidden to the outside world, and this call will always appear the same to the caller.

In other words the proxy sits right in between the client of an object and the actual object itself. This is where it can choose to act as a "protector" or add custom logic such as caching without the caller ever knowing this. Because of this it can sometimes be referred to as the Mediator. Some may also categorize it as another form of a Decorator pattern, but there are some differences.

In this post we will be going over the power of the Proxy Design Pattern in JavaScript and go over several examples of how beneficial it can become for your next application.

Since JavaScript natively added a Proxy class that implements the pattern, we will be directly using the Proxy class instead to demonstrate the pattern after a couple vanilla implementations.

Difference between Decorator vs Proxy

In the decorator pattern, the decorator's main responsibility is to enhance the object it is wrapping (or "decorating"), whereas the proxy has more accessibility and controls the object.

The proxy may choose to enhance the object it is wrapping or control it in other ways such as restricting access from the outside world, but a decorator instead informs and applies enhancements.

The difference responsibility-wise is clear. Engineers commonly use decorators to add new behavior or as a form of an adapter for old or legacy classes where they return an enhanced interface that the client may know about but doesn't care about at the same time. The proxy is usually intended to be returning the same interface where the client may assume it is working with the same object untouched.

Validator/Helper

The first implementation of a Proxy pattern I will be showing here will be a validator.

This example shows the pattern being implemented as a way to help validate input and protect properties from being set the wrong data types. Remember that the caller must always assume that it is working with the original object so the Proxy must not change the signature or interface of the object it is wrapping:

class Pop {
  constructor(...items) {
    this.id = 1
  }
}

const withValidator = (obj, field, validate) => {
  let value = obj[field]

  Object.defineProperty(obj, field, {
    get() {
      return value
    },
    set(newValue) {
      const errMsg = validate(newValue)
      if (errMsg) throw new Error(errMsg)
      value = newValue
    },
  })

  return obj
}

let mello = new Pop(1, 2, 3)

mello = withValidator(mello, 'id', (newId) => {
  if (typeof newId !== 'number') {
    return `The id ${newId} is not a number. Received ${typeof newId} instead`
  }
})

mello.id = '3'

This example shows a simple helper that validates fields of an object, throwing a TypeError exception when the validation fails.

The Proxy takes ownership of the getter and setter of the id property and chooses to allow or reject values that are attempted to be set.

In the Proxy class it can be implemented with something like this:

const withValidator = (obj, field, validate) => {
  return new Proxy(obj, {
    set(target, prop, newValue) {
      if (prop === field) {
        const errMsg = validate(newValue)
        if (errMsg) throw new TypeError(errMsg)
        target[prop] = newValue
      }
    },
  })
}

let mello = new Pop(1, 2, 3)

mello = withValidator(mello, 'id', (newId) => {
  if (typeof newId !== 'number') {
    return `The id ${newId} is not a number. Received ${typeof newId} instead`
  }
})

mello.id = '3'

The validator works perfectly:

TypeError: The id 3 is not a number. Received string instead

Clipboard Polyfill

This section will go over using the Proxy as a way to support older browsers when copying selections of text into the users clipboard by ensuring that the browser supports the Navigator.clipboard API. If it doesn't, then it will fall back to using execCommand to copy the selection.

Again, the client will always assume that the object it is calling methods on is the original object and only knows that it's calling the said method:

const withClipboardPolyfill = (obj, prop, cond, copyFnIfCond) => {
  const copyToClipboard = (str) => {
    if (cond()) {
      copyFnIfCond()
    } else {
      const textarea = document.createElement('textarea')
      textarea.value = str
      textarea.style.visibility = 'hidden'
      document.body.appendChild(textarea)
      textarea.select()
      document.execCommand('copy')
      document.body.removeChild(textarea)
    }
  }
  obj[prop] = copyToClipboard
  return obj
}

const api = (function () {
  const o = {
    copyToClipboard(str) {
      return navigator.clipboard.writeText(str)
    },
  }
  return o
})()

let copyBtn = document.createElement('button')
copyBtn.id = 'copy-to-clipboard'
document.body.appendChild(copyBtn)

copyBtn.onclick = api.copyToClipboard

copyBtn = withClipboardPolyfill(
  copyBtn,
  'onclick',
  () => 'clipboard' in navigator,
  api.copyToClipboard,
)

copyBtn.click()

You might ask what is the point of applying the proxy in situations like this instead of directly hardcoding the implementation inside the actual copyToClipboard function. If we utilize a proxy we can reuse it as a standalone and freely change the implementation via inversion of control.

Another benefit from using this strategy is that we don't modify the original function.

Cacher (Enhancing performance)

Caching can take in many different forms in many different scenarios. For example there is a Stale While Revalidate for http requests, nginx content caching, cpu caching, lazy loading caching, memoization. etc.

In JavaScript we can also achieve caching with the help of a Proxy.

To implement the proxy pattern without directly using the Proxy class we can do something like this:

const simpleHash = (str) =>
  str.split('').reduce((acc, str) => (acc += str.charCodeAt(0)), '')

const withMemoization = (obj, prop) => {
  const origFn = obj[prop]
  const cache = {}

  const fn = (...args) => {
    const hash = simpleHash(args.map((arg) => String(arg)).join(''))
    if (!cache[hash]) cache[hash] = origFn(...args)
    return cache[hash]
  }

  Object.defineProperty(obj, prop, {
    get() {
      return fn
    },
  })

  return obj
}

const sayHelloFns = {
  prefixWithHello(str) {
    return `[hello] ${str}`
  },
}

const enhancedApi = withMemoization(sayHelloFns, 'prefixWithHello')
enhancedApi.prefixWithHello('mike')
enhancedApi.prefixWithHello('sally')
enhancedApi.prefixWithHello('mike the giant')
enhancedApi.prefixWithHello('sally the little')
enhancedApi.prefixWithHello('lord of the rings')
enhancedApi.prefixWithHello('lord of the rings')
enhancedApi.prefixWithHello('lord of the rings')
enhancedApi.prefixWithHello('lord of the rings')
enhancedApi.prefixWithHello('lord of the rings')

Cache:

{
  "109105107101": "[hello] mike",
  "11597108108121": "[hello] sally",
  "109105107101321161041013210310597110116": "[hello] mike the giant",
  "115971081081213211610410132108105116116108101": "[hello] sally the little",
  "108111114100321111023211610410132114105110103115": "[hello] lord of the rings"
}

Implementing this directly in a Proxy class is straight forward:

const withMemoization = (obj, prop) => {
  const origFn = obj[prop]
  const cache = {}

  const fn = (...args) => {
    const hash = simpleHash(args.map((arg) => String(arg)).join(''))
    if (!cache[hash]) cache[hash] = origFn(...args)
    return cache[hash]
  }

  return new Proxy(obj, {
    get(target, key) {
      if (key === prop) {
        return fn
      }
      return target[key]
    },
  })
}

The `Proxy` class

We've seen a persistent pattern in a couple of barebones Proxy pattern implementation vs directly using the Proxy class. Since JavaScript directly provides Proxy as an object into the language, the rest of this post will be using this as a convenience.

All remaining examples can be achieved without the Proxy, but we will be focusing on the class syntax instead because it is more concise and easier to work with especially for the sake of this post.

Proxy to Singleton

If you've never heard of a Singleton, it's another design pattern that ensures that an object of interest will be returned and reused if it's already instantiated throughout the lifetime of an application. In practice you will most likely see this being used as some global variable.

For example, if we were coding an MMORPG game and we had three classes Equipment, Person, and Warrior where there can only be one Warrior in existence, we can use the construct handler method inside the second argument when instantiating a Proxy on the Warrior class:

class Equipment {
  constructor(equipmentName, type, props) {
    this.id = `_${Math.random().toString(36).substring(2, 16)}`
    this.name = equipmentName
    this.type = type
    this.props = props
  }
}

class Person {
  constructor(name) {
    this.hp = 100
    this.name = name
    this.equipments = {
      defense: {},
      offense: {},
    }
  }

  attack(target) {
    target.hp -= 5
    const weapons = Object.values(this.equipments.offense)
    if (weapons.length) {
      for (const weapon of weapons) {
        console.log({ weapon })
        target.hp -= weapon.props.damage
      }
    }
  }

  equip(equipment) {
    this.equipments[equipment.type][equipment.id] = equipment
  }
}

class Warrior extends Person {
  constructor() {
    super(...arguments)
  }

  bash(target) {
    target.hp -= 15
  }
}

function useSingleton(_Constructor) {
  let _warrior

  return new Proxy(_Constructor, {
    construct(target, args, newTarget) {
      if (!_warrior) _warrior = new Warrior(...args)
      return _warrior
    },
  })
}

const WarriorSingleton = useSingleton(Warrior)

If we try to create multiple instances of Warrior we are ensured that only the first one created is used every time:

const mike = new WarriorSingleton('mike')
const bob = new WarriorSingleton('bob')
const sally = new WarriorSingleton('sally')

console.log(mike)
console.log(bob)
console.log(sally)

Result:

Warrior {
  hp: 100,
  name: 'mike',
  equipments: { defense: {}, offense: {} }
}
Warrior {
  hp: 100,
  name: 'mike',
  equipments: { defense: {}, offense: {} }
}
Warrior {
  hp: 100,
  name: 'mike',
  equipments: { defense: {}, offense: {} }
}

Cookie Stealer

In this section we will demonstrate an example using a Proxy to prevent mutations from a list of cookies. This will prevent the original object from being mutated and the mutator (the CookieStealer) will assume that their evil operation was a success.

Lets take a look at this example:

class Food {
  constructor(name, points) {
    this.name = name
    this.points = points
  }
}

class Cookie extends Food {
  constructor() {
    super(...arguments)
  }

  setFlavor(flavor) {
    this.flavor = flavor
  }
}

class Human {
  constructor() {
    this.foods = []
  }

  saveFood(food) {
    this.foods.push(food)
  }

  eat(food) {
    if (this.foods.includes(food)) {
      const foodToEat = this.foods.splice(this.foods.indexOf(food), 1)[0]
      this.hp += foodToEat.points
    }
  }
}

const apple = new Food('apple', 2)
const banana = new Food('banana', 2)

const chocolateChipCookie = new Cookie('cookie', 2)
const sugarCookie = new Cookie('cookie', 2)
const butterCookie = new Cookie('cookie', 3)
const bakingSodaCookie = new Cookie('cookie', 3)
const fruityCookie = new Cookie('cookie', 5)

chocolateChipCookie.setFlavor('chocolateChip')
sugarCookie.setFlavor('sugar')
butterCookie.setFlavor('butter')
bakingSodaCookie.setFlavor('bakingSoda')
fruityCookie.setFlavor('fruity')

const george = new Human()

george.saveFood(apple)
george.saveFood(banana)
george.saveFood(chocolateChipCookie)
george.saveFood(sugarCookie)
george.saveFood(butterCookie)
george.saveFood(bakingSodaCookie)
george.saveFood(fruityCookie)

console.log(george)

George's food:

 {
  foods: [
    Food { name: 'apple', points: 2 },
    Food { name: 'banana', points: 2 },
    Cookie { name: 'cookie', points: 2, flavor: 'chocolateChip' },
    Cookie { name: 'cookie', points: 2, flavor: 'sugar' },
    Cookie { name: 'cookie', points: 3, flavor: 'butter' },
    Cookie { name: 'cookie', points: 3, flavor: 'bakingSoda' },
    Cookie { name: 'cookie', points: 5, flavor: 'fruity' }
  ]
}

We instantiated george using the Human class and we added 7 items of food to its storage. George is happy he is about to eat his fruits and cookies. He is especially excited about his cookies because he's gotten his favorite flavors all at the same time, soon to be gobbling on them to satisfy his cravings for cookies.

However, there is an issue:

const CookieStealer = (function () {
  const myCookiesMuahahaha = []

  return {
    get cookies() {
      return myCookiesMuahahaha
    },
    isCookie(obj) {
      return obj instanceof Cookie
    },
    stealCookies(person) {
      let indexOfCookie = person.foods.findIndex(this.isCookie)
      while (indexOfCookie !== -1) {
        const food = person.foods[indexOfCookie]
        if (this.isCookie(food)) {
          const stolenCookie = person.foods.splice(indexOfCookie, 1)[0]
          myCookiesMuahahaha.push(stolenCookie)
        }
        indexOfCookie = person.foods.findIndex(this.isCookie)
      }
    },
  }
})()

CookieStealer.stealCookies(george)

The CookieStealer comes out of the blue to steal his cookies. The CookieStealer now has the 5 cookies in his storage:

[
  Cookie { name: 'cookie', points: 2, flavor: 'chocolateChip' },
  Cookie { name: 'cookie', points: 2, flavor: 'sugar' },
  Cookie { name: 'cookie', points: 3, flavor: 'butter' },
  Cookie { name: 'cookie', points: 3, flavor: 'bakingSoda' },
  Cookie { name: 'cookie', points: 5, flavor: 'fruity' }
]

George:

Human {
  foods: [
    Food { name: 'apple', points: 2 },
    Food { name: 'banana', points: 2 }
  ]
}

If we were to rewind back and introduce our savior Superman to apply one of his methods that implement the Proxy pattern to prevent the CookieStealer from his evil acts it would solve our issue:

class Superman {
  protectFromCookieStealers(obj, key) {
    let realFoods = obj[key]
    let fakeFoods = [...realFoods]

    return new Proxy(obj, {
      get(target, prop) {
        if (key === prop) {
          fakeFoods = [...fakeFoods]

          Object.defineProperty(fakeFoods, 'splice', {
            get() {
              return function fakeSplice(...[index, removeCount]) {
                fakeFoods = [...fakeFoods]
                return fakeFoods.splice(index, removeCount)
              }
            },
          })

          return fakeFoods
        }
        return target[prop]
      },
    })
  }
}

const superman = new Superman()
const slickGeorge = superman.protectFromCookieStealers(george, 'foods')

Our friend superman luckily happens to have a protectFromCookieStealers using the power of the Proxy to fake a list of cookies! He keeps the real collection of foods that contain george's cookies hidden away from the CookieStealer. CookieStealer proceeds with his evil plans and is seemingly tricked into thinking he got away with the cookies:

CookieStealer.stealCookies(slickGeorge)

console.log(CookieStealer.cookies)

The CookieStealer walks away with cookies in his storage still and thinks he got away with it:

[
  Cookie { name: 'cookie', points: 2, flavor: 'chocolateChip' },
  Cookie { name: 'cookie', points: 2, flavor: 'sugar' },
  Cookie { name: 'cookie', points: 3, flavor: 'butter' },
  Cookie { name: 'cookie', points: 3, flavor: 'bakingSoda' },
  Cookie { name: 'cookie', points: 5, flavor: 'fruity' }
]

Little does he know that he was tricked by superman and those were fake cookies! george still has his cookies untouched thanks to the power of Proxy saving him from the darkness of evil:

console.log(slickGeorge)

Human {
  foods: [
    Food { name: 'apple', points: 2 },
    Food { name: 'banana', points: 2 },
    Cookie { name: 'cookie', points: 2, flavor: 'chocolateChip' },
    Cookie { name: 'cookie', points: 2, flavor: 'sugar' },
    Cookie { name: 'cookie', points: 3, flavor: 'butter' },
    Cookie { name: 'cookie', points: 3, flavor: 'bakingSoda' },
    Cookie { name: 'cookie', points: 5, flavor: 'fruity' }
  ]
}

Conclusion

I hope this helped shed some light on the Proxy pattern and how to take advantage of this concept using the now built-in Proxy class in JavaScript.

That concludes the end of this post :) I hope you found this article helpful to you, and make sure to follow me on medium for future posts!

Find me on medium

11 JavaScript Examples to Source Code That Reveal Design Patterns In Use

jsmanifest — Mon, 21 Mar 2022 01:30:31 +0000

While we write code for web applications we are constantly trying to make good decisions. It's not always an easy task especially when our code becomes larger over time.

Fortunately there are some techniques we can incorporate into our code to solve complex issues. They're called design patterns.

This post will go over several source codes in the JavaScript world that you can look at to find some inspiration, answers, or even as a learning experience so that you can speed up your pace in learning the advanced coding techniques without feeling alone.

I noticed that not many articles out there directly reveal the patterns that are used in source codes and leave that task to the audience. I don't know about you but when I was new to programming this would have been very helpful. Don't worry, I got you covered.

Builder Design Pattern

One of my favorite libraries demonstrating the builder pattern in practice is spotify-web-api-node.

The builder design pattern is a behavior pattern that helps to construct objects that are otherwise complex without it.

This library constructs a builder that makes up a good majority of its implementation. For example most of its methods construct requests using one builder that reads like english:

Envision this without the builder providing this interface and you will see the benefit that the builder does for you.

Chaining / Fluent interfaces

We have actually just seen this technique in the last example, but we can also talk about jQuery that takes advantage of chaining methods together resulting in an easy to read fluent api to work with.

We are talking about a library that took the JavaScript community by storm before modern frameworks like React took their way into the scene, so this pattern is proven to be useful in programming.

jQuery was so popular back in the day that front end job listings preferred candidates with experience in jQuery. Although it isn't as popular as before, it is still being used by plenty of companies today.

cheerio is a library I still use today that was heavily inspired by the jQuery library, and remains popular today when topics like web scraping come up. It uses chaining to manipulate DOM nodes similarly to jQuery.

The moral of the story? It works.

Life cycles

As you start building more projects there will be a moment in time where you need to integrate some type of life cycle pipeline to ensure that functions are being processed in the correct time of events.

When consumed this can be useful to functions outside that need to tap into specific timing of events like manipulating DOM nodes after they are done applying their style attributes.

A good repository to learn from this concept is snabbdom, a virtual DOM library that focuses on simplicity, modularity, and powerful features to improve performance when working with the DOM.

They provide an extensible module api that allow developers to create their own modules to attach onto the main patch function. The core implementation of each module is to tap into these life cycles which is what makes this library work in the way that it does for our web applications.

For example they provide an optional event listeners module that hooks into this life cycle and ensures that event handlers are correctly attached and cleaned up between each patch (in other words each "rerender").

Command Design Pattern

Like jQuery, redux also soared in popularity but mostly within applications that needed to manage state which was basically every react app. It is by far my favorite example of the command pattern used in practice.

The pattern is facilitated through the concept of dispatching actions where each action is the command. Their documentation exclusively mentions that the only way to change its state is by dispatching actions.

The benefits this pattern provides are the main reasons it was popularized in react. Redux takes advantage of the command pattern by separating the objects that invoke actions away from those that know what to when they are being invoked. This is a perfect combination when used in conjunction with react. React is mostly about composition and separation of concerns between dumb and smart components. (However there are still different ways to architect react apps that don't utilize the concept of smart and dumb components).

Powerful middlewares were created to squeeze the most of the pattern's advantages such as being able to time travel in the redux devtools extension.

Modularity

When I first landed my eyes on the lodash repository to examine how their functions were structured, there were times I asked my self "What is the point of this function being here?" because functions like flowRight import another function just to call the function and return the result.

But over time as I started gaining more hands on experience I realized the beauty in structuring our modules/utility functions this way.

It helps you to think in the concept of reusability, functions with a single responsibility, and DRY (Do Not Repeat Yourself) when you write code. The benefit I take away from flowRight structured in the way that it is is that by depending on flow to do the "flow" logic, it only needs to be responsible for "flowing them to the right". Also, realize that if there updates in the impementation of flow, it automatically reflects in flowRight as well as all other functions that import flow.

Abstract Syntax Trees and the Composite Design Pattern

I'll be honest, my approach to getting used to working with ASTs is a bit weird, but it worked for me. For some reason the thought of working with the TypeScript AST sounds really attractive to me. I'm sure most people recommend to start deep diving into babel first before getting used to working with an AST with the TypeScript compiler, but I started it the other way around. There is a great library called ts-morph that focuses on making it easier for developers to work with the TypeScript compiler. Learning hands on with ts-morph while getting used to their compiler api made babel much easier to understand without ever touching babel.

You will also notice that a lot of objects you work with share a similar interface. This is their interface exposed to consumers that uses the composite design pattern.

Proxy Design Pattern

The Proxy pattern provides a placeholder object to act as the real object. It controls access to the real object.

immer uses this pattern by returning to us a draft that represents the object you give to the produce function. What it gets from this pattern is immutability which is great for react apps.

Observer / PubSub Design Pattern

One library that uses this pattern extensively is twilio-video.js. Almost every object ultimately extends the EventEmitter whether by directly extending it or by inheritance.

Their core objects like Participant implements this pattern extensively which enable consumers of the api to create an event driven video chat experiences in their apps.

For example to observe when a users' (or participant) media tracks are ready (these are what gets attached to the DOM and start the streaming) you would observe their remote participant object in code via someParticipant.on('trackSubscribed', () => {...}) and handle it accordingly.

Chain of Responsibility Design Pattern

Implementing chain of responsibility in JavaScript usually involves a pipeline of loosely coupled functions where one or more can handle the request.

The best example demonstrating this pattern is the expressjs library through the concept of route handling.

For example, if you create a route handler for the route /dogs and one for /dogs?id=3 and a user has navigated to /dogs?id=3, there will be a chain of handlers invoking where /dogs will get called first and can decide to handle this request or pass it on to the second handler that will get to decide from there, and so on.

Visitor Design Pattern

You will rarely see this pattern implemented in practice until you start digging deeper into tools. The visitor pattern is useful in cases where you want to work with each object in ASTs by "visiting" each AST node.

Visitors are used for many reasons like extensibility, plugins, printing an entire schema somewhere, etc.

Here is an implementation of one from the graphql repository

Prototype Design Pattern

The Prototype pattern's main concern is to ensure that objects being created are not new instances each time. This means if we create an object MathAdd with a method add, we should just reuse add when we created multiple instances of MathAdd since the implementation doesn't change. This is a performance benefit as well.

The request library uses this pattern on nearly all of their class objects.

Conclusion

And that concludes the end of this post! I hope you found this valuable and look out for more in the future!

Find me on medium

DEV Community: jsmanifest

Teaching AI Agents to Batch React State Updates with ESLint

1. The Problem: When AI Agents Generate useState Waterfalls

2. Understanding React Render Batching (And Its Limits)

3. The Solution: useImmer for Batched Updates

4. Advanced useImmer Patterns with Lodash

5. Building the ESLint Rule: Catching the Pattern Automatically

6. Implementing the ESLint Rule: Detection Logic

7. Full ESLint Rule Implementation

8. Teaching Claude with Custom Rules

10. Real-World Before/After Comparison

11. When NOT to Use This Pattern

Conclusion

5 Real-Life Problems Solved with Async Generators in JavaScript

What Are Async Generators?

1. Paginated API Fetching

2. Processing Large Files Line by Line

3. Real-Time Event Streams

4. Rate-Limited API Calls

5. Database Cursor Iteration

The Composability Superpower

When NOT to Use Async Generators

Conclusion

[Boost]

How to Monitor Any URL for Dead Links (Including Tricky Soft 404s)

How to Monitor Any URL for Dead Links (Including Tricky Soft 404s)

The Problem: Not All Dead Links Return 404

The Solution: Universal Link Monitoring

Building the API Client

Importing Links

How Detection Works

Setting Up Discord Alerts

Setting Up Telegram Alerts

Querying Link Status

Investigating Link History

Automated Daily Audit

Webhook Signature Verification

Real-World Example: Docusaurus Documentation Monitor

Step 1: Extract Links from Markdown Files

Step 2: Setup Monitoring with Groups

Running the Monitor

Summary

Combining the Command Pattern with State Pattern in JavaScript

Who uses this approach?

Conclusion

The Bridge Design Pattern in JavaScript

Where and when should the Bridge Pattern be used?

Implementation

Conclusion

The Power of Template Design Pattern in JavaScript

How does the Template Pattern work?

When is the Template Pattern needed?

How does the Template Pattern look like in code?

Another Example

Conclusion

The Power of Strategy Design Pattern in JavaScript

What kind of objects are involved?

Strengths

Implementation

Handling different data types

Conclusion

The Power of Memento Design Pattern in JavaScript

Implementing the Memento Design Pattern

Conclusion

State Design Pattern in JavaScript

What Problems Does The State Pattern Solve?

Implementation

The bigger picture

Conclusion

The Power of Proxy Pattern in JavaScript

Difference between Decorator vs Proxy

Validator/Helper

Clipboard Polyfill

Cacher (Enhancing performance)

The Proxy class

Proxy to Singleton

Cookie Stealer

Conclusion

11 JavaScript Examples to Source Code That Reveal Design Patterns In Use

Builder Design Pattern

The `Proxy` class