DEV Community: Zane

SEO as Code, Not SEO as Spreadsheets: A Publish-Grade Governance Workflow

Zane — Wed, 08 Apr 2026 08:21:22 +0000

Most teams do not fail at SEO because they do not care.
They fail because the process is disconnected:

standards are in docs, but not executable,
audits happen after release,
remediation is ad hoc and hard to track.

SAR (SEO-Audit-Remediation) is built to close that gap with a rulemap-driven, CI-friendly workflow.

What SAR Actually Includes

SAR is a repository-first governance stack with 5 connected layers:

standards/: human-readable policy and boundaries.
rulemaps/: machine-readable rule contracts.
core/: execution engine (discover / generate / audit).
skills/seo-audit/SKILL.md: agent workflow contract (with staged guardrails).
skills/seo-audit/scripts/*.cjs: bundled runtime artifacts.

The key is that standards, execution, and remediation guidance live in one versioned system.

Why Rulemap-Driven Runtime Matters

Rules are not hardcoded in application flow.

They are executed from rulemap config fields such as:

category
severity
blocking
runtime.scope
runtime.evaluator
runtime.params

Runtime scopes are explicit:

page
cross-page
host
gate

This keeps architecture stable while rules evolve.

Why `skills` Is a Core Differentiator

Many tools can report issues. Fewer can orchestrate fix workflows safely.

skills/seo-audit/SKILL.md defines a practical agent runbook:

staged execution (discover -> generate -> audit),
mandatory human checkpoint after route discovery,
explicit command contract,
re-audit loop after fixes.

In other words: it is not “AI auto-fix magic.” It is controlled automation with review gates.

End-to-End Flow (CLI)

Route-based one-shot audit:

pnpm seo:audit --routes core/examples/routes.sample.json --origin https://your-site.com

Step-by-step flow:

pnpm seo:discover --project-root /path/to/project --origin https://your-site.com
pnpm seo:generate --routes .outputs/<project>/routes.json --origin https://your-site.com
pnpm seo:audit --urls .outputs/<project>/urls.txt

Outputs You Can Feed Into Engineering

Each run produces concrete artifacts:

audit-report.json for machine processing and CI records,
action-plan.md for prioritized remediation execution,
optional AI remediation suggestions (--ai-remediation) for top issues.

AI output is recommendation-oriented, not blind code mutation.

CI Gate Strategy

Typical release gate:

P0 violations = 0
passRate >= 99.5%

Verification command:

pnpm seo:verify

Packaging and Runtime Consistency

SAR ships bundled CJS artifacts:

skills/seo-audit/scripts/discover.cjs
skills/seo-audit/scripts/generate.cjs
skills/seo-audit/scripts/audit.cjs

This enables predictable execution in CI/CD without relying on runtime node_modules.

Who Should Use It

SAR is a strong fit for teams that need:

cross-repo SEO governance,
auditable release criteria,
and deterministic CLI + agent workflows.

Repo: https://github.com/zandko/seo-foundation

Resolving lint-staged + pidtree Failures During Git Pre-Commit Hooks

Zane — Thu, 13 Nov 2025 08:37:39 +0000

Overview

Projects that rely on Husky combined with lint-staged may occasionally encounter pre-commit failures, particularly when running ESLint, Prettier, and Stylelint on staged files. One commonly observed issue is an unexpected crash originating from the pidtree dependency, which results in aborted commits and reverted changes.

This document provides a comprehensive and professional guideline for diagnosing, mitigating, and permanently resolving issues involving:

eslint --fix failures
lint-staged rollback interruptions
pidtree: No matching pid found errors
blocked Husky pre-commit hooks

The procedures below ensure that code changes remain safe and that teams maintain stable, predictable pre-commit behavior.

1. Symptoms

During a standard commit operation:

git commit -m "feat: add dashboard module"

The following symptoms may appear:

eslint --fix [FAILED]
Reverting to original state because of errors...
Error: No matching pid found
    at pidtree...
husky - pre-commit hook exited with code 1 (error)

Common signs include:

ESLint unable to auto-fix staged files
lint-staged leaving the working directory in a partially reverted state
pidtree throwing exceptions while cleaning child processes
the commit operation being aborted

2. Root Causes

2.1 ESLint Rule Violations

lint-staged stops immediately when ESLint encounters errors that cannot be automatically fixed. This is the most frequent cause of commit failures.

2.2 pidtree Failures Under Node 18+

pidtree@0.5.0 has known instability under newer Node versions (including Node 18 and 20). The error:

No matching pid found

occurs because lint-staged attempts to terminate a process that has already exited, leading to an unhandled exception.

2.3 Interrupted Rollback

lint-staged temporarily stashes local changes to run tasks in a clean state. If an error interrupts the restore phase, it may appear as if code was lost, although the data typically remains recoverable via git status, git diff, or git stash.

3. Immediate Workaround (Safe Commit Bypass)

If you have already validated your changes and need to commit urgently, you can bypass Husky for this commit only:

git add .
HUSKY=0 git commit -m "feat: add dashboard module"

This is safe and does not disable hooks globally or affect other contributors.

4. Permanent and Recommended Fixes

4.1 Ensure ESLint Passes Locally

Run ESLint directly to identify real rule violations:

npx eslint "apps/**/*.ts" "apps/**/*.vue" --fix

Or via your project scripts:

pnpm lint

Once the workspace is lint-clean, commit attempts are significantly more stable.

4.2 Upgrade lint-staged (Highly Recommended)

Updating lint-staged ensures newer, stable versions of the pidtree dependency are used. This is the most effective long-term fix.

Upgrade:

pnpm up lint-staged@latest -D

Verify:

npx lint-staged --debug

If the debug run completes successfully, the issue is resolved.

4.3 Optimize lint-staged Configuration

Large or overly broad file-globs increase lint-staged load, making pidtree failures more likely. A refined configuration improves reliability.

package.json

"lint-staged": {
  "*.{js,ts,vue}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.scss": [
    "stylelint --fix"
  ]
}

Avoid matching thousands of files when only a few are staged.

4.4 Optional: Disable pidtree Behavior (Temporary Mitigation)

For teams unable to upgrade dependencies immediately:

LINT_STAGED_PIDTREE=0 git commit -m "feat: add dashboard module"

This prevents lint-staged from killing process trees and avoids pidtree from triggering errors.

(Not recommended as a long-term solution.)

5. Recovering “Lost” Code

Even when lint-staged rollback fails, changes are normally not lost. Use these commands to inspect them:

Check workspace:

git status
git diff

Check staged diff:

git diff --staged

Check if lint-staged created a stash:

git stash list
git stash show -p stash@{0}

Restore if needed:

git stash apply stash@{0}

This resolves almost all cases where files appear missing.

6. Recommended Team Workflow

Before committing:

pnpm lint
pnpm prettier
pnpm stylelint

After verifying a clean workspace:

git add .
git commit -m "feat: ..."

This approach reduces friction, prevents pre-commit failures, and ensures a consistent codebase.

7. Summary

Issue	Cause	Solution
ESLint auto-fix failed	Code rule violations	Run ESLint manually and fix errors
`pidtree: No matching pid found`	Node 18+ + outdated pidtree	Upgrade lint-staged
lint-staged rollback error	Interrupted restore	Restore via stash or diff
Temporary need to commit	Pre-commit blocking	Use `HUSKY=0 git commit`

Upgrading lint-staged and keeping ESLint clean are the most effective and permanent solutions.

From Chaos to Comfy Super-Charging ComfyUI Workflows with a Type-Safe Node.js SDK 🚀

Zane — Fri, 30 May 2025 06:34:54 +0000

“I just wanted to trigger a text-to-image workflow from JavaScript—why does it feel like I’m herding cats?”
—Every front-end engineer who has ever hand-rolled a ComfyUI HTTP request

If that line feels painfully familiar, you’re going to love what comes next.

TL;DR

comfyui-sdk is a production-ready, TypeScript-native client for ComfyUI. It wraps the raw HTTP API in a fluent, strongly typed interface, adds connection-pooling, artifact pipelines, cloud storage hooks, and battle-tested retry logic—so you can focus on shipping instead of yelling at cURL.

In this article I’ll walk you through:

Why the JS/TS ecosystem needed its own first-class ComfyUI client.
What sets comfyui-sdk apart from the handful of existing wrappers.
How to integrate it—from a 5-line quick start to multi-instance load balancing.
Where the design pays off in real projects (benchmarks & edge cases).

By the end you’ll have everything you need to replace brittle fetch calls with a rock-solid, fully typed abstraction—no matter whether you ship a hobby bot on Vercel or a fleet of GPUs on Kubernetes.

1. The Pain: JSON Soup, Polling Loops & State Leaks

ComfyUI is brilliant for visual workflow composition, but its official REST endpoints were never meant for ergonomic consumption from TypeScript:

Problem	Why It Hurts in JS/TS
Opaque JSON payloads	Misspelled node keys only fail at runtime—often 30 s into an image render.
No connection pooling	Browser & serverless apps attack a single GPU node with N parallel requests → 429s & slowdowns.
Manual polling	You write the same `setTimeout` chain on every project, plus exponential backoff “by feel”.
Artifact sprawl	Generated images/text must be re-uploaded to S3/GCS after you parse the binary blob yourself.
Session cleanup	Leaked prompts clog the server, but the REST API has no concept of sessions.

Libraries existed—mostly thin axios wrappers—but none solved these cross-cutting concerns. They were bindings, not batteries.

2. The Antidote: What Makes `comfyui-sdk` Different?

Feature	Traditional Wrapper	comfyui-sdk
100 % TypeScript	Optional .d.ts	First-class generics & conditional types
Type-safe workflow mapping	❌	`defineConfig()` infers inputs & outputs
Connection pool	❌	Round-robin with per-host concurrency limits
Artifact pipeline	❌	Pluggable processors (e.g. S3, COS, custom)
Built-in logging	Minimal	5 levels, redacts API keys
Exponential backoff	Manual	Tunable `poll.backoffBase` + `backoffCap`
Session object	❌	Automatic cleanup on `close()`
Tree-shakable ESM	Varies	Yes (≃ 50 kB min+gz)
Framework-agnostic	–	Works in Node ≥ 18, Vite, Next.js, Bun

In short, it’s a toolkit, not a wrapper.

3. Five Lines to First Pixel

import { ComfyUIClient } from 'comfyui-sdk'

const client = new ComfyUIClient({ baseUrl: 'http://localhost:8188' })

const workflow = { /* …your node graph… */ }

const artifacts = await client.run(workflow)     // ← awaits completion & returns files
console.log(artifacts[0].manifest.width)         // fully typed!

That’s it—no explicit polling loop, no fetch, no JSON schema copy-paste. The SDK waits, retries with exponential backoff, and returns a typed Artifact[] once the prompt finishes.

4. Level-Up: Type-Safe Pipelines with `defineConfig`

Large graphs get messy fast. One wrong property path and your render fails after burning 200 GPU-seconds.
Enter defineConfig():

import { defineConfig } from 'comfyui-sdk'

const textToImage = defineConfig({
  inputs: [
    { from: 'prompt', to: '6.inputs.text', required: true },
    { from: 'seed',   to: '3.inputs.seed',  defaultValue: 42 }
  ] as const,
  outputs: [
    { from: '9', to: 'image' }
  ] as const
})

// TypeScript now **knows** what your workflow expects:
const result = await client.run(workflow, {
  node: textToImage,
  inputs: { prompt: 'A cyber-punk corgi' }  // seed optional
})

