DEV Community: meijin

Building a Teacher Search AI Agent with Mastra and Structured Data Streaming

meijin — Wed, 11 Jun 2025 01:12:54 +0000

Recently, we released a "teacher search agent" feature at Manalink, an online tutoring platform. This AI agent helps users find the perfect teacher through natural language conversations.

Here's a quick demo of the feature:

Note: Screen shown is from development phase / Search results are examples

Key Features

The AI teacher search agent includes these distinctive capabilities:

Character-by-character streaming responses similar to ChatGPT, creating a familiar UX
Natural language input processing - users can describe their needs in plain language, and the AI understands subjects, grade levels, and other criteria
Unstructured data search - beyond typical filters like subjects and grades, users can search using criteria like "needs help with communication skills" or "prefers strict teaching style"
Rich structured UI components - instead of plain text responses, the system displays structured cards with teacher rankings, recommendations, and detailed information through JSON streaming
Real-time progress indicators - users see live updates as the AI searches through various data sources, reducing perceived wait time
Interactive conversations - users can continue refining their search based on initial results

Technical Architecture Overview

To achieve these features, we implemented several key technical decisions:

AI Agent approach instead of simple LLM API calls for flexible, context-aware responses
Mastra framework as our AI agent foundation, leveraging its streaming capabilities and existing tooling
Next.js and React Native integration with proper AWS infrastructure configuration for streaming
Embedding and RAG for similarity search to handle unstructured data without consuming excessive context
Careful tool, schema, and instruction design to ensure stable agent behavior
Custom useStructuredChat hook extending Vercel AI SDK's useChat for cross-platform structured data streaming
Business-focused accuracy metrics ensuring the agent meets real-world educational matching requirements

This article focuses primarily on implementing structured data streaming for AI agents while touching on UX considerations and the broader challenges of agent development.

Environment Information

This implementation uses:

June 2025 timeframe
Next.js 14.x
@mastra/core and related Mastra packages 0.10.x
Expo 52.x

The Challenge of Structured Data Streaming

Why Streaming Matters

Before diving into technical implementation, let's establish why streaming is essential and why it needs to be structured.

User Experience Benefits:
AI generation, despite optimizations, takes time. For tasks users perceive as "doable myself" or "available elsewhere," even 10 seconds feels excessive. Streaming display eliminates the "waiting" sensation by showing progressive results.

Changed User Expectations:
Major AI services (ChatGPT, Claude, Gemini) have made streaming standard. Like how LINE popularized chat UI as a communication standard, users now expect AI responses to stream. This creates a baseline expectation developers must meet.

Why Structure Matters

Rich UI and Interactions:
Structured data (JSON) enables direct mapping to React components. For example:

Plain text: Restaurant name, description, URL as text
Structured data: Restaurant name, rating, image URL, reservation link, availability button - enabling rich restaurant cards with actionable elements

Application Integration:
Structured output enables sophisticated workflows. JSON responses can trigger additional data fetching via SWR, enable conditional UI rendering, and support complex application logic that plain text cannot facilitate.

Implementation Approaches

Option 1: Basic `useChat`