result.image             // ← correctly typed

No runtime key-path typos, ever. If you refactor the graph IDs, the compiler yells before you push.

5. Going Horizontal: Connection Pooling & Load Balancing

Need to saturate three A100 boxes? Spin up a pool:

import { ComfyUIPool } from 'comfyui-sdk'

const pool = new ComfyUIPool([
  { baseUrl: 'http://gpu-1:8188', maxConcurrency: 3 },
  { baseUrl: 'http://gpu-2:8188', maxConcurrency: 2 },
  { baseUrl: 'http://gpu-3:8188', maxConcurrency: 1 }
])

// Fire-and-forget convenience helper
const artifacts = await pool.execute(workflow)

Under the hood, leases are granted round-robin while respecting per-node limits. If one server drops, leases fall back automatically—no extra code.

6. Ship Your Artifacts—Automatically

Most teams ultimately upload outputs to a CDN. Doing it manually means juggling temp files and SDKs.
ArtifactPipeline fixes that:

import { ArtifactPipeline, CosUploader } from 'comfyui-sdk'

const pipeline = new ArtifactPipeline([
  new CosUploader({ /* Tencent COS creds */ })
])

const client = new ComfyUIClient({ baseUrl: 'http://localhost:8188' })

const artifacts = await client.run(workflow)
const processed  = await pipeline.run(artifacts)

console.log(processed[0].pipeline.cosUploader.url) // ready for frontend

Cloud storage is just one plugin. Write your own processor to:

Push metadata into Postgres
Run sharp for thumbnails
Invoke a moderation API

Each processor is an async class that receives an Artifact, mutates it, and stores side data under its own namespace—dirt simple, fully typed.

7. Real-World Benchmarks & Edge-Case Hardening

Scenario	Raw `fetch` (avg)	comfyui-sdk
10 parallel prompts on one server	8.1 s setup + time to render	1 network RTT (pooled)
Server returns 503 thrice	manual retry code	built-in `retry × max 5`
Browser drops tab mid-render	leaked prompt 🗑️	session `close()` on GC
2× GPU hosts, dynamic scale-down	custom health checks	pool detects 5 × fail → pauses host

Yes, we timed it. No, you don’t have to.

8. Why I Wrote It (and Why You Might Care)

As a full-stack Node engineer I wanted a client that felt native, not like a Python transplant. I needed:

Predictability in production—typed inputs, sane defaults.
Performance without yak-shaving—automatic backoff, pooled HTTP agents.
Extensibility—artifact hooks that don’t make me fork the library.

The result saved my team ~600 LOC across two micro-services and cut 90 % of ComfyUI-related on-call pages. That’s the SDK I’m open-sourcing today.

9. Installation & Compatibility

npm i comfyui-sdk   # or yarn/pnpm

Node ≥ 18 (works on 18/20, Bun, Deno w/ npm-compat)
No peer deps—Axios is bundled, but tree-shakable.
Runs fine in serverless (Vercel, Netlify) and Electron.

10. What’s Next on the Roadmap?

Area	Status	ETA
WebSocket live progress	draft PR	Q3 2025
OpenAPI schema generator	design	Q4 2025
First-class Bun adapter	community	–
Deno native HTTP	backlog	–

Open an issue, star the repo, or send a PR—help shape the tooling you want to use.

11. Take It for a Spin 🏁

Every minute you spend writing glue code is a minute not spent crafting prompts or features. Replace the boilerplate with a SDK that:

Understands your workflows at compile time
Scales from one laptop to a GPU farm
Ships artifacts straight to your bucket

import { ComfyUIClient } from 'comfyui-sdk'

new ComfyUIClient({ baseUrl: 'http://localhost:8188' })
  .run(myWorkflow)
  .then(console.log)

That’s two lines fewer than this conclusion. 😄

👉 Docs

GitHub: https://github.com/zandko/comfyui-sdk
NPM: npm i comfyui-sdk
API Reference: generated from source—no surprises

If this article saved you time, drop a ⭐ on GitHub or share your builds—I’d love to see what you create.

Happy rendering!

🚀 Easily Connect LLMs and MCP Servers with mcp-use (TypeScript)

Zane — Sun, 20 Apr 2025 13:07:05 +0000

Integrating Large Language Models (LLMs) with external services and tools efficiently is a common challenge developers face. Enter mcp-use, an open-source TypeScript library designed to simplify this integration, allowing you to quickly and safely connect any LangChain.js-compatible LLM with MCP servers, building powerful, flexible AI agents.

🌟 Why Choose `mcp-use`?

mcp-use provides a unified and simple interface to help you rapidly develop intelligent agents capable of calling various tools, freeing you from complex integration tasks and enabling you to focus on your core logic.

✨ Key Features:

🚦 Extreme Simplicity: Create functional intelligent agents in just a few lines of code.
🔧 LLM Flexibility: Compatible with any LangChain.js-supported LLM that supports tool calls.
🌐 HTTP/SSE Support: Easily connect to MCP servers.
🔄 Dynamic Server Selection: Agents dynamically choose the most suitable server in real-time.
🧩 Multi-Server Support: Effortlessly use multiple MCP servers simultaneously.
🔒 Fine-Grained Tool Permissions: Restrict sensitive or potentially dangerous tool calls.
🛠️ Fully Customizable: Create custom agents based on LangChain.js or implement new adapters.

⚡ Quick Start

📦 Install Dependencies

npm install mcp-use langchain @langchain/openai dotenv

Create a .env file:

OPENAI_API_KEY=your_api_key

🛠️ Example Code

import { ChatOpenAI } from '@langchain/openai';
import { MCPAgent, MCPClient } from 'mcp-use';
import 'dotenv/config';

async function main() {
  const config = {
    mcpServers: {
      playwright: { command: 'npx', args: ['@playwright/mcp@latest'] }
    }
  };

  const client = MCPClient.fromDict(config);
  const llm = new ChatOpenAI({ modelName: 'gpt-4o' });

  const agent = new MCPAgent({ llm, client, maxSteps: 20 });
  const result = await agent.run('Find the best restaurant in Tokyo using Google Search');

  console.log('🔍 Result:', result);
}

main().catch(console.error);

🗂️ Using Configuration Files

Manage MCP server configurations in a JSON file:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Load the configuration file:

import { MCPClient } from 'mcp-use';
const client = MCPClient.fromConfigFile('./mcp-config.json');

🌍 Advanced Multi-Server Usage

const config = {
  mcpServers: {
    airbnb: { command: 'npx', args: ['@openbnb/mcp-server-airbnb'] },
    playwright: { command: 'npx', args: ['@playwright/mcp@latest'] }
  }
};

const client = MCPClient.fromDict(config);
const agent = new MCPAgent({ llm, client, useServerManager: true });
await agent.run('Search Airbnb in Barcelona, then Google restaurants nearby');

🔐 Fine-Grained Permission Control

const agent = new MCPAgent({
  llm,
  client,
  disallowedTools: ['file_system', 'network']
});

📖 Contribute

mcp-use is fully open-source, and contributions via issues or pull requests are welcome!

If you find mcp-use helpful, consider giving the project a GitHub star. Your support motivates continuous improvement!

Singleton Pattern: The Lonely Chapter of Design Patterns

Zane — Tue, 11 Mar 2025 05:58:34 +0000

The Singleton pattern is like the control tower of an application, ensuring that all operations are conducted under a unified command, avoiding chaos and resource waste. It is the lone ranger in the family of creational patterns, focusing on building a unique and reliable instance, bringing order and efficiency to the complex software world.

Core Value and Definition of Singleton Pattern

The core of the Singleton pattern is to ensure that a class has only one instance and provides a global access point to this instance for the entire application. It's like the only post office in the city center, where all letters are sent and received, ensuring simple and efficient mail processing. Its existence not only saves resources but also ensures consistency in data and behavior.

Main Features of Singleton Pattern

Unique Instance: Ensures that a class has only one instance in the application, similar to the only moon on Earth, avoiding conflicts between instances.
Global Access Point: Provides a global access point, allowing access to this unique instance from anywhere in the application, like the moon clearly visible in the night sky.

Analogy of Singleton Pattern in Daily Life

Imagine a unique landmark in your city center, like the Eiffel Tower or the Statue of Liberty, which is unique and a shared memory. The Singleton pattern is similar; it is recognizable in every corner of the software because it is unique and shared. Just like every city has a central post office serving all residents, the Singleton pattern serves the entire application, ensuring system efficiency and order.

Structure and Composition of Singleton Pattern

In this chapter, we will explore the mystery of the Singleton pattern. Let's start with its construction, like the first step in solving an ancient puzzle.

Basic Structure of Singleton Pattern

The Singleton pattern typically involves the following components:

Private Constructor: Ensures that the class cannot be instantiated from outside;
A Private Static Variable (usually a private static property in TypeScript) to hold the unique instance of the class;
A Public Static Method (usually named getInstance) to provide a global access point.

UML Class Diagram and Interpretation of Singleton Pattern

The UML class diagram of the Singleton pattern is like a book with only one page opened. On this page, it clearly records how to guard a treasure — that unique class instance.

In this diagram, you will see:

A Class whose constructor is privatized, like a spell sealed with secret words in a book.
A Private Static Variable, like the treasure location silently guarded in the book, ensuring only one treasure exists.
A Public Static Method, like a spell to reveal the treasure. If the treasure is undiscovered, it will cast magic to summon it; if the treasure is already in the open, it will guide you directly to it.

Implementation of Singleton Pattern

Let's move from theory to practice. The following TypeScript code demonstrates how to implement a Singleton pattern:

function createSingleton<T extends new (...args: any[]) => any>(constructor: T): (...args: ConstructorParameters<T>) => InstanceType<T> {
  // Variable to store the instance
  let instance: InstanceType<T>;

  // Return a new function
  return function (...args: ConstructorParameters<T>): InstanceType<T> {
    // If the instance does not exist, create a new one
    if (!instance) {
      instance = new constructor(...args);
    }
    // Return the instance
    return instance;
  };
}

The createSingleton function takes a constructor as a parameter;
It returns a new function. This new function checks if an instance already exists:
- If it exists, it returns the existing instance;
- If it does not exist, it creates a new instance and then returns it.

In this way, no matter how many times we try to create an instance, we always get the same instance, as promised by the Singleton pattern.

Practical Exercise of Singleton Pattern — Global State Manager

In our software world, state is like a ship sailing at sea, needing to navigate safely under orderly and clear guidance. But if every component tries to navigate independently, it's like every captain trying to control the lighthouse themselves — chaos ensues! At this point, we need a global state manager to act as the lighthouse for the entire application, guiding the safe flow of state.

Background Introduction of the Case

In complex front-end applications, component state management is like sailing at sea, where each component may have its own direction, and their states may need to be shared and synchronized. If each component tries to navigate independently, it quickly becomes uncontrollable. This is why a global state manager becomes an indispensable lighthouse in software navigation. It provides a central location for managing and synchronizing the state of the entire application, like a harbor lighthouse guiding the ships.

Application of Singleton Pattern in State Management

Here, the Singleton pattern is like the light in the lighthouse, unique and crucial. It ensures that our global state manager is unique, like the central lighthouse in the software sea. No matter where you are in the software, you manage the state through this unique lighthouse, ensuring that all state changes are orderly and predictable.

Code Demonstration

Next, we will demonstrate through code how to use the Singleton pattern to create and use a global state manager.

First, we define a Store class responsible for managing state, executing changes, and handling actions:

class Store<S extends object = State, M extends Mutations<S> = Mutations<S>, A extends Actions<S> = Actions<S>> {
  private state: S;
  private mutations: M;
  private actions: A;

  // In the constructor, initialize state, mutations, and actions.
  constructor(options: StoreOptions<S, M, A>) {
    this.state = reactive(options.state) as S;
    this.mutations = options.mutations;
    this.actions = options.actions;
  }

  // getState method returns the current state.
  getState(): S {
    return this.state;
  }

  // commit method is used to call a mutation. It takes a mutation type and a payload.
  commit(type: string, payload: any): void {
    const mutation = this.mutations[type];
    if (!mutation) {
      throw new Error(`Mutation "${type}" does not exist`);
    }
    mutation(this.state, payload);
  }

  // dispatch method is used to call an action. It takes an action type and a payload.
  dispatch(type: string, payload: any): void {
    const action = this.actions[type];
    if (!action) {
      throw new Error(`Action "${type}" does not exist`);
    }
    action({ state: this.state, commit: this.commit.bind(this) }, payload);
  }
}

Then, we use the createSingleton function to ensure that our Store instance is unique:

// Create a singleton Store instance
const store = createSingleton(Store<State>)({
  // Definition of state
  state: {
    count: 0
  },
  // Definition of mutations
  mutations: {
    increment(state, payload) {
      state.count += payload;
    }
  },
  // Definition of actions
  actions: {
    incrementAsync({ commit }, payload) {
      commit('increment', payload);
    }
  },
});

Finally, in our Vue component, we can use this global state manager as follows:

<script setup lang="ts">
import { computed } from 'vue';
import { store } from '@/stores'

// Define a computed property that returns the count state from the store
const count = computed(() => store.getState().count);

// Use store methods to change the state
const increment = () => {
  store.commit('increment', 1);
};

const decrement = () => {
  store.dispatch('incrementAsync', -1);
};

</script>

<template>
 <div class="flex items-center justify-center h-screen bg-gray-100">
    <div class="p-6 bg-white shadow-md rounded-md">
      <h2 class="text-2xl font-bold mb-4 text-gray-700">Counter</h2>
      <div class="flex items-center space-x-4">
        <button @click="decrement" class="px-4 py-2 bg-red-500 text-white rounded">-</button>
        <span class="text-xl font-bold text-gray-700">{{ count }}</span>
        <button @click="increment" class="px-4 py-2 bg-green-500 text-white rounded">+</button>
      </div>
    </div>
  </div>
</template>

Through these codes, we demonstrated how to use the Singleton pattern to create an efficient and reliable global state manager. This state manager is like the central lighthouse of our software sea, ensuring that the flow of state is orderly and safe, guiding every state ship to sail safely.

Case Study of Singleton Pattern in Practice

We have just designed a lighthouse (Singleton pattern), now let's see how it illuminates ships in actual navigation. We are not analyzing ordinary code, but the code that plays a key role in excellent frameworks. This time, our focus is on Vuex, a famous Vue.js state management library. Vuex uses the Singleton pattern to manage the application's state, ensuring that the state throughout the application is unified and predictable.

Application Analysis of Singleton Pattern in Vuex Library

In Vuex, the Singleton pattern is not just a pattern; it is the heart of state management. There is a central repository (Store), which is the only source of state for the entire application. Every component communicates through this central repository, regardless of their position in the application. Imagine this as the central control tower of a large airport, where all planes (components) follow its command.

Source Code Analysis

In Vuex, the Store class is the core of global state management. The constructor of Store is responsible for initializing the global state, registering mutations, actions, and getters, and connecting the state of the entire application.

Below is the key part of the constructor:

function createStore (options) {
  return new Store(options)
}

class Store {
  constructor (options = {}) {  
    this._committing = false
    this._actions = Object.create(null)
    this._actionSubscribers = []
    this._mutations = Object.create(null)
    this._wrappedGetters = Object.create(null)
    this._modules = new ModuleCollection(options)
    this._modulesNamespaceMap = Object.create(null)
    this._subscribers = []
    this._makeLocalGettersCache = Object.create(null)

    // Bind commit and dispatch methods 
    const { dispatch, commit } = this
    this.dispatch = function boundDispatch (type, payload) {
      return dispatch.call(store, type, payload)
    }
    this.commit = function boundCommit (type, payload, options) {
      return commit.call(store, type, payload, options)
    }

    const state = this._modules.root.state

    // Initialize root module, recursively register all submodules, and collect all module getters
    installModule(this, state, [], this._modules.root)

    // Initialize store state, responsible for reactivity (also registers _wrappedGetters as computed properties)
    resetStoreState(this, state)

    // Apply plugins
    plugins.forEach(plugin => plugin(this))
  }

  install (app, injectKey) {
    // ... Code to install Vuex ...
  }

  // Other methods
  // ...
}

In this code, we see the Store class of Vuex. This Store class is the central repository of the application. When you call the createStore method, Vuex ensures that a Store instance is created, which is the only source of state for the entire application.

this._actions, this._mutations, etc., are used to store the logic for state changes.
installModule is responsible for registering all modules, ensuring modular state management.
resetStoreState is responsible for initializing the state, ensuring state reactivity.
plugins.forEach(plugin => plugin(this)) allows developers to extend Vuex functionality through plugins.

Let's delve a little deeper and look at the commit and dispatch methods in the Store class. These two methods are the core of Vuex state management. commit is used for synchronous operations, while dispatch is used for asynchronous operations. But regardless of the operation type, they are coordinated through this unique Store instance.

Practical Application Scenarios of Singleton Pattern

The Singleton pattern has a wide range of applications in software development. By ensuring that a class has only one instance, it simplifies the management of global resources. Here are some typical applications in software development:

Configuration Manager: Ensures that there is only one configuration manager throughout the application, making it easy for various components to access and use configuration information.
Logger: Manages logs through a global logger, simplifying log maintenance and improving performance.
Thread Pool: Controls the number of threads, avoiding frequent creation and destruction of threads, improving system resource utilization and performance.
Cache Management: A global cache instance manages data caching, improving data access speed and reducing database pressure.
Hardware Interface Access: For accessing hardware resources like printers and serial ports, using a singleton ensures that there is only one access instance globally, avoiding conflicts.

How to Identify Scenarios Suitable for Singleton Pattern

To identify scenarios suitable for the Singleton pattern, the key is to find situations that require a globally unique instance. Here are some criteria:

The class controls a resource or service, and there should only be one "access point" throughout the application.
You are writing code to "ensure only one instance is created," which is often a sign of using the Singleton pattern.
Managing global state, such as state management in front-end frameworks.

Disadvantages of Singleton Pattern and Coping Strategies

Although the Singleton pattern is powerful, it also has limitations, such as global state management issues and difficulties in unit testing.

Coping Strategy — Dependency Injection

Control Singleton Creation: Strictly control the creation and access of singletons through private constructors and public static methods.
Use Dependency Injection: In unit testing, replace singleton instances with dependency injection to improve test convenience.
Limit Modifications to Global State: Modify the state through clearly defined methods, avoiding direct modifications to the global state.

In unit testing, using dependency injection to replace singleton instances is an effective strategy to solve testing problems. It not only improves the flexibility and testability of the code but also retains the core advantages of the Singleton pattern. See the following dependency injection example:

class DIContainer {
  private static instances: Record<string, any> = {};

  // Register method for registering singleton instances
  public static register<T>(key: string, creator: () => T): void {
    if (!DIContainer.instances[key]) {
      DIContainer.instances[key] = creator();
    }
  }

  // Resolve method for obtaining singleton instances
  public static resolve<T>(key: string): T {
    if (!DIContainer.instances[key]) {
      throw new Error(`No instance found for key: ${key}`);
    }
    return DIContainer.instances[key];
  }
}

// Example: Create Store instance and register
function createStoreInstance() {
  return new Store<State>({
    state: { count: 0 },
    // ... Other state and methods ...
  });
}

// Create Store instance and register to DIContainer
DIContainer.register<Store<State>>('Store', createStoreInstance);

// In Vue component, get Store instance through DIContainer
const store = DIContainer.resolve<Store<State>>('Store');

In this example, DIContainer provides a flexible way to manage singletons. We can register and resolve different instances in development and testing environments as needed. This not only retains the advantages of the Singleton pattern but also enhances the flexibility and testability of the code.

Essence Review and Value Re-recognition of Singleton Pattern

The Singleton pattern ensures that a class has only one instance and provides a global access point in a unique way. It not only ensures the consistency of global state but also greatly reduces resource consumption. Through our global state manager and Vuex case, we have seen the powerful application of the Singleton pattern in actual projects. But at the same time, we have also recognized its challenges and how to overcome these challenges through strategies such as dependency injection.

Building a High-Quality Stock Report Generator with Node.js, Express, and OpenAI API

Zane — Sun, 03 Nov 2024 09:02:48 +0000

In this article, we will delve into creating a professional-grade stock report generator using Node.js, Express, and the OpenAI API. The application will fetch stock data, perform sentiment and industry analysis, and generate a comprehensive investment report.

Project Overview
Setting Up the Environment
Creating the Express Server
Fetching and Processing Data
Integrating with OpenAI API
Generating the Final Report
Testing the Application
Conclusion

Project Overview

Our goal is to build an API endpoint that generates a detailed investment report for a given stock ticker. The report will include:

Company Overview
Financial Performance
Management Discussion and Analysis (MDA)
Sentiment Analysis
Industry Analysis
Risks and Opportunities
Investment Recommendation

We will fetch stock data from external APIs and use the OpenAI API for advanced analysis, ensuring that the prompt messages are accurately preserved.

Setting Up the Environment

Prerequisites