Mastra internally uses Vercel AI SDK, making the useChat hook directly available. However, this approach outputs plain text only. Even with JSON format prompts, streaming creates incomplete JSON fragments like { "name": "Jo that cannot be parsed until completion, defeating streaming benefits.

During development, I experimented with custom parsing rules where {{teacherId:123456789}} in AI output would render as <TeacherCard teacherId={123456789} /> components. While functional, this approach can cause visual artifacts and imposes external constraints.

Option 2: `useObject` Hook

The useObject hook represents the primary structured streaming solution for non-agent scenarios:

import { mastra } from "@/src/mastra";

export async function POST(req: Request) {
  const body = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
  const stream = await myAgent.stream(body, {
    output: z.object({
      weather: z.string(),
    }),
  });

  return stream.toTextStreamResponse();
}

import { experimental_useObject as useObject } from '@ai-sdk/react';

export default function Page() {
  const { object, submit } = useObject({
    api: '/api/use-object',
    schema: z.object({
      weather: z.string(),
    }),
  });

  return (
    <div>
      <button onClick={() => submit('example input')}>Generate</button>
      {object?.weather && <p>{object.weather}</p>}
    </div>
  );
}

However, with agent calls, intermediate tool invocations don't match the schema, preventing users from seeing progress updates—only final results appear.

Option 3: Custom Hook Development

After investigating various approaches and reviewing GitHub discussions, I developed a custom solution using Vercel AI SDK's parsePartialJson utility function—the same function powering useObject internally.

Here's the core implementation:

parts: message.parts.map((part) => {
  if (part.type === 'text') {
    const parsedMessage = parsePartialJson(part.text);
    if (['repaired-parse', 'successful-parse'].includes(parsedMessage.state)) {
      return {
        type: 'output',
        structuredData: parsedMessage.value as PartialSchema,
      };
    }

The solution involves parsing partial JSON at each streaming step. The parsePartialJson function intelligently repairs incomplete JSON:

{ "name": "Jo becomes { "name": "Jo" }
{ "array": [1, 2, becomes { "array": [1, 2] }
{ "nested": { "foo": "bar becomes { "nested": { "foo": "bar" } }

This approach requires handling DeepPartial<z.infer<TSchema>> types on the frontend, with appropriate undefined checks.

For tool invocation progress display, use experimental_output instead of output in agent calls:

const result = await mastra.getAgent('manalinkAgent').stream(messages, {
  experimental_output: ResponseSchema,
});
return result.toDataStreamResponse();

Frontend Implementation

UI rendering requires careful handling of partial data:

{messages.map((message) => (
  <div key={message.id}>
    <div>{message.role === 'user' ? 'User' : 'AI'}</div>
    {message.parts.map((part, i) => {
      switch (part.type) {
        case 'output':
          const value = part.structuredData;
          if (!value?.teachers) return null;

          return (
            <div>
              {value.teachers
                .filter((teacher) => teacher?.id)
                .map((teacher) => (
                  <div key={teacher.id}>
                    <h3>
                      {teacher.ranking && <span>{teacher.ranking}位</span>}
                      <span>{teacher.name}</span>
                    </h3>
                    {teacher.ranking && (
                      <p>Reason: {teacher.rankReason}</p>
                    )}
                    <p>{teacher.recommendation}</p>
                    <TeacherCard
                      id={teacher.id}
                      subjectIds={teacher.subjectIds}
                      gradeId={teacher.gradeId}
                    />
                  </div>
                ))}
            </div>
          );

        case 'tool-invocation':
          return (
            <p key={`${message.id}-${i}`}>
              {getToolDisplayName(part.toolInvocation.toolName)}
              {loading && <span>...</span>}
            </p>
          );

        default:
          return null;
      }
    })}
  </div>
))}

Technical Challenges and Solutions

Application-Level Barriers

Next.js App Router Requirement:
Integrating Mastra requires App Router API Routes. While our main app uses Pages Router, we can call App Router APIs from Pages Router components.

Expo 52 Fetch Requirement:
React Native streaming requires Expo 52's enhanced fetch API for proper streaming support.

Infrastructure Considerations

Local Development Setup:
Our Nginx-fronted local environment required specific configuration:

location /api/ {
    proxy_pass {Next.js host and port};
    proxy_buffering off; # Critical for streaming
}

Production Deployment:
Network configuration becomes complex in staging/production environments. Early deployment testing is crucial for streaming and AI agent implementations.

AI Agent Tool Design Philosophy

Structured vs. Unstructured Data Search

We distinguish between two search types:

Structured data: Subject preferences, grade levels—existing database fields that can be filtered programmatically
Unstructured data: "Communication difficulties," "strict teaching style"—requiring embedding and vector search

Balancing Mechanical and AI-Driven Processing

Rather than providing many primitive tools to the agent, we implemented fewer tools that combine mechanical filtering with vector search. This approach prevents hallucinations in areas requiring precise filtering while leveraging AI strengths for similarity matching and recommendation generation.

Our Tool Strategy:

Mechanical filtering: Handle programmatically to ensure accuracy
AI processing: Query generation, similarity scoring, recommendation writing, result ranking

Agile Tool Development

Tool design requires iterative development:

Build basic tools quickly
Integrate with agent early
Observe agent behavior
Refine based on results

Avoid over-engineering individual tools—focus on overall agent effectiveness.

Performance and Monitoring

Speed Optimization

Tool input schema length significantly impacts generation time. Keep tool inputs concise and use memory management to avoid verbose tool calls.

For RAG implementation, we balanced search accuracy with speed, prioritizing reasonable response times over perfect precision given the inherent complexity of teacher-student matching.

Logging and Observability

Mastra provides Pino-based JSON logging for CloudWatch integration:

export const mastraLogger = new PinoLogger({
  name: 'Mastra',
  level: process.env.NODE_ENV === 'production' ? 'info' : 
         (process.env.AI_AGENT_LOG_LEVEL as LogLevel | undefined) ?? 'info',
  overrideDefaultTransports: true,
});

Project Management and Timeline

Resource Allocation

Total effort: 2 person-months

Web Engineer: Vector data processing, embedding research, RAG prototyping
Myself: Everything else (streaming implementation, agent design, UI integration)

Risk Management Strategy

Key approach: Maintain non-agent alternatives until final commitment

Since our team lacked agent development experience, I ensured fallback options remained viable throughout development. This allowed critical evaluation of agent necessity while building stakeholder confidence through progressive demonstrations.

Team Education and Buy-in

Technical Education:

Internal workshops on agent concepts
Hands-on MCP server development
Cursor/coding agent analysis sessions

Stakeholder Engagement:

Visual demonstrations of agent capabilities
Canary releases for internal testing
Progressive feature reveals showing agent advantages

Results and Learnings

Benefits of Structured Streaming

Rich UI variety: Different data types enable tailored visual designs
Contextual messaging: Conditional messages (e.g., no-results explanations) with custom styling
Clean schema separation: Agent prompts focus on business logic while schemas handle data structure

Key Takeaways

Agent development feels like extending familiar coding assistants to new domains
Structured streaming significantly enhances user experience beyond plain text responses
Iterative tool development proves more effective than upfront perfect design
Cross-platform considerations (Next.js + React Native) require careful infrastructure planning
Team education and progressive demonstration essential for stakeholder buy-in

Looking Forward

AI agents represent a natural evolution from the coding assistants we use daily. The combination of streaming responses, structured data, and thoughtful tool design creates genuinely useful applications that enhance rather than replace human decision-making.

For developers interested in agent development, start with your daily coding assistant—understand its tool usage patterns, experiment with MCP servers, and gradually build familiarity with agent behavior patterns.

Interested in AI agent development discussions?
Connect with me on X or Pitta - I'd love to hear about your agent projects and challenges!

Understanding Advanced Promise Patterns in JavaScript

meijin — Wed, 12 Mar 2025 07:38:21 +0000

Understanding Advanced Promise Patterns in JavaScript

If you're looking to master JavaScript's asynchronous programming patterns, you'll want to check out my JavaScript Promise Patterns repository on GitHub. Consider giving it a star if you find it helpful! ⭐

This article dives into the most challenging yet practical aspects of working with Promises in JavaScript. We'll explore patterns that are commonly used in production environments but are often misunderstood.

The Lifecycle of Promise States

One of the most fundamental yet confusing aspects of Promises is understanding how their states evolve. Let's explore what happens behind the scenes with different Promise patterns.

Pending Promises vs Resolved/Rejected Promises

When working with Promises, it's important to understand that a Promise can be in one of three states:

Pending: Initial state, neither fulfilled nor rejected
Fulfilled: The operation was completed successfully
Rejected: The operation failed

// A pending Promise
console.log(new Promise((resolve, reject) => {}));
// Output: Promise { <pending> }

// A resolved Promise
console.log(
  new Promise((resolve, reject) => {
    resolve('resolved');
  })
);
// Output: Promise { 'resolved' }

When you log a Promise directly, you see its current state. However, what many developers miss is that once a Promise is resolved or rejected, its state is immutable - it cannot change again.

The Execution Order Mystery

One of the most confusing aspects of Promises is the execution order of synchronous and asynchronous code. Let's examine a particularly enlightening example:

(() => {
  console.log(1);
  console.log(
    new Promise((resolve, reject) => {
      console.log(2);
      resolve('resolved');
      console.log(3);
    }).then((value) => {
      console.log(value);
    })
  );
  console.log(4);
})();

If you guessed the output would be 1, 2, 3, 4, 'resolved', you understand a key concept! The Promise executor function runs synchronously, but the .then() handlers are always executed asynchronously, even when the Promise is already resolved.

This is a crucial distinction that causes many bugs in real-world applications. The JavaScript event loop processes Promise handlers after the current execution context is complete.

The await Transformation

The await keyword fundamentally changes how we work with Promises, making asynchronous code appear synchronous. But it's essential to understand exactly what's happening:

// Without await
console.log(1);
console.log(axios.get('https://api.example.com/data'));
console.log(2);

// With await
console.log(1);
console.log(await axios.get('https://api.example.com/data'));
console.log(2);

In the first example, line 3 executes immediately after line 2, regardless of whether the API request is complete. In the second example, line 3 only executes after the API request completes.

This difference seems obvious, but it's the source of countless bugs in production code. The await keyword pauses the execution of the async function until the Promise is settled.

Chaining Promises vs await

There are two main approaches to handling sequential asynchronous operations:

Promise chaining:

getIdPromise.then((id) => {
  return axios.get('https://api.example.com/data/' + id);
}).then((response) => {
  console.log(response.data);
});

Using async/await:

const id = await getIdPromise;
const response = await axios.get('https://api.example.com/data/' + id);
console.log(response.data);

While both accomplish the same goal, the async/await approach is generally more readable and easier to debug. However, it's crucial to understand that they work differently under the hood.

Error Handling: The try-catch vs .catch() Dilemma

One of the most nuanced aspects of Promise-based code is error handling. Consider these two approaches:

// Approach 1: Using .catch()
axios.get('https://api.example.com/data')
  .then(response => processData(response))
  .catch(error => handleError(error));

// Approach 2: Using try-catch with await
try {
  const response = await axios.get('https://api.example.com/data');
  processData(response);
} catch (error) {
  handleError(error);
}

While they might seem equivalent, there are subtle differences. The most critical one appears when we have multiple asynchronous operations:

// Using .catch() without await
axios.get('https://api.example.com/data1')
  .then(() => console.log('done1'));

axios.get('https://api.example.com/invalid')
  .then(() => console.log('done2'))
  .catch(() => console.error('error2'));

axios.get('https://api.example.com/data3')
  .then(() => console.log('done3'));

In this example, an error in the second request doesn't prevent the third request from running. However:

// Using try-catch with await
try {
  await axios.get('https://api.example.com/data1')
    .then(() => console.log('done1'));

  await axios.get('https://api.example.com/invalid')
    .then(() => console.log('done2'));

  await axios.get('https://api.example.com/data3')
    .then(() => console.log('done3'));
} catch (error) {
  console.error('error', error.message);
}

In this example, if the second request fails, the third request never runs because execution jumps to the catch block.

The Dangerous try-catch Gap

One of the most insidious bugs in Promise-based code occurs when you use try-catch without await:

try {
  axios.get('https://api.example.com/invalid')
    .then(() => console.log('done'));
} catch (error) {
  console.error('This will never run!', error);
}

The catch block will never execute because the Promise rejection isn't handled by the try-catch. This is because the try-catch completes execution before the Promise resolves or rejects.

To properly handle this, you must either:

Use .catch() on the Promise:

try {
  axios.get('https://api.example.com/invalid')
    .then(() => console.log('done'))
    .catch(error => console.error('Error caught by .catch()', error));
} catch (error) {
  console.error('This still won't run for Promise rejections', error);
}

Use await with try-catch:

try {
  await axios.get('https://api.example.com/invalid')
    .then(() => console.log('done'));
} catch (error) {
  console.error('Now this will run!', error);
}

The Promise Resolution Pattern

When building robust applications, a common pattern is to handle both success and failure gracefully:

const response = await axios
  .get('https://api.example.com/data')
  .catch(_ => undefined);

if (!response) {
  console.log('Error occurred');
  return;
}

// Safely use response data
console.log(response.data);

This pattern is particularly useful in TypeScript, where it creates a union type (Response | undefined), forcing you to check if the response exists before accessing its properties.

Promise Manipulation for API Calls

When working with real-world APIs, it's common to transform the Promise result:

const getPerson = async () => {
  const res = await axios.get('https://api.example.com/people/1');
  return res.data.name;
};

console.log(getPerson); // [Function: getPerson]
console.log(getPerson()); // Promise { <pending> }
console.log(await getPerson()); // "Luke Skywalker"

This pattern of creating functions that return Promises is fundamental in creating clean, maintainable asynchronous code. It allows you to encapsulate complex logic while maintaining a simple interface.

Practical Error Handling Patterns

In production applications, error handling is crucial. Let's examine the most robust approach:

try {
  await axios.get('https://api.example.com/data1')
    .then(() => console.log('done1'));

  await axios
    .get('https://api.example.com/invalid')
    .then(() => console.log('done2'))
    .catch(e => {
      console.error('API Error');
      throw new Error('Clean error message for upstream handlers');
    });

  await axios.get('https://api.example.com/data3')
    .then(() => console.log('done3'));
} catch (error) {
  console.error('Application Error', error.message);
  // Here you might show a user-friendly error message
}

This pattern allows you to:

Handle specific API errors at their source
Transform cryptic error messages into meaningful ones
Decide whether to continue execution or abort
Provide a final fallback for any unhandled errors

Conclusion

Understanding these advanced Promise patterns will dramatically improve your JavaScript code quality. The async/await syntax makes asynchronous code more readable, but it's essential to understand the underlying Promise mechanics to avoid subtle bugs.

For more examples and detailed explanations, check out my JavaScript Promise Patterns repository on GitHub. If you found this article helpful, please give it a star!

What advanced Promise patterns have you found most useful in your projects? Let me know in the comments below!

"bulletproof-react" is a hidden treasure of React best practices!

meijin — Sun, 14 Nov 2021 12:42:03 +0000

The GitHub repository "bulletproof-react", which is published as an example of React application architecture, is very informative and I will share it with my own views.

https://github.com/alan2207/bulletproof-react

Directory structure

https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md

First, you can learn about the directory structure, which tends to vary from project to project.

Put the source code under `src`.

In bulletproof-react, React-related source code is stored under the src directory; conversely, there are no directories such as components or utils in the root directory.

For example, the default application created by Create Next App has source code directories such as pages in the root directory, so putting them under src is the intentional directory structure of this repository.

The root of a real project will have a mix of markdown documentation (docs), CI settings such as GitHub Actions (.github), and Docker settings (docker) if the application is container-based. Therefore, if we put components directly at the root level, the source code of the application and the non-components will be mixed in the same hierarchy.

Not only is this confusing, but it is also convenient to unify the source code under src when writing CI settings, for example, to make it easier to specify the scope of application.

`features` directory

An interesting point in the directory structure of this repository is the features directory.

It contains the following directories:

src
|-- assets
+-- assets # assets folder can contain all the static files such as images, fonts, etc.
*(omitted)*
+-- features # feature based modules ← here
*(omitted)*
+-- utils # shared utility functions

Under features is directories with the name of each feature that the application has. For example, for a social networking service, this might be posts, comments, directMessages, and so on.

src/features/awesome-feature
|
+-- api # exported API request declarations and api hooks related to a specific feature
|
+-- components # components scoped to a specific feature
*(omitted)*
+-- index.ts # entry point for the feature, it should serve as the public API of the given feature and exports everything that should be used outside the feature

When deciding on a directory, it is important to consider what criteria to use. You tend to decide the directory name based on what role the module plays from the engineer's point of view. You may have components, hooks, types, etc. under src, and then finally create a directory for each function in each directory.

I myself create a directory called app/Domain for backend implementations, and then create a directory for each feature, such as app/Domain/Auth or app/Domain/HogeSearch. So it made a lot of sense to manage the front-end with the same idea.

By creating a features directory, you can manage components, APIs, Hooks, etc. by feature. In other words, if you have an API for each feature, you can cut the directory for the API, and if you don't, you don't have to.

Also, if you are running a service, you often want to discontinue a feature, but you only need to delete the corresponding directory under features.
I thought this was a great idea, because there is nothing worse than having unused features lingering around like zombies.

Creating a directory for each feature will also help to speed up the verification of the business side.
If the directory is divided by features/HOGE as in this repository, it is possible to prioritize development speed with a fat design in the initial release, and impose strict constraints in the second and subsequent releases.

You can decide whether a file should be placed under features or not, based on whether it will disappear with the feature when the feature is obsolete.

You can also write ESLint rules to prohibit dependency of features -> features.

        'no-restricted-imports': [
          'error',
          {
            patterns: ['@/features/*/*'],
          },
        ],

https://eslint.org/docs/rules/no-restricted-imports

Place modules that are needed across features under `src/HOGE`.

Components that are used across features, such as simple button elements, should be placed under src/components.

e.g. src/components/Elements/Button/Button.tsx

`providers` and `routes` directories are smart.

When I'm writing React and React Native applications, I often write both Provider and Route settings in App.tsx, and the number of lines gets bloated, but I found it very clever that this repository has separate providers and routes directories.

As a result, the contents of App.tsx are very simple. I would like to copy this.

import { AppProvider } from '@/providers/app';
import { AppRoutes } from '@/routes';

function App() {
  return (
    <AppProvider>
      <AppRoutes />
    </AppProvider>
  );
}

export default App;

Already support the implementation of react-router@v6 assumption.

In v6 of React Router, new features such as <Outlet> can be used to carve out routing into a separate object.

https://remix.run/blog/react-router-v6

https://github.com/remix-run/react-router/tree/main/examples/basic

This repository (at the time of writing, it is dependent on the beta version, so there may be minor changes in the future) already contains the following implementation examples, which I think can be used for preliminary study.

export const protectedRoutes = [
  {
    path: '/app',
    element: <App />,
    children: [
      { path: '/discussions/*', element: <DiscussionsRoutes /> },
      { path: '/users', element: <Users /> },
      { path: '/profile', element: <Profile /> },
      { path: '/', element: <Dashboard /> },
      { path: '*', element: <Navigate to="." /> },
    ],
  },
];

Supplementary information: Other examples of directory structure

I am currently managing a structure similar to the idea of the following article, rather than the idea of aggregating into features.

https://zenn.dev/yoshiko/articles/99f8047555f700

The model in this article is similar to the features in this repository. The general idea is to put all the .tsx files under components, which is well known from the default structure of Nuxt.js, so creating a directory components/models and putting components for each feature under it is also a good idea.

Component Design

https://github.com/alan2207/bulletproof-react/blob/master/docs/components-and-styling.md

The next section is about component design.

Create components in-house that wrap components from external libraries.

This design pattern is called the Anti-Corruption Pattern. I have already worked on it myself and recommend it.

By simply using a component that wraps the <Link> of react-router-dom, as shown below, I can increase the possibility of limiting the scope of influence when destructive changes are made to that component in the future. If you are importing external libraries directly from a number of components, you will be affected, but if you have in-house modules in between, you will have a better chance of limiting the impact.

In fact, it's hard to make it work for all of them, but it's useful to keep it in mind.

import clsx from 'clsx';
import { Link as RouterLink, LinkProps } from 'react-router-dom';

export const Link = ({ className, children, ...props }: LinkProps) => {
  return (
    <RouterLink className={clsx('text-indigo-600 hover:text-indigo-900', className)} {...props}>
      {children}
    </RouterLink>
  );
};

There are many examples of implementations using the Headless component library.

Headless UI is a UI library that can be unstyled or easily overridden, and is only responsible for state retention, accessibility, etc. React components nowadays can take on all the styling, a11y, state, and communication, so a library with this kind of separation of thought is a very smart approach.

Incidentally, the same README says that for most applications, Chakra with emotion is the best choice. I also think that Chakra is currently the best component library, and MUI is the next best, so I rather agree with the statement :)

A design example using react-hook-form

There is a Form library based on the premise of the heyday of Hooks called react-hook-form (RHF). I personally recommend it.

https://react-hook-form.com/

In this repository, RHF is embedded using a wrapper component called FieldWrapper. The idea is to implement a form component by putting <input> etc. in the FieldWrapper.

import clsx from 'clsx';
import * as React from 'react';
import { FieldError } from 'react-hook-form';

type FieldWrapperProps = {
  label?: string;
  className?: string;
  children: React.ReactNode;
  error?: FieldError | undefined;
  description?: string;
};

export type FieldWrapperPassThroughProps = Omit<FieldWrapperProps, 'className' | 'children'>;

export const FieldWrapper = (props: FieldWrapperProps) => {
  const { label, className, error, children } = props;
  return (
    <div>
      <label className={clsx('block text-sm font-medium text-gray-700', className)}>
        {label}
        <div className="mt-1">{children}</div>
      </label>
      {error?.message && (
        <div role="alert" aria-label={error.message} className="text-sm font-semibold text-red-500">
          {error.message}
        </div>
      )}
    </div>
  );
};

I have been discussing design patterns using RHF for a long time, and have published a practical example of component design in the following article.

https://dev.to/texmeijin/component-design-idea-using-react-hook-form-v7-ie0

The design philosophy presented here was to separate the layers as View layer←Logic layer←Form layer.

On the other hand, here is a list of the relative merits of designing with wrapper components in this repository, as perceived at a quick glance.

The label and error display, which should be common to all form components, can be standardized.
- In my design, labels and error messages are handled by either the View layer or the Form layer, so they are not common. It is necessary to implement them separately.
No need to use useController.
- since registration is executed in the Form layer as registration={register('email')}.
- In addition, the argument string of the register method is type-safe.
  - I'm working hard on the type definitions in Form.tsx to make this type-safe.
  - For example, I've adopted the design concept of wrapping View layer as HOC, but I couldn't define the type well without applying some any.
  - The use of unknown in the form of extends T<unknown> such as TFormValues extends Record<string, unknown> = Record<string, unknown> is a typedef tip that I often use for puzzles.
- It may be that the number of re-renders is less than my design plan? (untested).

In addition, it satisfies all the advantages of the idea I was designing, so I thought it was completely upward compatible (great).

Error handling

For error handling in React, react-error-boundary is useful.

https://github.com/bvaughn/react-error-boundary

It may be appropriate to use it in AppProvider.tsx as mentioned above.

      <ErrorBoundary FallbackComponent={ErrorFallback}>
        <Router>{children}</Router>
      </ErrorBoundary>.

I was personally impressed with the behavior of the Refresh button specified in the component for fallback.

      <Button className="mt-4" onClick={() => window.location.assign(window.location.origin)}>
        Refresh
      </Button>.

What window.location.assign(window.location.origin) is doing here is transitioning to the top page because it is transitioning to the origin. When I saw this, I thought that I should just write location.reload(), but I realized that if I want to put a button on the top page, it would be more appropriate to go back to the top page, because it will keep dropping infinitely when an error occurs due to Invalid query parameter or page.

You can also use location.href = to get the same behavior, but assign has the subtle advantage that it is a method call and therefore easier to write tests for, so assign is slightly preferable.

Incidentally, from a personal point of view, I thought it would be better to use location.replace(), which doesn't leave the error in the history, because it seems to be more subtle if you want to return to the page where the error occurred. However, I wonder if that would result in unexpected behavior.

Other

There are many other things that I noticed, but I'll just list them here, instead of reading the Markdown under docs in the repository for details.

The source code scaffolding tool is also set up.
- With Scaffolding, you can generate files of a certain format in a target directory with a single command.
- It is set up under the generators directory.
- This is possible because the directory structure is stable.
- https://www.npmjs.com/package/plop is used
- By the way, I like Scaffdog, which can be written in markdown.
  - https://github.com/cats-oss/scaffdog
The test code setup is also massive
- testing-library is also via test/test-utils.ts as a corruption prevention layer
- The setup of MSW is also very thorough
- I know MSW is useful, but I hadn't imagined what it would look like after it was set up, so it's very helpful.
- Already integrated with GitHub Actions
Performant.
- The basic but important point is that the page components are lazyImported in the Route file, so the code is split.
- I was wondering why React.lazy can only be used for Default Export, but I heard that it can be used for named export. I didn't know that (or I never thought to do something about it).
- https://github.com/alan2207/bulletproof-react/blob/master/src/utils/lazyImport.ts
- I've also made it possible to record web-vitals.
About ESLint
- I didn't set up import/order because I thought it would be too radical, but now that I've seen it set up, it does seem to be easier to read...
Type ReactNode is safe to use.
- I've been using ReactNode for all React element props, but I was wondering if I need to be more strict since ReactNode can be classified into more detailed types. I was wondering if I should do that.
- Of course, there are times when you should do that, but I'm glad to know that ReactNode is fine for most cases.
Naming
- https://github.com/kettanaito/naming-cheatsheet I've never heard of such a repository. I can use it as an internal README.
Overall, I like the selection of libraries (this is completely subjective).
- tailwind
- react-hook-form
- msw
- testing-library
- clsx
- On the other hand, react-helmet is almost out of maintenance, and react-helmet-async should be better, so I published a pull request (https://github.com/alan2207/bulletproof-react/pull/45 )

Summary

I've never seen a template repository with such a thorough and complete set of Production Ready configurations. Personally, I'd like to refer to it regularly as a bookmark because it contains many things I know but haven't used, such as Storybook and Cypress.

I also think vercel/commerce is a good place to learn, but if there are any other repositories you'd recommend, please let me know!

There are a lot of things that I haven't kept up with in the React projects I write on a regular basis at all, but I'd like to keep up with them, judging the need on a case-by-case basis.

Implement a Layered Architecture by React Hook Form (v7)

meijin — Thu, 16 Sep 2021 09:29:22 +0000

I will talk about the idea of component design using React Hook Form (v7).

React Hook Form

React Hook Form is a library for writing validation logics for forms based on Hooks.

With the separation of the form logic in Hooks, it should be possible to implement the View layer written in TSX and the Logic layer responsible for validation separately.

versions

React v17
React Hook Form v7
Material UI v5

An example of TextArea component

In this section, we will consider the case of implementing a TextArea component.

View layer

First, we will implement a simple component that does not depend on React Hook Form. We also use Material UI as a UI framework.

import { FormHelperText, TextareaAutosize, TextareaAutosizeProps } from '@material-ui/core';
import type { ChangeEventHandler, FocusEventHandler } from "react";

export type TextAreaProps = {
  error?: string;
  className?: string;
  placeholder?: string;
};

export const TextArea = (
  props: TextAreaProps & {
    inputRef: TextareaAutosizeProps['ref'];
    value: string;
    onChange: ChangeEventHandler<HTMLTextAreaElement>;
    onBlur: FocusEventHandler<HTMLTextAreaElement>;
  }
) => {
  return (
    <>
      <TextareaAutosize
        minRows={3}
        placeholder={props.placeholder}
        className={props.className}
        ref={props.inputRef}
        value={props.value}
        onChange={props.onChange}
        onBlur={props.onBlur}
      />
      {!!props.error && <FormHelperText error>{props.error}</FormHelperText>}
    </>
  );
};

We have deliberately divided props into TextAreaProps and non-TextAreaProps, the intention of which will be clarified in the next section.

Logic layer

In the logic layer, we create a separate wrapper component that wraps a simple text area defined as the View layer with the logic of the Form.

import { DeepMap, FieldError, FieldValues, useController, UseControllerProps } from 'react-hook-form';

import { TextArea, TextAreaProps } from '~/components/parts/form/textarea/TextArea';
import formControlStyles from '~/components/parts/form/FormControl.module.scss';
import classNames from 'classnames';

export type RhfTextAreaProps<T extends FieldValues> = TextAreaProps & UseControllerProps<T>;

export const RhfTextArea = <T extends FieldValues>(props: RhfTextAreaProps<T>) => {
  const { name, control, placeholder, className } = props;
  const {
    field: { ref, ...rest },
    formState: { errors },
  } = useController<T>({ name, control });

  return (
    <TextArea
      inputRef={ref}
      className={classNames(formControlStyles.formInput, formControlStyles.formTextArea, className)}
      placeholder={placeholder}
      {...rest}
      error={errors[name] && `${(errors[name] as DeepMap<FieldValues, FieldError>).message}`}
    />
  );
};

The component naming is prefixed with Rhf (short for React Hook Form), and the type and other components are dependent on React Hook Form.

The CSS is also imported from a style file dedicated to form controls, named FormControl.module.scss (*If it receives a className, the parent can change its appearance in any way, which is both good and bad). ).

If you use the useController hook, you can get the various values needed for the form component, and you can pour them almost directly into the TextArea component.

The TextAreaProps type is also used for Props in logic layer components. For example, className is passed from Form and relayed to the bottom View layer. I put these relayed types in TextAreaProps.

Form layer

Finally, we will show how to actually use the component we created from the form. We'll call this the Form layer.

First, we will get the control variable of the Form from the useForm hook.

  const {
    control,
    handleSubmit,
    setError,
    formState: { isValid },
  } = useForm<NewPostInput>({
    mode: 'onChange',
    resolver: yupResolver(newPostSchema),
    defaultValues,
  });

And pass control to the RhfTextArea component.

    <RhfTextArea placeholder="post content" name="body" control={control} />

This allows us to do a bit of dependency injection.
On the RhfTextArea component side, we can take the control of any form, pass it to useController, and see the status of that form.

  const {
    field: { ref, ...rest },
    formState: { errors },
  } = useController<T>({ name, control });

Since formState has about 10 properties other than errors, each component can also get the state of the form.
For example, it may be easy to implement disabling a form component when isSubmitting = true.

export declare type FormState<TFieldValues> = {
    isDirty: boolean;
    dirtyFields: FieldNamesMarkedBoolean<TFieldValues>;
    isSubmitted: boolean;
    isSubmitSuccessful: boolean;
    submitCount: number;
    touchedFields: FieldNamesMarkedBoolean<TFieldValues>;
    isSubmitting: boolean;
    isValidating: boolean;
    isValid: boolean;
    errors: FieldErrors<TFieldValues>;
};

Points

Benefits of carving out layers

What are the advantages of separating components in different layers?

The biggest one is that you can use the text area in places other than forms.

It's hard to imagine using a text area in a place other than a form, but for example, a Select box might be used to change the sort order in a list screen. In other words, the implementation of displaying a text area on a form can be divided into two parts: "displaying the text area" and "binding events and styles to it according to the purpose of the form", so that the former can be used more universally.

Another benefit is that it helps to keep dependencies on libraries in order.

If you take a look at the components in the View layer again, you will see that they only depend on Material UI and React:

import { FormHelperText, TextareaAutosize, TextareaAutosizeProps } from '@material-ui/core';
import type { ChangeEventHandler, FocusEventHandler } from "react";

Then, looking at the logic layer, we can see that it depends only on react-hook-form.

import { DeepMap, FieldError, FieldValues, useController, UseControllerProps } from 'react-hook-form';

import { TextArea, TextAreaProps } from '~/components/parts/form/textarea/TextArea';
import formControlStyles from '~/components/parts/form/FormControl.module.scss';

This separation of library dependencies by hierarchy reduces the number of places to look for large updates or library migrations in the future.

References

For those who have seen this article.

I would be happy to exchange React insights with you, please follow my dev.to account and GitHub account.

[PHP/Carbon]The result varies by subMonth, subRealMonth, subMonthNoOverflow

meijin — Tue, 06 Apr 2021 10:28:40 +0000

An error occurred when the end of March

In the end of March, suddenly my CI threw errors running PHPUnit.
The reason is that difference from subMonth, subRealMonth, subMonthNoOverflow in Carbon, which is PHP-date library.

Version of Carbon

2.43.0

Results at the end of March

I executed following PHPUnit code, and checked the result.

    /**
     * When subtract one month from the date at the end of March, you get 28 days before, 30 days before, and exactly one month before, respectively.
     */
    public function test_3月末の日付から1ヶ月引くとそれぞれ28日前、30日前、正確な1月前になる()
    {
        Carbon::setTestNow(Carbon::create(2001, 3, 31, 10));
        self::assertEquals(
            Carbon::create(2001, 3, 3, 10),
            Carbon::now()->subMonth(),
        );
        self::assertEquals(
            Carbon::now()->subDays(30),
            Carbon::now()->subRealMonth(),
        );
        self::assertEquals(
            Carbon::create(2001, 2, 28, 10),
            Carbon::now()->subMonthNoOverflow(),
        );
    }

The result of subMonth is March 3, which is 3 days after end of February. Why?
Because subMonth judged the date is February 31. But it does not exist. And February 31 is equally March 3. So the result is March 3.

The result of subRealMonth is just 30 days ago.

Finally, subMonthNoOverflow outputted the end of February!
Because the method rounds down overflowed date, so February 31 becomes February 28.

In short, subMonth and subRealMonth sometimes output day in current Month.

Results at the end of March(Leap year)

And, in leap years, the methods has same logic.

    /**
     * When subtract one month from the end of March in a leap year, you get 29 days before, 30 days before, and exactly one month before, respectively.
     */
    public function test_うるう年の3月末から1ヶ月引くとそれぞれ29日前、30日前、正確な1月前になる()
    {
        Carbon::setTestNow(Carbon::create(2000, 3, 31, 10));
        self::assertEquals(
            Carbon::create(2001, 3, 2, 10),
            Carbon::now()->subMonth(),
        );
        self::assertEquals(
            Carbon::now()->subDays(30),
            Carbon::now()->subRealMonth(),
        );
        self::assertEquals(
            Carbon::create(2000, 2, 29, 10),
            Carbon::now()->subMonthNoOverflow(),
        );
    }

The difference point is subMonth's result.
In leap years, February 31 equals March 2 because February has 29 days.

Therefore, I recommend subMonthNoOverflow method when you should subtract months from specific date. The result is intuitive.

How to calculate the 15th of the previous month

According to difference of these methods, let's check how to calculate the 15th of the previous month.

    /**
     * When the requirement is to calculate 0:00:00 on the 15th of the previous month, care should be taken to execute startOfMonth() first, or subMonthNoOverflow() should be used.
     */
    public function test_前月の15日0時0分を算出するという要件の時は先にstartOfMonthを実行するように気をつけるか、subMonthNoOverflowを使うべき()
    {
        Carbon::setTestNow(Carbon::create(2001, 3, 31));
        self::assertEquals(
            Carbon::create(2001, 2, 15),
            Carbon::now()->startOfMonth()->subMonth()->addDays(14),
        );

        // when subMonth executed before startOfMonth, the month is March...
        self::assertEquals(
            Carbon::create(2001, 3, 15),
            Carbon::now()->subMonth()->startOfMonth()->addDays(14),
        );

        self::assertEquals(
            Carbon::create(2001, 2, 15),
            Carbon::now()->subMonthNoOverflow()->startOfMonth()->addDays(14),
        );

        self::assertEquals(
            Carbon::create(2001, 2, 15),
            Carbon::now()->startOfMonth()->subMonthNoOverflow()->addDays(14),
        );
    }

Conclusion

Use subMonthNoOverflow instead of subMonth, subRealMonth. The result is always intuitive. In limited case, subMonth and subRealMonth should be used.

Starter using Vite + React + TypeScript + Tailwind CSS.

meijin — Sun, 21 Mar 2021 09:32:20 +0000

I made this template repository: https://github.com/TeXmeijin/vite-react-ts-tailwind-starter.

It is starter using Vite + React + TypeScript + Tailwind. And already set up Prettier and ESLint.

Motivation

Improve building your faster prototyping by using Vite, TypeScript, React, TailwindCSS.

Vite

Vite is a fast frontend build tool. According to the README, it consists of two major parts:

A dev server that serves your source files over native ES modules, with rich built-in features and astonishingly fast Hot Module Replacement (HMR).
A build command that bundles your code with Rollup, pre-configured to output highly optimized static assets for production.

React

React is a JavaScript library for building user interfaces.

Due to its awesome renderer system, there are many React Renderor. So React can be not used only Web, for example, used by React Native.

Let's dive into React and Vite can use with React.

TypeScript

TypeScript is a superset of JavaScript. It is just one of NPM library, but it provides an original compiler.

When you use TypeScript with React, you can write JSX with TypeScript, called TSX. Then you can develop views written by Type-Safe template.

Tailwind CSS

Tailwind CSS is modern utility-first CSS framework. It provides many CSS rules, but these are purged when production builds. So developers do not worry about CSS asset size for performance optimization.

In VSCode, I recommend to use intellisense extension.

Frequently, React developers are worried about how to write CSS in TSX(JSX) template. You must choose from CSS Modules, styled-components, linaria, and so on.
Additionally, CSS architecture is difficult about scoping, e.g. BEM, FLOCSS.

When you decide to use Tailwind, you only write utility-first CSS classes, you don't have to worry about them!

Formatter and Linter

Already set up ESLint and Prettier. You can customize the rules.

NOTICE: The template does not use eslint-plugin-prettier and prettier-eslint. So I recommend that running commands individually. e.g. prettier && eslint.

Please read: https://prettier.io/docs/en/integrating-with-linters.html.

Making Lambda@Edge and executing `cdk deploy` occurred a 400 Error with "The function cannot have environment variables"

meijin — Wed, 29 Jul 2020 04:34:39 +0000

Environment

aws-cdk v1.53.0 or above
aws-lambda-nodejs

My code

I want to deploy lambda@edge source code by aws-cdk.

    new NodejsFunction(this, 'some-awesome-function', {
      role: new Role(this, 'AllowLambdaServiceToAssumeRole', {
        assumedBy: new CompositePrincipal(
          new ServicePrincipal('lambda.amazonaws.com'),
          new ServicePrincipal('edgelambda.amazonaws.com')
        ),
      }),
    })

My command

cdk deploy

Error Message

CREATE_FAILED        | AWS::CloudFront::Distribution | XXXX/CFDistribution (XXXXCFDistributionXXXX) The function cannot have environment variables. Function: arn:aws:lambda:us-east-1:XXXX:function:CdkStack-XXXXD6AD4BEB-1XXXXXXMFY8E:1 (Service: AmazonCloudFront; Status Code: 400; Error Code: InvalidLambdaFunctionAssociation;

Solution

set awsSdkConnectionReuse to false in your props.

    new NodejsFunction(this, 'some-awesome-function', {
      role: new Role(this, 'AllowLambdaServiceToAssumeRole', {
        assumedBy: new CompositePrincipal(
          new ServicePrincipal('lambda.amazonaws.com'),
          new ServicePrincipal('edgelambda.amazonaws.com')
        ),
      }),
      awsSdkConnectionReuse: false,
    })

Reason

At July 2020, Lambda@Edge doesn't support Environment Values.

But aws-cdk v1.53.0 update contains default true of AWS_NODEJS_CONNECTION_REUSE_ENABLED.

https://github.com/aws/aws-cdk/commit/44c040072362456ebdd15799076a67bbb74e6668

      // Enable connection reuse for aws-sdk
      if (props.awsSdkConnectionReuse ?? true) {
        this.addEnvironment('AWS_NODEJS_CONNECTION_REUSE_ENABLED', '1');
      }

So you must set false the prop.

DEV Community: meijin

Building a Teacher Search AI Agent with Mastra and Structured Data Streaming

Key Features

Technical Architecture Overview

Environment Information

The Challenge of Structured Data Streaming

Why Streaming Matters

Why Structure Matters

Implementation Approaches

Option 1: Basic useChat

Option 2: useObject Hook

Option 3: Custom Hook Development

Frontend Implementation

Technical Challenges and Solutions

Application-Level Barriers

Infrastructure Considerations

AI Agent Tool Design Philosophy

Structured vs. Unstructured Data Search

Balancing Mechanical and AI-Driven Processing

Agile Tool Development

Performance and Monitoring

Speed Optimization

Logging and Observability

Project Management and Timeline

Resource Allocation

Risk Management Strategy

Team Education and Buy-in

Results and Learnings

Benefits of Structured Streaming

Key Takeaways

Looking Forward

Understanding Advanced Promise Patterns in JavaScript

Understanding Advanced Promise Patterns in JavaScript

The Lifecycle of Promise States

Pending Promises vs Resolved/Rejected Promises

The Execution Order Mystery

The await Transformation

Chaining Promises vs await

Error Handling: The try-catch vs .catch() Dilemma

The Dangerous try-catch Gap

The Promise Resolution Pattern

Promise Manipulation for API Calls

Practical Error Handling Patterns

Conclusion

"bulletproof-react" is a hidden treasure of React best practices!

Directory structure

Put the source code under src.

features directory

Place modules that are needed across features under src/HOGE.

providers and routes directories are smart.

Already support the implementation of react-router@v6 assumption.

Supplementary information: Other examples of directory structure

Component Design

Create components in-house that wrap components from external libraries.

There are many examples of implementations using the Headless component library.

A design example using react-hook-form

Error handling

Other

Summary

Implement a Layered Architecture by React Hook Form (v7)

versions

An example of TextArea component

View layer

Logic layer

Form layer

Points

Benefits of carving out layers

References

[PHP/Carbon]The result varies by subMonth, subRealMonth, subMonthNoOverflow

An error occurred when the end of March

Version of Carbon

Results at the end of March

Results at the end of March(Leap year)

How to calculate the 15th of the previous month

Conclusion

Starter using Vite + React + TypeScript + Tailwind CSS.

Motivation

Vite

React

TypeScript

Option 1: Basic `useChat`

Option 2: `useObject` Hook

Put the source code under `src`.

`features` directory

Place modules that are needed across features under `src/HOGE`.

`providers` and `routes` directories are smart.