Node.js installed on your machine
OpenAI API Key (If you don't have one, sign up at OpenAI)

Initializing the Project

Create a new directory and initialize a Node.js project:

mkdir stock-report-generator
cd stock-report-generator
npm init -y

Install the necessary dependencies:

npm install express axios

Set up the project structure:

mkdir routes utils data
touch app.js routes/report.js utils/helpers.js

Creating the Express Server

Setting Up `app.js`

// app.js
const express = require('express');
const reportRouter = require('./routes/report');

const app = express();

app.use(express.json());
app.use('/api', reportRouter);

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Express Initialization: Import Express and initialize the application.
Middleware: Use express.json() to parse JSON request bodies.
Routing: Mount the report router on the /api path.
Server Listening: Start the server on the specified port.

Fetching and Processing Data

Creating Helper Functions

In utils/helpers.js, we'll define utility functions for data fetching and processing.

// utils/helpers.js
const axios = require('axios');
const fs = require('fs');
const path = require('path');

const BASE_URL = 'https://your-data-api.com'; // Replace with your actual data API

/**
 * Get the start and end dates for the last year.
 * @returns {object} - An object containing `start` and `end` dates.
 */
function getLastYearDates() {
  const now = new Date();
  const end = now.toISOString().split('T')[0];
  now.setFullYear(now.getFullYear() - 1);
  const start = now.toISOString().split('T')[0];
  return { start, end };
}

/**
 * Convert an object to a string, excluding specified keys.
 * @param {object} obj - The object to convert.
 * @param {string[]} excludeKeys - Keys to exclude.
 * @returns {string} - The resulting string.
 */
function objectToString(obj, excludeKeys = []) {
  return Object.entries(obj)
    .filter(([key]) => !excludeKeys.includes(key))
    .map(([key, value]) => `${key}: ${value}`)
    .join('\n');
}

/**
 * Fetch data from a specified endpoint with given parameters.
 * @param {string} endpoint - API endpoint.
 * @param {object} params - Query parameters.
 * @param {any} defaultValue - Default value if the request fails.
 * @returns {Promise<any>} - The fetched data or default value.
 */
async function fetchData(endpoint, params = {}, defaultValue = null) {
  try {
    const response = await axios.get(`${BASE_URL}${endpoint}`, { params });
    return response.data || defaultValue;
  } catch (error) {
    console.error(`Error fetching data from ${endpoint}:`, error.message);
    return defaultValue;
  }
}

/**
 * Read data from a local JSON file.
 * @param {string} fileName - Name of the JSON file.
 * @returns {any} - The parsed data.
 */
function readLocalJson(fileName) {
  const filePath = path.join(__dirname, '../data', fileName);
  const data = fs.readFileSync(filePath, 'utf-8');
  return JSON.parse(data);
}

module.exports = {
  fetchData,
  objectToString,
  getLastYearDates,
  readLocalJson,
};

getLastYearDates: Calculates the start and end dates for the previous year.
objectToString: Converts an object to a readable string, excluding specified keys.
fetchData: Handles GET requests to external APIs, returning data or a default value.
readLocalJson: Reads data from local JSON files.

Implementing Stock Data Fetching

In routes/report.js, define functions to fetch stock data.

// routes/report.js
const express = require('express');
const {
  fetchData,
  objectToString,
  getLastYearDates,
  readLocalJson,
} = require('../utils/helpers');

const router = express.Router();

/**
 * Fetches stock data including historical prices, financials, MDA, and main business info.
 * @param {string} ticker - Stock ticker symbol.
 * @returns {Promise<object>} - An object containing all fetched data.
 */
async function fetchStockData(ticker) {
  try {
    const dates = getLastYearDates();
    const [historicalData, financialData, mdaData, businessData] = await Promise.all([
      fetchData('/stock_zh_a_hist', {
        symbol: ticker,
        period: 'weekly',
        start_date: dates.start,
        end_date: dates.end,
      }, []),

      fetchData('/stock_financial_benefit_ths', {
        code: ticker,
        indicator: '按年度',
      }, [{}]),

      fetchData('/stock_mda', { code: ticker }, []),

      fetchData('/stock_main_business', { code: ticker }, []),
    ]);

    const hist = historicalData[historicalData.length - 1];
    const currentPrice = (hist ? hist['开盘'] : 'N/A') + ' CNY';
    const historical = historicalData
      .map((item) => objectToString(item, ['股票代码']))
      .join('\n----------\n');

    const zsfzJson = readLocalJson('zcfz.json');
    const balanceSheet = objectToString(zsfzJson.find((item) => item['股票代码'] === ticker));

    const financial = objectToString(financialData[0]);

    const mda = mdaData.map(item => `${item['报告期']}\n${item['内容']}`).join('\n-----------\n');

    const mainBusiness = businessData.map(item =>
      `主营业务: ${item['主营业务']}\n产品名称: ${item['产品名称']}\n产品类型: ${item['产品类型']}\n经营范围: ${item['经营范围']}`
    ).join('\n-----------\n');

    return { currentPrice, historical, balanceSheet, mda, mainBusiness, financial };
  } catch (error) {
    console.error('Error fetching stock data:', error.message);
    throw error;
  }
}

fetchStockData: Concurrently fetches multiple data points and processes the results.
Data Processing: Formats and transforms data for subsequent use.
Error Handling: Logs errors and rethrows them for higher-level handling.

Integrating with OpenAI API

OpenAI API Interaction Function

const axios = require('axios');

const OPENAI_API_KEY = 'your-openai-api-key'; // Replace with your OpenAI API key

/**
 * Interacts with the OpenAI API to get completion results.
 * @param {array} messages - Array of messages, including system prompts and user messages.
 * @returns {Promise<string>} - The AI's response.
 */
async function analyzeWithOpenAI(messages) {
  try {
    const headers = {
      'Authorization': `Bearer ${OPENAI_API_KEY}`,
      'Content-Type': 'application/json',
    };
    const requestData = {
      model: 'gpt-4',
      temperature: 0.3,
      messages: messages,
    };

    const response = await axios.post(
      'https://api.openai.com/v1/chat/completions',
      requestData,
      { headers }
    );
    return response.data.choices[0].message.content.trim();
  } catch (error) {
    console.error('Error fetching analysis from OpenAI:', error.message);
    throw error;
  }
}

analyzeWithOpenAI: Handles communication with the OpenAI API.
API Configuration: Sets parameters such as model and temperature.
Error Handling: Logs and throws errors for upstream handling.

Performing Sentiment Analysis

/**
 * Performs sentiment analysis on news articles using the OpenAI API.
 * @param {string} ticker - Stock ticker symbol.
 * @returns {Promise<string>} - Sentiment analysis summary.
 */
async function performSentimentAnalysis(ticker) {
  const systemPrompt = `You are a sentiment analysis assistant. Analyze the sentiment of the given news articles for ${ticker} and provide a summary of the overall sentiment and any notable changes over time. Be measured and discerning. You are a skeptical investor.`;

  const tickerNewsResponse = await fetchData('/stock_news_specific', { code: ticker }, []);

  const newsText = tickerNewsResponse
    .map(item => `${item['文章来源']} Date: ${item['发布时间']}\n${item['新闻内容']}`)
    .join('\n----------\n');

  const messages = [
    { role: 'system', content: systemPrompt },
    {
      role: 'user',
      content: `News articles for ${ticker}:\n${newsText || 'N/A'}\n----\nProvide a summary of the overall sentiment and any notable changes over time.`,
    },
  ];

  return await analyzeWithOpenAI(messages);
}

performSentimentAnalysis: Constructs prompt messages and calls the OpenAI API for analysis.
Prompt Design: Ensures that the prompt messages are clear and include necessary context.

Analyzing the Industry

/**
 * Analyzes industry information using the OpenAI API.
 * @param {string} industry - Industry name.
 * @returns {Promise<string>} - Industry analysis summary.
 */
async function analyzeIndustry(industry) {
  const industryNewsResponse = await fetchData('/stock_news_specific', { code: industry }, []);
  const industryNewsArticles = industryNewsResponse
    .map(item => `${item['文章来源']} Date: ${item['发布时间']}\n${item['新闻内容']}`)
    .join('\n----------\n');

  const systemPrompt = `You are an industry analysis assistant. Provide an analysis of the ${industry} industry, including trends, growth prospects, regulatory changes, and competitive landscape.

Consider the following recent news articles relevant to the ${industry} industry:
${industryNewsArticles || 'N/A'}

Be measured and discerning. Truly think about the positives and negatives of the industry. Be sure of your analysis. You are a skeptical investor.`;

  const messages = [
    { role: 'system', content: systemPrompt },
    {
      role: 'user',
      content: `Provide an analysis of the ${industry} industry, taking into account the recent news articles provided.`,
    },
  ];

  return await analyzeWithOpenAI(messages);
}

analyzeIndustry: Similar to sentiment analysis but focuses on broader industry context.
Prompt Preservation: Maintains the integrity of the original prompt messages.

Generating the Final Report

Compiling All Data

/**
 * Generates the final investment report.
 * @param {string} ticker - Stock ticker symbol.
 * @param {object} data - Collected data and analyses.
 * @returns {Promise<string>} - The final report.
 */
async function provideFinalAnalysis(ticker, data) {
  const {
    sentimentAnalysis,
    industryAnalysis,
    balanceSheet,
    mda,
    mainBusiness,
    financial,
    currentPrice,
    historical,
  } = data;

  const systemPrompt = `You are a financial analyst tasked with providing a comprehensive investment recommendation for the stock ${ticker}. Your analysis should utilize the available data and aim for a length of approximately 1500 to 3000 words. Focus on the following key aspects:

1. **Company Overview**: Provide a brief overview of the company, including its business model, core products/services, and market position. Refer to the provided main business data.

2. **Financial Performance**:
   - Analyze key financial metrics based on the available data, including the current price (${currentPrice}), historical data, financial data, and balance sheet.
   - Highlight any significant financial trends and changes.

3. **Management Discussion and Analysis (MDA)**:
   - Summarize the management's insights and future outlook based on the provided MDA data.

4. **Sentiment Analysis**:
   - Summarize public sentiment based on recent news articles.
   - Include insights into any significant events or announcements that could influence market perception.

5. **Industry Analysis**:
   - Outline current industry trends and major players based on the available industry data.
   - Identify any regulatory or technological factors affecting the industry.

6. **Macroeconomic Factors**:
   - Analyze relevant macroeconomic indicators that may impact the company's performance.

7. **Risks and Opportunities**:
   - Identify key risks facing the company, including market, operational, and regulatory risks.
   - Highlight potential growth opportunities and strategic initiatives.

8. **Investment Recommendation**:
   - Based on your analysis, provide a clear recommendation (buy, hold, or sell) for the stock.
   - Support your recommendation with a well-reasoned rationale, considering both positives and negatives.

Please write in a professional tone, using precise language and relevant financial terminology. Respond in Chinese.`;

  const userPrompt = `Ticker: ${ticker}\n
1. **Sentiment Analysis**:\n${sentimentAnalysis}\n
2. **Industry Analysis**:\n${industryAnalysis}\n
3. **Financial Data**:\nCurrent Price: ${currentPrice}\nHistorical Data: ${historical}\nBalance Sheet: ${balanceSheet}\nFinancial Data: ${financial}\n
4. **Management Discussion and Analysis (MDA)**:\n${mda}\n
5. **Main Business**:\n${mainBusiness}\n\n
Based on the provided data and analyses, please provide a comprehensive investment analysis and recommendation for ${ticker}. Ensure the report length is controlled between 1500 and 3000 words, ensuring clarity and conciseness in your arguments.`;

  const messages = [
    { role: 'system', content: systemPrompt },
    {
      role: 'user',
      content: userPrompt,
    },
  ];

  return await analyzeWithOpenAI(messages);
}

provideFinalAnalysis: Carefully crafts prompt messages, incorporating all collected data.
Prompt Integrity: Ensures that the original prompt messages are not altered or corrupted.

Testing the Application

Defining the Route Handler

Add the route handler in routes/report.js:

router.post('/generate-report', async (req, res) => {
  const { ticker } = req.body;

  if (!ticker) {
    return res.status(400).json({ error: 'Ticker symbol is required.' });
  }

  try {
    const dataJson = readLocalJson('stock.json');
    const stockInfo = dataJson.find((item) => item.symbol === ticker);

    if (!stockInfo) {
      return res.status(404).json({ error: 'Stock information not found.' });
    }

    const { industry } = stockInfo;

    // Fetch stock data
    const stockData = await fetchStockData(ticker);

    // Perform analyses
    const [sentimentAnalysis, industryAnalysis] = await Promise.all([
      performSentimentAnalysis(ticker),
      analyzeIndustry(industry || 'the industry'),
    ]);

    // Generate final report
    const finalAnalysis = await provideFinalAnalysis(ticker, {
      sentimentAnalysis,
      industryAnalysis,
      ...stockData,
    });

    res.json({ report: finalAnalysis });
  } catch (error) {
    console.error('Error generating report:', error.message);
    res.status(500).json({ error: 'Failed to generate report.' });
  }
});

module.exports = router;

Input Validation: Checks if the ticker symbol is provided.
Data Gathering: Concurrently fetches stock data and performs analyses.
Error Handling: Logs errors and sends a 500 response in case of failure.

Starting the Server

Ensure your app.js and routes/report.js are correctly set up, then start the server:

node app.js

Sending a Test Request

Use curl or Postman to send a POST request:

curl -X POST http://localhost:3000/api/generate-report \
  -H 'Content-Type: application/json' \
  -d '{"ticker": "AAPL"}'

Response: The server should return a JSON object containing the generated report.

Conclusion

We have built a high-quality stock report generator with the following capabilities:

Fetching and processing stock data from external APIs.
Performing advanced analyses using the OpenAI API.
Generating a comprehensive investment report, while ensuring the integrity of the prompt messages.

Throughout the development process, we focused on writing professional, maintainable code and provided detailed explanations and annotations.

Best Practices Implemented

Modular Code Structure: Functions are modularized for reusability and clarity.
Asynchronous Operations: Used async/await and Promise.all for efficient asynchronous programming.
Error Handling: Comprehensive try-catch blocks and error messages.
API Abstraction: Separated API interaction logic for better maintainability.
Prompt Engineering: Carefully designed prompt messages for the OpenAI API to achieve the desired output.
Input Validation: Checked for required input parameters to prevent unnecessary errors.
Code Documentation: Added JSDoc comments for better understanding and maintenance.

Next Steps

Caching: Implement caching mechanisms to reduce redundant API calls.
Authentication: Secure the API endpoints with authentication and rate limiting.
Frontend Development: Build a user interface for interacting with the application.
Additional Analyses: Incorporate technical analysis or other financial models.

References

Disclaimer: This application is for educational purposes only. Ensure compliance with all API terms of service and handle sensitive data appropriately.

A Comprehensive and User-Friendly Project README.md Template

Zane — Tue, 13 Aug 2024 14:01:40 +0000

1. Project Overview

[Brief Introduction]

1.1 Project Background

This project aims to address the issue of [description of the need] by utilizing [technical solution] to design and develop a [product overview].

1.2 Project Objectives

The goal of this project is to achieve [description of project objectives] by providing the best [product/service/solution] to [target customer/user group] through [implementation methods].

1.3 Project Scope

The scope of this project includes [description of project scope] and aims to [purpose explanation].

2. User Requirements

2.1 Requirement Analysis

This project has analyzed the needs of [target customer/user group] and identified the following requirements:

[Description of Requirement 1]
[Description of Requirement 2]
[Description of Requirement 3]
...

2.2 User Experience

This project aims to provide a user experience that [description of user experience goals], focusing on [target customer/user group], supported by [technical means].

2.3 Interface Design

The interface design of this project adopts a [description of interface style] style, combined with [technical means] to achieve a simple and easy-to-use interface.

3. Technical Architecture

3.1 Technology Selection

This project adopts [technical solution] as the core technology, combined with [other technical solutions] to achieve [product overview].

System Architecture: The system architecture diagram of this project is as follows:

[System Architecture Diagram]

The project includes the following main modules:

[Module 1 Name]: [Module 1 Description]
[Module 2 Name]: [Module 2 Description]
[Module 3 Name]: [Module 3 Description]
...

The data flow diagram of this project is as follows:

[Data Flow Diagram]

3.2 Frontend Framework

This project uses [name of frontend framework] as the frontend tech stack, combined with [other technical solutions] to achieve [product overview].

3.3 Backend API

The backend API documentation for this project is online and can be accessed at [API documentation link] for detailed information.

[API 1 Name]: [API 1 Documentation Link]
[API 2 Name]: [API 2 Documentation Link]
[API 3 Name]: [API 3 Documentation Link]
...

4. Development Environment

To develop this project, please ensure that your development environment meets the following requirements:

[Requirement 1]
[Requirement 2]
[Requirement 3]
...

4.1 Development Tools

The following development tools are recommended:

[Tool 1 Name]: [Tool 1 Description]
[Tool 2 Name]: [Tool 2 Description]
[Tool 3 Name]: [Tool 3 Description]
...

Please follow the steps below to configure your local environment:

[Description of Step 1]
[Description of Step 2]
[Description of Step 3]
...

The project's code is hosted on [code hosting platform], and you can access the code at [code repository link].

4.2 Development Guidelines

To ensure code quality, please follow these development guidelines:

[Description of Guideline 1]
[Description of Guideline 2]
[Description of Guideline 3]
...

To ensure that the code conforms to the development guidelines and code standards, this project uses [code inspection tool], so please ensure the code passes inspection before submission.

If you have any questions while adhering to the development guidelines and code standards, please feel free to contact the technical team for assistance.

Here are the steps to configure the development environment:

Install [necessary software]
Configure [related environment variables]
Clone the code repository to your local machine
Run [initialization command] to install project dependencies
Run [start command] to start the development environment

This project depends on the following software and libraries:

[Dependency 1]
[Dependency 2]
[Dependency 3]
...

4.3 Code Standards

The coding standards for this project provide a unified development style to ensure the readability and maintainability of the code.

[Standard 1 Name]: [Standard 1 Description]
[Standard 2 Name]: [Standard 2 Description]
[Standard 3 Name]: [Standard 3 Description]
...

Please follow these steps to submit your code:

[Description of Step 1]
[Description of Step 2]
[Description of Step 3]
...

Please refer to the [review process link] for the code review process.

5. Module Details

[Module Name]: [Module Description]

For example:

User Management Module: Responsible for functions related to user management.

5.1 Page Layout

User Registration Page: Uses Bootstrap layout, including forms for entering username, password, and email.
User Login Page: Uses Bootstrap layout, including forms for entering username and password.

5.2 Component Design

Form Component: Uses Ant Design's Form component to implement form validation.

5.3 Code Implementation

user.js: Responsible for handling the logic for user registration and login.
api.js: Encapsulates the requests to the backend API.

6. Testing and Debugging

6.1 Test Environment

Operating System: [Environment requirements, such as Windows 10, macOS 11, etc.]
Browser: [Environment requirements, such as Google Chrome, Mozilla Firefox, etc.]
Other Software: [Environment requirements, such as Node.js, npm, etc.]

6.2 Testing Methods

Use [testing tools, such as Jest, Mocha, etc.] for unit testing.

6.3 Test Plan

[Test Case 1]: [Test Case Description]
[Test Case 2]: [Test Case Description]
...

For example:

User Registration: Test whether the user registration API is functioning correctly.
User Login: Test whether the user login API is functioning correctly.

6.4 Debugging Tools

Use [Chrome DevTools, VSCode Debugger, etc.] for debugging.

6.5 Debugging Methods

[Description of debugging methods, such as breakpoint debugging, logging, etc.]

For example:

Breakpoint debugging in DevTools.

7. Deployment and Release

This project uses Docker for deployment. The frontend code is run inside a container on the server via Docker.

7.1 Deployment Process

Install Docker environment on the server
Run the command docker build -t my-frontend-project . in the project root directory to build the image
Run the command docker run -p 80:80 my-frontend-project to start the container, and the frontend project can then be accessed via the server IP

7.2 Release Plan

Run the build command locally to generate static resource files
Use an FTP client to upload the static resource files to the server
Update the project code on the server and restart the container to complete the release

7.3 Operations and Maintenance

8. Appendix

8.1 Sample Code

Below is a sample React component code for implementing a search feature:

import React, { useState } from 'react';

const Search = () => {
  const [searchTerm, setSearchTerm] = useState('');
  const [results, setResults] = useState([]);

  const handleChange = (e) => {
    setSearchTerm(e.target.value);
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    fetch(`https://api.example.com/search?q=${searchTerm}`)
      .then((res) => res.json())
      .then((data) => setResults(data.results));
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Search"
        value={searchTerm}
        onChange={handleChange}
      />
      <button type="submit">Go</button>
      {results.length > 0 && (
        <ul>
          {results.map((result) => (
            <li key={result.id}>{result.title}</li>
          ))}
        </ul>
      )}
    </form>
  );
};

export default Search;

8.2 Resource Links

Below are some resource links used in this project:

8.3 Development Documentation

Below are some documents needed during project development:

Building an Efficient Jenkins + Docker + Vue Project Automated Deployment Environment

Zane — Mon, 12 Aug 2024 00:48:35 +0000

Highlights

Custom Shell scripts make controlling the integrated deployment environment more convenient and flexible.
If the server is replaced, the workload for redeployment is relatively small.

Preparations

First, you need to have a server. I used an Alibaba Cloud ECS instance in the East China region. There are plenty of tutorials online for purchasing a server. After the purchase, you will have a public IP and a password to log into the server via SSH.

If you are not familiar with Docker, I recommend checking out its documentation first. Docker containers are like shipping containers on a cargo ship. Each container holds its own goods and doesn’t affect the others. For example, a Redis service and a MongoDB service can each be placed in their own container. These containers rely on an execution environment, which Docker calls an Image. Each container manages its own lifecycle.

Jenkins is an open-source software project developed in Java, mainly used for continuous integration. Essentially, it allows you to pre-write scripts, and once these scripts are successfully debugged, they can be automatically executed for future deployments without modification.

Installing Docker

Reference Documentation

Uninstalling Old Versions

$ sudo apt-get remove docker docker-engine docker.io

Installing via APT

Since APT sources use HTTPS to ensure that software is not tampered with during download, we need to add the HTTPS transport package and CA certificates first.

$ sudo apt-get update

$ sudo apt-get install 
    apt-transport-https \
    ca-certificates \
    curl \
    software-properties-common

Given the network issues in China, it is strongly recommended to use domestic sources. For official sources, see the comments.

To verify the legitimacy of the downloaded packages, add the GPG key for the software source.

$ curl -fsSL https://mirrors.ustc.edu.cn/docker-ce/linux/ubuntu/gpg | sudo apt-key add -

# Official Source
# $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Next, add the Docker software source to source.list:

$ sudo add-apt-repository \
    "deb [arch=amd64] https://mirrors.ustc.edu.cn/docker-ce/linux/ubuntu \
    $(lsb_release -cs) \
    stable"

# Official Source
# $ sudo add-apt-repository \
    # "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
    # $(lsb_release -cs) \
    # stable"

The above command adds the stable version of the Docker CE APT source. If you need the test or nightly build versions, change stable to test or nightly.

Installing Docker CE

Update the APT package cache and install Docker CE:

$ sudo apt-get update

$ sudo apt-get install docker-ce

Installing Automatically via Script

For testing or development environments, Docker provides a convenient installation script to simplify the process. On Ubuntu systems, you can use this script:

$ curl -fsSL get.docker.com -o get-docker.sh

$ sudo sh get-docker.sh --mirror Aliyun

Running this command will automatically prepare everything and install the Edge version of Docker CE on your system.

Starting Docker CE

$ sudo systemctl enable docker

$ sudo systemctl start docker

Creating the Docker User Group

By default, Docker commands communicate with the Docker engine using a Unix socket. Only the root user and users in the Docker group can access the Docker engine's Unix socket. For security reasons, it is generally not recommended to use the root user directly on a Linux system. A better approach is to add users who need to use Docker to the Docker user group.

Create the Docker group:

$ sudo groupadd docker

Add the current user to the Docker group:

$ sudo usermod -aG docker $USER

Log out and log back in, then test Docker.

Testing Docker Installation

$ docker run hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
d1725b59e92d: Pull complete
Digest: sha256:0add3ace90ecb4adbf7777e9aacf18357296e799f81cabc9fde470971e499788
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image, which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

If you see the above output, the installation was successful.

Image Acceleration

If you find that pulling Docker images is very slow, you can configure Docker's domestic image acceleration.

Alibaba Cloud Mirror Acceleration

Installing Docker Compose

Reference Documentation

Run this command to download the latest stable version of Docker Compose:

$ sudo curl -L "https://github.com/docker/compose/releases/download/1.25.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Apply executable permissions to the binary:

$ sudo chmod +x /usr/local/bin/docker-compose

Check the version:

$ docker-compose --version

Installing Jenkins

To install Jenkins, I chose to use Docker Compose. Docker Compose automates Docker operations, allowing you to complete all complex Docker operations with a single command.

First, create a directory structure on the server (this is just a demo):

/home/jenkins
     - docker-compose.yml
     - jenkins-home

Next, write a `docker-compose.yml` file to install Jenkins:

version: '3'    # Specifies the format of the docker-compose.yml file
services:       # Collection of multiple containers
  docker_jenkins: 
    user: root  # Using root to avoid some permission issues
    restart: always # Restart policy
    image: jenkins/jenkins:lts  # Specifies the image to use, in this case, LTS (Long-Term Support)
    container_name: jenkins # Container name
    ports:      # Exposed ports
      - '8080:8080'
      - '50000:50000'
    volumes:    # Volume mount paths
      - /home/jenkins/jenkins_home/:/var/jenkins_home  # Mounts the directory we created to Jenkins's home directory inside the container
      - /var/run/docker.sock:/var/run/docker.sock
      - /usr/bin/docker:/usr/bin/docker     # Allows the use of Docker commands inside the container
      - /usr/local/bin/docker-compose:/usr/local/bin/docker-compose # Allows the use of Docker Compose commands inside the container

Navigate to the Jenkins directory and execute:

$ docker-compose up -d

This command will automatically pull the image and configure everything.

If everything goes well, you can now access your server at http://your-server-address:port and see the following interface:

Open the Jenkins directory you created and navigate to jenkins-home:

/home/jenkins/jenkins-home

Enter the secrets directory:

$ cat initialAdminPassword

Copy the content from this file and paste it into the administrator password field.

Next, install two plugins:

NodeJS Plugin
Publish Over SSH

Scroll down to the bottom.

Start Creating Project Deployment

Official Reference

1. First, create an `nginx.conf` file in the root directory of your project:

user  nginx;
worker_processes  1;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
events {
  worker_connections  1024;
}
http {
  include       /etc/nginx/mime.types;
  default_type  application/octet-stream;
  log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
  '$status $body_bytes_sent "$http_referer" '
  '"$http_user_agent" "$http_x_forwarded_for"';
  access_log  /var/log/nginx/access.log  main;
  sendfile        on;
  keepalive_timeout  65;
  server {
    listen       80;
    server_name  www.lovelp.xin;  # Domain name
    location / {
      root   /app;  # Directory location
      index  index.html;
      try_files $uri $uri/ /index.html;
    }
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
      root   /usr/share/nginx/html;
    }
  }
}

2. Create a `Dockerfile` in the root directory of your project:

FROM node
WORKDIR /app

COPY package*.json ./
RUN npm install -g cnpm --registry=https://registry.npm.taobao.org
RUN cnpm install
COPY ./ /app
RUN npm run build:prod

FROM nginx
RUN mkdir /app
COPY --from=0 /app/dist /app
COPY nginx.conf /etc/nginx/nginx.conf

3. Create a `setup.sh` script in the root directory of your project to help execute commands:

#!/usr/bin/env bash
image_version=`date +%Y%m%d%H%M`;
# Stop the shop_admin container
docker stop shop_admin || true;
# Remove the shop_admin container
docker rm shop_admin || true;
# Remove the shop/admin image
docker rmi --force $(docker images | grep shop/admin | awk '{print $3}')
# Build the shop/admin:$image_version image
docker build . -t shop/admin:$image_version;
# List the images
docker images;
# Create a container named shop_admin from the shop/admin image
docker run -p 9527:80 -d --name shop_admin shop/admin:$image_version;
# View logs
docker logs shop_admin;
# Remove images generated during the build process
docker rmi $(docker images -f "dangling=true" -q)
# Automatically clean up space
docker system prune -a -f

4. Finally, create a project on Jenkins:

Finally, you can happily click on Build Now.

Building a Node.js Wrapper for Reddit API: A Step-by-Step Guide

Zane — Fri, 09 Aug 2024 00:49:40 +0000

Building a Node.js Wrapper for Reddit API: A Step-by-Step Guide

In modern development, API wrapping is a crucial skill. Wrapping an API allows developers to create more readable, maintainable, and scalable code, ultimately improving development efficiency. Today, we will explore how to build a simple yet effective wrapper in Node.js for interacting with Reddit's API.

The Starting Point: Why Wrap the Reddit API?

When developing applications that interact with Reddit, directly calling the API is possible but not ideal. If you want your code to be more modular and easier to maintain, wrapping the API is essential. By wrapping the API, you can:

Abstract Complexity: Hide the intricate details of the API behind a simple, easy-to-use interface.
Reusability: Wrapped code can be reused across multiple projects.
Better Error Handling: Manage and handle API errors uniformly in the wrapper.

Getting Hands-On: Building the Reddit Class

We'll start with a basic Reddit class, including essential functions needed to interact with the Reddit API, such as obtaining an access token and performing search queries.

1. Configuration and Initialization

In the code, we begin by defining the constructor for the Reddit class. This constructor is mainly responsible for initializing critical parameters required by the Reddit API, such as clientId, clientSecret, userAgent, and the base baseURL. These parameters are retrieved from environment variables to ensure sensitive information is not hardcoded.



export class Reddit {

  private baseURL: string;

  private clientId: string;

  private clientSecret: string;

  private userAgent: string;

  private token?: string;

constructor() {

    this.clientId = getEnvironmentVariable('REDDIT_CLIENT_ID')!;

    this.clientSecret = getEnvironmentVariable('REDDIT_SECRET')!;

    this.userAgent = getEnvironmentVariable('REDDIT_USER_AGENT')!;

    this.baseURL = getEnvironmentVariable('REDDIT_BASE_URL')!;

  }

}

Building the Request URL

Building the request URL is a critical part of wrapping an API. We create a buildUrl method that takes the API endpoint and optional options parameters. This method converts the options object into a URL query string, forming the complete request URL.



private buildUrl(endpoint: string, options?: RedditSearchOptions): string {

  const preparedParams: [string, string][] = Object.entries({ ...options })

    .filter(

      ([key, value]) =>

        value !== undefined && value !== null && key !== 'apiKey',

    )

    .map(([key, value]) => [key, </span><span class="p">${</span><span class="nx">value</span><span class="p">}</span><span class="s2">]);

const searchParams = new URLSearchParams(preparedParams);

  return </span><span class="p">${</span><span class="k">this</span><span class="p">.</span><span class="nx">baseURL</span><span class="p">}</span><span class="s2">/</span><span class="p">${</span><span class="nx">endpoint</span><span class="p">}</span><span class="s2">?</span><span class="p">${</span><span class="nx">searchParams</span><span class="p">}</span><span class="s2">;

}

Obtaining the Access Token

The Reddit API requires OAuth2 for authentication, so we need to obtain an access token first. The getAccessToken method sends a POST request to retrieve and store the access token. This token is cached to avoid repeated requests.



private async getAccessToken(): Promise<string> {

  if (this.token) return this.token;

const auth = Buffer.from(</span><span class="p">${</span><span class="k">this</span><span class="p">.</span><span class="nx">clientId</span><span class="p">}</span><span class="s2">:</span><span class="p">${</span><span class="k">this</span><span class="p">.</span><span class="nx">clientSecret</span><span class="p">}</span><span class="s2">).toString(

    'base64',

  );

const headers = new Headers();

  headers.append('Authorization', Basic </span><span class="p">${</span><span class="nx">auth</span><span class="p">}</span><span class="s2">);

  headers.append('Content-Type', 'application/x-www-form-urlencoded');

const response = await fetch(</span><span class="p">${</span><span class="k">this</span><span class="p">.</span><span class="nx">baseURL</span><span class="p">}</span><span class="s2">/api/v1/access_token, {

    method: 'POST',

    headers,

    body: 'grant_type=client_credentials',

  });

if (!response.ok) {

    throw new Error(Error fetching access token: </span><span class="p">${</span><span class="nx">response</span><span class="p">.</span><span class="nx">statusText</span><span class="p">}</span><span class="s2">);

  }

const data = (await response.json()) as {

    access_token: string;

  };

this.token = data.access_token;

  return this.token;

}

Invoking the Reddit API

The invoke method is a generic API calling function. It first obtains the access token, then builds the request URL, and finally makes the request and handles the response. If the API request fails, it throws an error, allowing you to handle errors uniformly when using this wrapper.



private async invoke<T = any>(

  endpoint: string,

  options?: RedditSearchOptions,

): Promise<T> {

  const token = await this.getAccessToken();

const headers = new Headers();

  headers.append('Authorization', Bearer </span><span class="p">${</span><span class="nx">token</span><span class="p">}</span><span class="s2">);

  headers.append('User-Agent', this.userAgent);

const response = await fetch(this.buildUrl(endpoint, options), {

    method: 'GET',

    headers,

  });

  if (!response.ok) {

    throw new Error(Error fetching data: </span><span class="p">${</span><span class="nx">response</span><span class="p">.</span><span class="nx">statusText</span><span class="p">}</span><span class="s2">);

  }

return (await response.json()) as T;

}

Performing Reddit Searches

Finally, we use the findMany method to perform search requests. This method allows users to search based on a query string and other optional parameters, returning the search results.



public async findMany(

  q: string,

  options: RedditSearchOptions = {},

): Promise<any> {

  return this.invoke('/search', { ...options, q });

}

Conclusion

Through this post, we learned how to wrap the Reddit API, making API calls more straightforward and maintainable. This wrapping method is not only applicable to Reddit but also to most applications that frequently interact with external APIs. The wrapped code improves reusability and provides significant convenience for future expansion and maintenance.

In actual projects, further optimizations could include adding more detailed error handling, supporting additional API features, or creating a caching layer to optimize performance. However, mastering the basics of wrapping is an essential skill for every developer. I hope that through this post, you can apply these techniques in your work to write more elegant code.

LangGraph.js Concept Guide

Zane — Tue, 30 Jul 2024 00:41:49 +0000

Welcome to LangGraph.js, a JavaScript library designed for building complex, scalable AI agents using a graph-based state machine. In this guide, we will explore the core concepts behind LangGraph.js and why it excels in creating reliable and fault-tolerant agent systems. We assume you have already learned the basics introduced in the Quick Start guide and want to dive deeper into the fundamental design and internal workings of LangGraph.js.

Background: Agents as Graphs and AI Workflows

While definitions of "AI agents" vary, we define an "agent" as any system that allows a language model to control looped workflows and take actions. Typical LLM agents use a "Reasoning and Acting" (ReAct) style design, applying an LLM to drive a basic loop comprising the following steps:

Reason and plan actions to take.
Take action using tools (regular software functions).
Observe the effects of the tools and appropriately replan or react.

While LLM agents perform well in this regard, naive agent loops can't provide the reliability users expect at scale. They have a beautiful randomness. Well-designed systems can harness this randomness and apply it reasonably in well-designed composite systems, making them fault-tolerant to errors in LLM outputs because errors will happen.

We believe agents are exciting and novel, but AI design patterns should be applied using good engineering practices from Software 2.0. Some similarities include:

AI applications must balance autonomous operations with user control.
Agent applications are akin to distributed systems in error tolerance and correction.
Multi-agent systems resemble multiplayer network applications in parallelism and conflict resolution.
Everyone likes an undo button and version control.

LangGraph.js's primary StateGraph abstraction is designed to support these and other needs, providing a lower-level API than other agent frameworks (like LangChain's AgentExecutor), giving you full control over how and where "AI" is applied.

It extends Google's Pregel graph processing framework, offering fault tolerance and recovery for long-running or error-prone workloads. During development, you can focus on local operations or specific task agents, and the system will assemble these operations into a more robust and scalable application.

Its parallelism and state reduction features allow you to control how to handle conflicting information returned by multiple agents.

Lastly, its persistent versioned checkpoint system enables you to roll back agent states, explore alternative paths, and have full control over what is happening.

The following sections will delve into how these concepts work and why.

Core Design

At its core, LangGraph.js models agent workflows as a state machine. You can define agent behavior using three key components:

State: A shared data structure representing a snapshot of the application's current state. It can be any TypeScript type but is usually an interface or class.
Nodes: TypeScript functions encoding the agent logic. They take the current State as input, perform some computation or side effect, and return the updated State.
Edges: Control flow rules determining which Node to execute next based on the current State. They can be conditional branches or fixed transitions.

By combining Nodes and Edges, you can create complex looped workflows that evolve the State over time. The true power lies in how LangGraph.js manages these States.

In short: Nodes do work; Edges determine what to do next.

LangGraph.js's underlying graph algorithm defines a general program using message passing. When a Node completes, it sends messages (States) along one or more Edges to other Nodes. These Nodes run their functions and pass the result messages to the next set of Nodes, and so on. Inspired by Pregel, the program executes in conceptually parallel discrete "supersteps." When the graph runs, all Nodes start in an inactive state. When an incoming edge (or "channel") receives a new message (State), the Node becomes active, runs its function, and responds with updates. At the end of each superstep, if no more incoming edge messages exist, Nodes vote to halt, marking themselves as inactive. When all Nodes are inactive and no messages are in transit, the graph terminates.

We'll illustrate a complete StateGraph execution later, but first, let's delve into these concepts.

Nodes

In a StateGraph, Nodes are usually TypeScript functions (synchronous or asynchronous), with the first positional argument being the State, and an optional second positional argument being RunnableConfig, containing optional configurable parameters (e.g., thread_id).

Similar to NetworkX, you can add these Nodes to the graph using the addNode method:

Node Example

import { END, START, StateGraph, StateGraphArgs } from "@langchain/langgraph";
import { RunnableConfig } from "@langchain/core/runnables";

interface IState {
  input: string;
  results?: string;
}

// This defines the agent state
const graphState: StateGraphArgs<IState>["channels"] = {
  input: {
    value: (x?: string, y?: string) => y ?? x ?? "",
    default: () => "",
  },
  results: {
    value: (x?: string, y?: string) => y ?? x ?? "",
    default: () => "",
  },
};

function myNode(state: IState, config?: RunnableConfig) {
  console.log("In node:", config?.configurable?.user_id);
  return { results: `Hello, ${state.input}!` };
}

// The second parameter is optional
function myOtherNode(state: IState) {
  return state;
}

const builder = new StateGraph({ channels: graphState })
  .addNode("my_node", myNode)
  .addNode("other_node", myOtherNode)
  .addEdge(START, "my_node")
  .addEdge("my_node", "other_node")
  .addEdge("other_node", END);

const graph = builder.compile();

const result1 = await graph.invoke(
  { input: "Will" },
  { configurable: { user_id: "abcd-123" } }
);

// In node: abcd-123
console.log(result1);
// { input: 'Will', results: 'Hello, Will!' }

Under the hood, functions are transformed into RunnableToLambda, adding batching and async support to your functions, along with native tracing and debugging.

Edges

Edges define how the logic routes and when the graph decides to stop. Like Nodes, they take the current graph State and return a value.

By default, this value is the name of the next Node or Nodes to send the State to. All these Nodes will run in parallel as part of the next superstep.

If you want to reuse Edges, you can optionally provide a dictionary mapping the Edge's output to the name of the next Node.

If you always want to go from Node A to Node B, you can use the addEdge method directly.

If you want to conditionally route to one or more Edges (or conditionally terminate), you can use the addConditionalEdges method.

If a Node has multiple outgoing Edges, all those target Nodes will run in parallel in the next superstep.

State Management

LangGraph.js introduces two key concepts for state management: state interfaces and reducers.

State interfaces define the type of the object passed to each Node in the graph.

Reducers define how Node outputs are applied to the current State. For example, you can use a reducer to merge new conversation responses into the conversation history or average outputs from multiple agent Nodes. By annotating your state fields with reducer functions, you can precisely control how data flows through your application.

We'll illustrate how reducers work with an example. Compare the following two states. Can you guess the output in each case?

State Management

import { END, START, StateGraph } from "@langchain/langgraph";

interface StateA {
  myField: number;
}

const builderA = new StateGraph<StateA>({
  channels: {
    myField: {
      // "Override" is the default behavior:
      value: (_x: number, y: number) => y,
      default: () => 0,
    },
  },
})
  .addNode("my_node", (_state) => ({ myField: 1 }))
  .addEdge(START, "my_node")
  .addEdge("my_node", END);

const graphA = builderA.compile();

console.log(await graphA.invoke({ myField: 5 }));
// { myField: 1 }

and StateB:

interface StateB {
  myField: number;
}

// add **reducer** defines **how** to apply state updates
// to specific fields.
function add(existing: number, updated?: number) {
  return existing + (updated ?? 0);
}

const builderB = new StateGraph<StateB>({
  channels: {
    myField: {
      value: add,
      default: () => 0,
    },
  },
})
  .addNode("my_node", (_state) => ({ myField: 1 }))
  .addEdge(START, "my_node")
  .addEdge("my_node", END);

const graphB = builderB.compile();

console.log(await graphB.invoke({ myField: 5 }));

// { myField: 6 }

If you guessed "1" and "6," you were right!

In the first case (StateA), the result is "1" because your default reducer is a simple override. In the second case (StateB), the result is "6" because we created an add function as the reducer. This function takes the existing state (for that field) and the state update (if provided) and returns the updated value for that state.

Reducers typically tell the graph how to handle updates to that field.

In building a simple chatbot like ChatGPT, the state can be as simple as a list of chat messages. This is the state used by MessageGraph, a lightweight wrapper around

StateGraph, and is a bit more complex than the following:

Root Reducer

import { StateGraph, END, START } from "@langchain/langgraph";

const builderE = new StateGraph({
  channels: {
    __root__: {
      reducer: (x: string[], y?: string[]) => x.concat(y ?? []),
      default: () => [],
    },
  },
})
  .addNode("my_node", (state) => {
    return [`Adding a message to ${state}`];
  })
  .addEdge(START, "my_node")
  .addEdge("my_node", END);

const graphE = builderE.compile();

console.log(await graphE.invoke(["Hi"]));

// ["Hi", 'Added a message to Hi']

Using shared state in a graph has some design trade-offs. For example, you might think this feels like using dreadful global variables (though this can be mitigated with a namespace parameter). However, shared typed state provides many benefits related to building AI workflows, including:

Data flow is fully inspectable before and after each "superstep."
State is mutable, allowing users or other software to write to the same state between supersteps to control the agent's direction (using updateState).
Checkpoints are well-defined, making it easy to save and restore or even fully version-control the entire workflow execution in any storage backend.

We'll discuss checkpoints in more detail in the next section.

Persistence

Any "intelligent" system needs memory to operate. AI agents are no exception and require memory across one or more time frames:

They always need to remember the steps taken in this task (to avoid repeating when answering a given query).
They often need to remember the previous rounds of multi-turn conversations with a user (for coreference resolution and additional context).
Ideally, they "remember" previous interactions with the user and behavior in a given "environment" (e.g., application context) to behave more personalized and efficiently.

The latter form of memory covers a lot (personalization, optimization, continuous learning, etc.), which is beyond the scope of this article, though it can be easily integrated into any LangGraph.js workflow, and we are actively exploring the best ways to expose this natively.

The first two forms of memory are natively supported by the StateGraph API through checkpoints.

Checkpoints

Checkpoints represent the state of a thread in a (potentially) multi-turn interaction between a user (or users or other systems). Checkpoints created within a single run will have a set of next Nodes to execute when resuming from that state. Checkpoints created at the end of a given run are the same, except no next Nodes to transition (the graph is waiting for user input).

Checkpoints support chat memory and more, allowing you to mark and persist every state the system takes, whether within a single run or across multi-turn interactions. Let's explore why this is useful:

Single Run Memory

Within a given run, checkpoints are made at every step. This means you can ask your agent to create world peace. When it fails and hits an error, you can always restore its task from its saved checkpoint.

This also allows you to build human-in-the-loop workflows, common in customer support bots, programming assistants, and other applications. You can interrupt the graph's execution before or after executing a given Node and "escalate" control to a user or support staff. The staff might respond immediately, or they might respond a month later. Regardless, your workflow can resume at any time as if no time has passed.

Multi-Turn Memory

Checkpoints are saved under a thread_id to support multi-turn interactions between a user and the system. For developers, there is no difference when configuring the graph to add multi-turn memory support, as checkpoints work the same way throughout.

If you have some state you want to retain between turns and some state you want to consider "ephemeral," you can clear the relevant state in the graph's final Node.

Using checkpoints is as simple as calling compile({ checkpointer: myCheckpointer }), then invoking it with the thread_id in its configurable parameters. You can see more in the next section!

Configuration

For any given graph deployment, you might want some configurable values controlled at runtime. These values differ from graph inputs because they should not be considered state variables. They are more like "out-of-band" communication.

A common example is the thread_id for a conversation, user_id, which LLM to use, the number of documents to return in a retriever, etc. While these can be passed in state, it is better to separate them from the regular data flow.

Example

Let's review another example to see how our multi-turn memory works! Can you guess what the results and result2 of running this graph will be?

Configuration

import { END, MemorySaver, START, StateGraph } from "@langchain/langgraph";

interface State {
  total: number;
  turn?: string;
}

function addF(existing: number, updated?: number) {
  return existing + (updated ?? 0);
}

const builder = new StateGraph<State>({
  channels: {
    total: {
      value: addF,
      default: () => 0,
    },
  },
})
  .addNode("add_one", (_state) => ({ total: 1 }))
  .addEdge(START, "add_one")
  .addEdge("add_one", END);

const memory = new MemorySaver();

const graphG = builder.compile({ checkpointer: memory });

let threadId = "some-thread";

let config = { configurable: { thread_id: threadId } };

const result = await graphG.invoke({ total: 1, turn: "First Turn" }, config);

const result2 = await graphG.invoke({ turn: "Next Turn" }, config);

const result3 = await graphG.invoke({ total: 5 }, config);

const result4 = await graphG.invoke(
  { total: 5 },
  { configurable: { thread_id: "new-thread-id" } }
);

console.log(result);
// { total: 2, turn: 'First Turn' }
console.log(result2);
// { total: 3, turn: 'Next Turn' }
console.log(result3);
// { total: 9, turn: 'Next Turn' }
console.log(result4);
// { total: 6 }

For the first run, no checkpoint is found, so the graph runs on the original input. The total value increases from 1 to 2, and the turn is set to "First Turn."

For the second run, the user provides an update for "turn" but not the total! Since we load from state, the previous result increments by one (in our "add_one" Node), and "turn" is overwritten by the user.

For the third run, "turn" remains unchanged because it is loaded from the checkpoint but not overwritten by the user. The total is incremented by the value provided by the user because it updates the existing value using the add function.

For the fourth run, we use a new thread id, and no checkpoint is found, so the result is just the user's provided total plus one.

You might notice that this user-facing behavior is equivalent to running the following commands without a checkpointer.

Configuration

const graphB = builder.compile();
const resultB1 = await graphB.invoke({ total: 1, turn: "First Turn" });
const resultB2 = await graphB.invoke({ ...result, turn: "Next Turn" });
const resultB3 = await graphB.invoke({ ...result2, total: result2.total + 5 });
const resultB4 = await graphB.invoke({ total: 5 });

console.log(resultB1);
// { total: 2, turn: 'First Turn' }
console.log(resultB2);
// { total: 3, turn: 'Next Turn' }
console.log(resultB3);
// { total: 9, turn: 'Next Turn' }
console.log(resultB4);
// { total: 6 }

Run it yourself to confirm the equivalence. User inputs and checkpoint loads are treated like any other state update.

Now that we've covered the core concepts of LangGraph.js, it might be more helpful to see how all the pieces come together through an end-to-end example.

StateGraph Single Execution Data Flow

As engineers, we are never satisfied until we know what happens "under the hood." In the previous sections, we explained some core concepts of LangGraph.js. Now it's time to show how they come together.

Let's extend our toy example with a conditional edge and walk through two consecutive invocations.

Data Flow

import { START, END, StateGraph, MemorySaver } from "@langchain/langgraph";

interface State {
  total: number;
}

function addG(existing: number, updated?: number) {
  return existing + (updated ?? 0);
}

const builderH = new StateGraph<State>({
  channels: {
    total: {
      value: addG,
      default: () => 0,
    },
  },
})
  .addNode("add_one", (_state) => ({ total: 1 }))
  .addNode("double", (state) => ({ total: state.total }))
  .addEdge(START, "add_one");

function route(state: State) {
  if (state.total < 6) {
    return "double";
  }
  return END;
}

builderH.addConditionalEdges("add_one", route);
builderH.addEdge("double", "add_one");

const memoryH = new MemorySaver();
const graphH = builderH.compile({ checkpointer: memoryH });
const threadId = "some-thread";
const config = { configurable: { thread_id: threadId } };

for await (const step of await graphH.stream(
  { total: 1 },
  { ...config,

 streamMode: "values" }
)) {
  console.log(step);
}
// 0 checkpoint { total: 1 }
// 1 task null
// 1 task_result null
// 1 checkpoint { total: 2 }
// 2 task null
// 2 task_result null
// 2 checkpoint { total: 4 }
// 3 task null
// 3 task_result null
// 3 checkpoint { total: 5 }
// 4 task null
// 4 task_result null
// 4 checkpoint { total: 10 }
// 5 task null
// 5 task_result null
// 5 checkpoint { total: 11 }

To trace this run, check the LangSmith link. We will explain the execution step by step below:

First, the graph looks for checkpoints. None is found, so the state initializes with a total of 0.
Next, the graph applies user input as a state update. The reducer adds the input (1) to the existing value (0). At the end of this superstep, the total is (1).
After that, the "add_one" Node is invoked, returning 1.
Next, the reducer applies this update to the existing total (1). The state is now 2.
Then, the conditional edge "route" is called. Since the value is less than 6, we proceed to the 'double' Node.
The double Node takes the existing state (2) and returns it. The reducer is then called and adds it to the existing state. The state is now 4.
The graph then loops back to add_one (5), checks the conditional edge, and proceeds since it is <6. After doubling, the total is (10).
The fixed edge loops back to add_one (11), checks the conditional edge, and since it is greater than 6, the program terminates.

For the second run, we will use the same configuration:

Data Flow

const resultH2 = await graphH.invoke({ total: -2, turn: "First Turn" }, config);
console.log(resultH2);
// { total: 10 }

To trace this run, check the LangSmith link. We will explain the execution step by step below:

First, the graph looks for checkpoints. It loads into memory as the initial state. The total is (11) as previously.
Next, it applies user input updates. The add reducer updates the total from 11 to -9.
After that, the "add_one" Node is invoked, returning 1.
This update is applied using the reducer, raising the value to 10.
Next, the "route" conditional edge is triggered. Since the value is greater than 6, we terminate the program, ending at (11).

Conclusion

That's it! We have explored the core concepts of LangGraph.js and seen how to use it to create reliable, fault-tolerant agent systems. By modeling agents as state machines, LangGraph.js provides a powerful abstraction for composing scalable and controllable AI workflows.

Remember these key ideas when working with LangGraph.js:

Nodes do the work; Edges determine the control flow.
Reducers precisely define how state updates are applied at each step.
Checkpoints enable memory within single runs and across multi-turn interactions.
Interrupts allow you to pause, retrieve, and update the graph's state for human-in-the-loop workflows.
Configurable parameters allow runtime control, independent of the regular data flow.

With these principles, you can harness the full power of LangGraph.js to build advanced AI agent systems.

Discover the Magic of SearXNG Service and Empower Your Search Engine API

Zane — Mon, 22 Jul 2024 17:58:47 +0000

In the age of information overload, having a powerful and flexible search tool is like holding a magic key to explore the web. Today, we bring you such a magical key—the SearXNG Service. This TypeScript-based service seamlessly interacts with the SearXNG search engine API, allowing you to perform searches and retrieve results in various formats. Whether you're developing a cool web application or need robust backend search support, the SearXNG Service is your ideal solution.

Why Choose SearXNG Service?

SearXNG Service is more than just a tool; it's your search companion, making your development work more efficient and enjoyable.

Unlimited Customization: Adjust search parameters according to your needs. Choose from various categories, engines, and locales to get precise search results.
Ease of Use: From installation to usage, the entire process is straightforward and hassle-free, allowing you to get started quickly.
Multi-Format Support: Retrieve search results in JSON, CSV, and RSS formats, making your application versatile and adaptable to different scenarios.

Installation and Configuration

One-Click Installation

Install the SearXNG Service with a single command:

npm install searxng

Configuration Setup

Import and configure the SearXNG Service to start using it:

import { SearxngService, type SearxngServiceConfig } from 'searxng';

const config: SearxngServiceConfig = {
  baseURL: 'https://your-searxng-instance.com',
  defaultSearchParams: {
    format: 'json',
    lang: 'auto',
  },
  defaultRequestHeaders: {
    'Content-Type': 'application/json',
  },
};

const searxngService = new SearxngService(config);

Types and Parameters

Engines and Locales

Select your preferred search engines and locales to customize your search experience:

export type SearxngEngine =
  | 'google'
  | 'bing'
  | 'duckduckgo'
  // Add more engines
  ;

export type SearxngLocale =
  | 'en'
  | 'es'
  | 'fr'
  // Add more locales
  ;

Methods

Use the search method to start your exploration journey:

async search(
  input: string,
  params?: Partial<SearxngSearchParameters>,
): Promise<SearxngSearchResults>

Example: Basic Search

Perform a simple search to see the power of the magic key:

async function performSearch() {
  try {
    const results = await searxngService.search('example query');
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
}

performSearch();

Example: Search with Parameters

Perform a more refined search with additional parameters:

async function performSearchWithParams() {
  const searchParams = {
    categories: ['general', 'web'],
    engines: ['google', 'bing'],
    lang: 'en',
    pageno: 2,
    time_range: 'month',
    format: 'json',
  };

  try {
    const results = await searxngService.search('example query', searchParams);
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
}

performSearchWithParams();

Conclusion

SearXNG Service is more than just a tool; it's your search magic wand, making complex searches simple and fun. Whether you're a developer or a tech enthusiast, SearXNG Service can help you achieve more powerful search capabilities. Install the SearXNG Service today and start your magical search journey!

DEV Community: Zane

SEO as Code, Not SEO as Spreadsheets: A Publish-Grade Governance Workflow

What SAR Actually Includes

Why Rulemap-Driven Runtime Matters

Why skills Is a Core Differentiator

End-to-End Flow (CLI)

Outputs You Can Feed Into Engineering

CI Gate Strategy

Packaging and Runtime Consistency

Who Should Use It

Resolving lint-staged + pidtree Failures During Git Pre-Commit Hooks

Overview

1. Symptoms

2. Root Causes

2.1 ESLint Rule Violations

2.2 pidtree Failures Under Node 18+

2.3 Interrupted Rollback

3. Immediate Workaround (Safe Commit Bypass)

4. Permanent and Recommended Fixes

4.1 Ensure ESLint Passes Locally

4.2 Upgrade lint-staged (Highly Recommended)

4.3 Optimize lint-staged Configuration

4.4 Optional: Disable pidtree Behavior (Temporary Mitigation)

5. Recovering “Lost” Code

Check workspace:

Check staged diff:

Check if lint-staged created a stash:

6. Recommended Team Workflow

Before committing:

After verifying a clean workspace:

7. Summary

From Chaos to Comfy Super-Charging ComfyUI Workflows with a Type-Safe Node.js SDK 🚀

TL;DR

1. The Pain: JSON Soup, Polling Loops & State Leaks

2. The Antidote: What Makes comfyui-sdk Different?

3. Five Lines to First Pixel

4. Level-Up: Type-Safe Pipelines with defineConfig

5. Going Horizontal: Connection Pooling & Load Balancing

6. Ship Your Artifacts—Automatically

7. Real-World Benchmarks & Edge-Case Hardening

8. Why I Wrote It (and Why You Might Care)

9. Installation & Compatibility

10. What’s Next on the Roadmap?

11. Take It for a Spin 🏁

👉 Docs

🚀 Easily Connect LLMs and MCP Servers with mcp-use (TypeScript)

🌟 Why Choose mcp-use?

✨ Key Features:

⚡ Quick Start

📦 Install Dependencies

🛠️ Example Code

🗂️ Using Configuration Files

🌍 Advanced Multi-Server Usage

🔐 Fine-Grained Permission Control

📖 Contribute

Singleton Pattern: The Lonely Chapter of Design Patterns

Core Value and Definition of Singleton Pattern

Main Features of Singleton Pattern

Analogy of Singleton Pattern in Daily Life

Structure and Composition of Singleton Pattern

Basic Structure of Singleton Pattern

UML Class Diagram and Interpretation of Singleton Pattern

Implementation of Singleton Pattern

Practical Exercise of Singleton Pattern — Global State Manager

Background Introduction of the Case

Application of Singleton Pattern in State Management

Code Demonstration

Case Study of Singleton Pattern in Practice

Application Analysis of Singleton Pattern in Vuex Library

Source Code Analysis

Practical Application Scenarios of Singleton Pattern

How to Identify Scenarios Suitable for Singleton Pattern

Disadvantages of Singleton Pattern and Coping Strategies

Coping Strategy — Dependency Injection

Essence Review and Value Re-recognition of Singleton Pattern

Building a High-Quality Stock Report Generator with Node.js, Express, and OpenAI API

Table of Contents

Project Overview

Setting Up the Environment

Prerequisites

Why `skills` Is a Core Differentiator

2. The Antidote: What Makes `comfyui-sdk` Different?

4. Level-Up: Type-Safe Pipelines with `defineConfig`

🌟 Why Choose `mcp-use`?

Setting Up `app.js`