There is often a disparity between the concrete representation and storage of data from its necessary use within the application. Let’s break down each concept by how they work together to create a data layer segregated into sub-layers with specific responsibilities.

So, to get terminology correct, we will explain the difference between an “entity” and “model” and how DTO and DAO play roles. The core difference is one of concern and context: an Entity is about the database representation, while a Model is about the business logic representation.

Entity: The Database Ambassador

An Entity is a class that is directly mapped to a database table. Its purpose is to represent the state and structure of a database record.

• Primary Concern: Data Persistence

• Lives in: The Data Access/Persistence Layer

• Characteristics:

  • Each instance corresponds to a row in a table.

  • Its fields/properties map directly to table columns.

  • It often includes ORM (Object-Relational Mapping) annotations like @Entity, @Table, @Column (in Java/JPA) or similar decorators in other languages (e.g., [Table] in C#, @entity in Python with SQLAlchemy).

  • It defines relationships (e.g., @OneToMany, @ManyToOne) to other entities.

• Example: A UserEntity class with an id, username, password_hash, created_date, etc., that exactly matches the users database table.

  // Java (JPA) Example
  @Entity
  @Table(name = "users")
  public class UserEntity {
      @Id
      @GeneratedValue(strategy = GenerationType.IDENTITY)
      private Long id;
  
      @Column(name = "username", nullable = false, unique = true)
      private String username;
  
      @Column(name = "password_hash", nullable = false)
      private String passwordHash;
  
      // ORM Annotations, getters, and setters
  }

Model (aka Domain Model): The Business Brain

A Model (also often called a Domain Model or Business Model) is a class that represents a core concept of your business domain. It contains both data and the behavior (business logic) that operates on that data.

• Primary Concern: Implementing Business Logic and Rules.

• Lives in: The Domain Layer (the heart of the application).  It is persistence-ignorant (no ORM annotations) and rich with business methods.

• Characteristics:

  • It is persistence-ignorant; it has no knowledge of how or where its data is saved. It should not have any ORM annotations.

  • Encapsulates the business rules and logic of your application — methods that enforce business rules (e.g., calculateTotal(), validate(), changePassword()).

  • It is the most important layer and should be the least likely to change if your database or API changes.

• Example: A User model that has a method changePassword() which enforces password complexity rules before updating its own password field.

  // Java Example - Pure Domain Model
  public class User {
      private Long id;
      private String username;
      private String password; // Might be hashed by a service, not the model itself
  
      // Business logic lives here
      public boolean isValidPassword(String inputPassword) {
          // Logic to validate password against stored hash
          return PasswordEncoder.matches(inputPassword, this.password);
      }
  
      // Getters and setters might have validation logic
      public void setUsername(String username) {
          if (username == null || username.trim().isEmpty()) {
              throw new IllegalArgumentException("Username cannot be empty");
          }
          this.username = username;
      }
      // ... other getters and setters
  }

The Model is the “truth” of your business. The Entity is just a persistence mechanism for that model. In simpler applications, the Entity and the Model are often the same class, but this is considered an anti-pattern in complex domains because it couples your business logic to your database schema.

Data Transfer Object (DTO): The Data Courier

A DTO is a simple container for data used to move information between layers, especially across network boundaries. Its sole purpose is to reduce the number of method calls by aggregating data.

• Primary Concern: Data Transfer, often over a network (e.g., API requests/responses).

• Lives in: The Service Layer or Presentation Layer.

• Characteristics:

  • It contains no business logic—only fields, getters, and setters.

  • It is often tailored to a specific use case (e.g., UserCreationRequest, UserSummaryResponse).

  • Provides a stable, decoupled contract for external communication; used to decouple your internal domain/entity from your external API contract.

  • It protects your API from internal changes. You can change your User model’s structure without breaking your API clients, and vice-versa.

• Example: A UserDto sent to a web client that excludes sensitive fields like passwordHash and includes a calculated fullName field.

  // Example DTO for sending user data to a client
  public class UserDto {
      private Long id;
      private String username;
      private String email;
      private String fullName; // A field that might not exist in the Entity
  
      // No logic, only getters and setters
      public String getFullName() {
          return fullName;
      }
      public void setFullName(String fullName) {
          this.fullName = fullName;
      }
  }

Data Access Object (DAO)

A DAO is a design pattern that provides an abstract interface to the database. It hides all the intricate details of the persistence mechanism (e.g., SQL, NoSQL queries) from the rest of the application.

• Primary Concern: Abstracting data access and persistence operations.

• Lives in: The Data Access Layer.

• Characteristics:

  • Separates persistence logic from business logic.

  • It provides CRUD (Create, Read, Update, Delete) operations for a specific entity/model.

  • The application uses the DAO interface, not direct database calls. This makes it easy to switch databases (e.g., from MySQL to PostgreSQL) or switch from SQL to a web API.

  • In modern development, the DAO is often replaced or implemented by an ORM (like Hibernate, Entity Framework, Django ORM, Sequelize). The Repository pattern is a more advanced evolution of the DAO pattern.

• Example: A UserDao interface with methods like findById, save, delete, and findAll.

  // DAO Interface
  public interface UserDao {
      Optional<UserEntity> findById(Long id);
      List<UserEntity> findAll();
      UserEntity save(UserEntity user);
      void delete(Long id);
  }
  
  // JPA-based implementation of the DAO interface
  @Repository // Spring stereotype marking this as a DAO
  public class JpaUserDao implements UserDao {
  
      @PersistenceContext
      private EntityManager entityManager;
  
      @Override
      public Optional<UserEntity> findById(Long id) {
          return Optional.ofNullable(entityManager.find(UserEntity.class, id));
      }
      // ... implement other methods
  }

How They Work Together in a Flow

Let’s imagine an API endpoint GET /users/{id}:

1. Presentation Layer (Controller):

   • Receives the HTTP request and extracts the user id.

   • Calls a method on a Service.

2. Service Layer:

   • The service contains business logic. It calls a DAO to fetch the data.

3. Data Access Layer (DAO):

   • The DAO (e.g., userDao.findById(id)) executes the database query.

   • It returns a UserEntity object, which is a direct representation of the database row.

4. Service Layer (cont.):

   • The service might perform operations using the User model (if one exists). It might convert the UserEntity to a User domain model to apply business rules.

   • It then converts the result (either the UserEntity or the User model) into a UserDTO tailored for the response (e.g., hiding the password hash, formatting names).

5. Presentation Layer (Controller):

   • The controller receives the UserDTO from the service and serializes it to JSON to send back in the HTTP response.

This flow ensures each layer has a single responsibility and is decoupled from the others, leading to maintainable, testable, and flexible software.

DTOs and Models: A Flexible Relationship

DTOs closely parallel (and may even match) the corresponding data model

• Often True, but Not a Rule: It’s very common for a DTO to initially look identical to the domain model it represents, especially for simple CRUD operations. A UserModel might have id, name, email, and the UserResponseDto might have those same fields.

• The Divergence is the Point: The power of the DTO pattern emerges when they stop matching. DTOs are tailored to the specific needs of a client or use case, while the Model is the single source of truth.

  • Combination: A UserProfileDto might combine data from a UserModel and a UserProfileModel.

  • Omission: A PublicUserDto might return a user’s name and avatarUrl but omit their email for privacy.

  • Addition: A UserDto might include a calculated field like isEligibleForDiscount that isn’t stored in the model but is derived from its data.

  • Flattening: A UserOrderDto might flatten a relationship, taking the orderNumber from an associated OrderModel instead of nesting the entire OrderModel object.

DTOs often start life as mirrors of Models but are expected to diverge based on external requirements. The Model is stable; the DTO is volatile and adaptable.

DAOs and Entities: A Direct Mirror

DAOs closely match the entity definitions

• This is Almost Always True: This relationship is much more direct and rigid. A DAO’s single responsibility is to perform CRUD operations on a specific Entity.

• One-to-One Mapping: You will typically have:

  • A UserEntity class.

  • A UserDao interface (e.g., UserRepository in Spring).

  • The UserDao will have methods like save(UserEntity entity), findUserEntityById(Long id), and delete(UserEntity entity).

• The DAO is Contracted to the Entity: The DAO’s interface is defined by the structure and relationships of the Entity it manages. Its purpose is to translate that object-oriented structure into persistence commands (SQL, etc.).

The DAO is fundamentally tied to its corresponding Entity. This is a very strong, one-to-one coupling by design.

Visualizing the Relationships

A Practical Example

Imagine an application with a User and a Order model.

1. Persistence Layer:

   • UserEntity (id, username, password_hash, created_date)

   • OrderEntity (id, user_id, total_amount, status)

   • UserDao – methods like save(UserEntity), findById(id)

   • OrderDao – methods like save(OrderEntity), findOrdersByUser(UserEntity)

   Here, the DAOs are tightly coupled to their respective Entities.

2. Business Layer:

   • User model (id, username, password, ordersList, hasPasswordExpired())

   • Order model (id, totalAmount, status, canBeCancelled())

3. API Response:

   • You need an API endpoint that returns a user’s profile along with a summary of their recent orders.

   • You would create a UserProfileDto:

     public class UserProfileDto {
         private Long id;
         private String username;
         private List<OrderSummaryDto> recentOrders; // <- Flattened/combined data
     }

   • This DTO does not match any single Model. It combines data from the User model and the Order model and presents it in a tailored structure for the client.

Final Takeaway: Your intuition is spot-on for the data access layer (DAO/Entity mirroring). For the interface layer (DTO/Model), the parallelism is a common starting point, but the strategic value of DTOs is realized when they are allowed to be different from the domain models to meet external demands without polluting the core business logic.

What Are Data Transfer Objects (DTO)s?

DTOs are objects that define the structure of data being transferred between layers of an application (e.g., client and server). They are typically used to:

1. Encapsulate Data: Define a clear contract for the shape of data being sent or received.
2. Validate Data: Ensure that the data conforms to a specific structure.
3. Decouple Layers: Abstract the internal structure of the server or database from the client.

DTOs with Next.js Server Actions

Server actions in Next.js provide a way to handle server-side logic directly in the application. By using DTOs as interfaces for server actions, you can:

1. Standardize Data Contracts
   • Define clear and reusable interfaces for the data sent to and received from server actions.
   • Ensure consistency across the application.
2. Improve Type Safety
   • Use TypeScript to enforce the structure of data at compile time.
   • Reduce runtime errors caused by unexpected data shapes.
3. Simplify Validation
   • Validate incoming and outgoing data against the DTO structure.
   • Use libraries like zod or class-validator for runtime validation.
4. Enhance Maintainability:
   • Centralize data definitions, making it easier to update and refactor the application.

How to Implement DTOs with Server Actions in Next.js

Step 1: Define DTO Interfaces

Create TypeScript interfaces or types to define the structure of the data being transferred.

import { z } from "zod";

// Define the DTO schema using zod for runtime validation
export const SheetUserWeightsDTO = z.object({
  userId: z.string(),
  sheetId: z.string(),
  specWeights: z.record(z.string(), z.number()), // Example: { spec1: 0.5, spec2: 0.8 }
  specsVersion: z.number(),
});

// Infer the TypeScript type from the zod schema
export type SheetUserWeightsDTOType = z.infer<typeof SheetUserWeightsDTO>;

Step 2: Use DTOs in Server Actions

Leverage the DTOs in server actions to validate and enforce the structure of incoming and outgoing data.

import { SheetUserWeightsDTO, SheetUserWeightsDTOType } from "@/lib/dto/sheetUserWeights.dto";

export async function saveSheetUserWeightsAction(data: SheetUserWeightsDTOType): Promise<void> {
  // Validate the incoming data
  const parsedData = SheetUserWeightsDTO.parse(data);

  // Perform the server-side logic (e.g., save to database)
  const { userId, sheetId, specWeights, specsVersion } = parsedData;

  // Example: Save to database
  await db.collection("sheetUserWeights").updateOne(
    { userId, sheetId },
    { $set: { specWeights, specsVersion } },
    { upsert: true }
  );
}

export async function getSheetUserWeightsAction(userId: string, sheetId: string): Promise<SheetUserWeightsDTOType | null> {
  // Fetch data from the database
  const result = await db.collection("sheetUserWeights").findOne({ userId, sheetId });

  if (!result) return null;

  // Validate the fetched data
  return SheetUserWeightsDTO.parse(result);
}

Step 3: Use DTOs in Client-Side Hooks

Use the DTOs in React Query hooks to ensure type safety and consistency.

import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { SheetUserWeightsDTOType } from "@/lib/dto/sheetUserWeights.dto";
import { getSheetUserWeightsAction, saveSheetUserWeightsAction } from "@/lib/actions/sheets";

export function useQuerySheetUserWeights(userId: string, sheetId: string) {
  return useQuery<SheetUserWeightsDTOType | null, Error>({
    queryKey: ["sheetUserWeights", userId, sheetId],
    queryFn: () => getSheetUserWeightsAction(userId, sheetId),
    enabled: !!userId && !!sheetId,
    staleTime: 1000 * 60 * 5, // Cache for 5 minutes
  });
}

export function useSaveSheetUserWeights() {
  const queryClient = useQueryClient();

  return useMutation<void, Error, SheetUserWeightsDTOType>({
    mutationFn: saveSheetUserWeightsAction,
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries(["sheetUserWeights", variables.userId, variables.sheetId]);
    },
  });
}

Benefits of This Approach

1. Type Safety
   • Both the client and server share the same DTO definitions, ensuring consistent data structures.
2. Validation:
   • DTOs can validate incoming and outgoing data at runtime, catching errors early.
3. Reusability:
   • DTOs can be reused across server actions, client-side hooks, and even database queries.
4. Scalability:
   • As the application grows, DTOs provide a clear and maintainable way to manage data contracts.

When to Use DTOs

• Complex Applications:
  • DTOs are especially useful in applications with complex data flows or multiple layers (e.g., client, server, database).
• Shared Data Contracts:
  • When the same data structure is used across multiple parts of the application (e.g., client and server).
• Validation Requirements:
  • When you need to validate data at runtime to ensure correctness.

Conclusion

Using DTOs as interfaces for server actions in Next.js is a powerful design pattern that improves type safety, validation, and maintainability. By defining DTOs with tools like zod or TypeScript interfaces, you can standardize data contracts across your application and ensure consistency between the client and server.

This article was generated mostly via my prompting of AI CoPilot; Image was generated via Claude.ai. I had to edit the result.

1. Use Markdown for a text-heavy portion of a page of my web app, and
2. To be able to have an entire page of content come from a single Markdown page

The former is a feature of NextJS to allow markdown content to be imported as a “component,” which can be rendered like any component in ReactJs.

The latter would rely NextJS’s App Router that assumes many URL paths for the app parallel the file/directory hierarchy of the app itself. So, merely placing a “page” file in the app’s directory will create a new URL path for the website. That means that you can create a “page.md” or “page.mdx” file with Markdown text content to define the content for that URL. .mdx files also allow JSX syntax so that React/Next components can be embedded within the Markdown.

Setup

The first issue was getting things set up. Here were the steps that worked for me.

1. Add packages. The highlighted line was missing from the documentation.

   npm install @mdx-js/loader @mdx-js/react @next/mdx
   npm install -D @types/mdx
   

2. In next.config.*, add
   1. import withMDX from "@next/mdx";
   2. Add “md” (optional) and “mdx” extensions for App Router support: nextConfig.pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx']
   3. Create, then wrap the Next config with mdx-configwithMDX = createMDX({})…export default withMDX(nextConfig)

   Note: I had to avoid using .ts to avoid syntax errors to support the “remark-gfm” plugin. I recommend using .js or .mjs extensions, I chose the latter.

   import type {NextConfig} from 'next';
   
   const nextConfig: NextConfig = {
     typescript: {
       ignoreBuildErrors: true,
     },
     eslint: {
       ignoreDuringBuilds: true,
     },
   };
   
   export default nextConfig;

   asdfasdf asdf asdf asd f

   import type {NextConfig} from 'next';
   import withMDX from "@next/mdx";
   
   const nextConfig: NextConfig = {
     pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
     typescript: {
       ignoreBuildErrors: true,
     },
     eslint: {
       ignoreDuringBuilds: true,
     },
   };
   
   const withMdxConfig = withMDX({
     options: {
       remarkPlugins: [],
       rehypePlugins: [],
     },
   });
   
   export default withMdxConfig(nextConfig);

3. Add the mdx-components.tsx file to src/. This file allows overriding how tags and components will be rendered, providing a mapping from tag/component name to an overriding render function; see the official documentation, mdx-components.js, but I will elaborate on how we’ll use this in the following sections.

   import type { MDXComponents } from 'mdx/types'
   
   export function useMDXComponents(components: MDXComponents): MDXComponents {
      return {
         ...components,
      }
   }
   

4. Help VSCode resolve imports
   1. Open settings
   2. Search for “file associations”
   3. Add item key = *.mdx, value = markdown. (Articles say, “react-markdown,” but that didn’t work for me).
5. Styles will need to be defined for all the generated HTML tags. See the next sections. 

Defining Markdown Output Style

Markdown syntax is translated to HTML. By default, the HTML tags have had their formatting stripped, for some reason. That means that the tags need to have style/class definitions applied to render properly. See How to use markdown and MDX in Next.js, for the official word.

The following are tags that correspond to Markdown syntax:

By default, NextJS removes the styling for the Markdown HTML tags, so we have to define them. 

Wrapper

Styles and classnames can be defined for any tag and component by redefining it to render with a style or className property, as desired. Instead, we will take advantage of a special Component named “wrapper” that wraps any .mdx content and define tag styles within that container context. Then we define all tag’s styles in an importable CSS module. 

import type { MDXComponents } from 'mdx/types'
import styles from './mdx-components.module.css'

export function useMDXComponents(components: MDXComponents): MDXComponents { 
   return { 
      ...components, 
      wrapper: ({ children }) => <div className={styles.mdxWrapper}>{children}</div>,
   } 
}

The file name and the wrapper class names are irrelevant so long as they match. Here is a good starting point for the “mdx-components.module.css” that I use. Note the class name, “_mdxWrapper” parent style definition. 

/**
 * Style definitions for tags corresponding to Markdown for MDX components
 * This file provides a reset for common HTML elements used in MDX content
 * to ensure consistent styling.
 */
._mdxWrapper {
  h1, h2, h3, h4, h5, h6, p, blockquote, pre, table {
    display: block;
    margin-block: initial;
    margin-inline: initial;
  }

  h1, h2, h3, h4, h5, h6 { font-weight: bold; }

  h1 {
    border-top: 1px solid lightgray;
    margin-block-start: 0.67em;
    font-size: 2em;
  }
  h2 { margin-block-start: 0.83em; font-size: 1.5em; }
  h3 { margin-block-start: 1em;    font-size: 1.17em; }
  h4 { margin-block-start: 1.67em; font-size: 1em; }
  h5 { margin-block-start: 1.33em; font-size: 0.83em; }
  h6 { margin-block-start: 2.33em; font-size: 0.67em; }

  p { margin-block: 0.4em; }

  a {
    color: -webkit-link;
    text-decoration: underline;
    cursor: pointer;
  }

  ul, ol {
    display: block;
    padding-inline-start: 1.5625rem;
  }
  ul { list-style-type: disc; }
  ul ul { list-style-type: circle; }
  ul ul ul { list-style-type: square; }
  ol { list-style-type: decimal; }
  
  blockquote {
    margin-block: 1em;
    margin-inline: 40px;
  }
  code, pre {
    font-family: monospace;
  }
  pre {
    display: block;
    margin-block: 1em;
    white-space: pre;
  }

  img {
    display: inline-block;
    max-width: 100%;
    height: auto;
  }

  table {
    /* Table styling variables */
    /* --table-border-color: blue; */
    /* --table-border-width: 2px;  */    /* Enable to non-0 to surround table with border */
    /* --table-header-background-color: #f2f2f2; */ /* Enable for distinct header background	color */
    --table-header-border-color: #BBB;   /* Defaults to cell border color */
    --table-header-border-width: 2px;    /* Defaults to row border width */
    --table-body-row-border-width: 1px;  /* Enable to non-0 show row dividers */
    --table-body-col-border-width: var(--table-body-row-border-width,1px);  /* Enable to non-0 show col dividers */
    --table-body-cell-border-color: lightgray;  /* Override border color */
    --table-body-background-color: white;/* Even row background color */
    --table-body-background-color-alt: #f9f9f9; /* Odd row background color */
    margin-left: var(--table-body-row-border-width,0);
    border-collapse: collapse;
    text-indent: initial;
  }
  thead, tbody, tfoot {
    vertical-align: middle;
  }
  thead {
    border-color: var(--table-border-color);
    border-width: var(--table-border-width,0) var(--table-border-width,0) 0 var(--table-border-width,0);
  }
  tbody {
    border-color: var(--table-border-color);
    border-width: 0 var(--table-border-width,0) var(--table-border-width,0) var(--table-border-width,0);
  }
  thead th {
    background-color: var(--table-header-background-color, inherit);
    /* border-style: solid; */
    border-color: var(--table-header-border-color, var(--table-body-cell-border-color));
    border-bottom-width: var(--table-header-border-width,var(--table-body-row-border-width,0));
  }
  tr {
    vertical-align: inherit;
    border: none; /* Disable row borders */
    border-color: inherit;
  }
  td, th {
    /* No top border, conditional side/bottom borders */
    border-width: 0 var(--table-body-col-border-width, 0px) var(--table-body-row-border-width, 0px) var(--table-body-col-border-width, 0px);
    border-color: var(--table-body-cell-border-color);
    padding-inline: 8px;
  }
  /* No side borders */
  td:last-child, th:last-child { border-right: none; }
  td:first-child, th:first-child { border-left: none; }

  /* Alternating background colors for table rows */
  tbody tr:nth-child(odd)  { background-color: var(--table-body-background-color); }
  tbody tr:nth-child(even) { background-color: var(--table-body-background-color-alt); }
} /* ._mdxWrapper */

Checkbox Support via “remark-gfm”

Github markup is supported via the remark-gfm plugin, however, I was never able to get it to work as documented (i.e., import and add  remarkGfm  to the plugins array. Instead, I had to use the string name of the plugin and add an array to the plugins array:

const withMdxConfig = withMDX({
  options: {
    remarkPlugins: [['remark-gfm']],
    rehypePlugins: [],
  },
});

export default withMdxConfig(nextConfig);

import withMDX from "@next/mdx"
import remarkGfm from 'remark-gfm'

const nextConfig: NextConfig = {
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
}

const withMdxConfig = withMDX({
  options: {
    // If you use remark-gfm, you'll need to use next.config.mjs
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
})

export default withMdxConfig(nextConfig);

The styling for task/checkboxes needs to be set. Unfortunately, remark-gfm uses class names to identify the list and list item tags. Since importing CSS modules mangles names, we have to import the CSS definitions directly. We can create a CSS file, randomly named, “remark-gfm.css”

/* remarkGfm MDX Checkbox support for remarkGfm */
ul.contains-task-list li.task-list-item {
  list-style-type: none; /* Remove list style for task list items */
  text-indent: -18px;    /* ...and outdent it so it aligns        */
}
/* Undo <li> inherited styling within nested chckbox lists */
ul.contains-task-list li:not(.task-list-item) {
  list-style-type: initial;
  text-indent: initial;
}

Then import this directly into “mdx-components.tsx.” Alternatively, you can add these style definitions in global.css.

import type { MDXComponents } from 'mdx/types'
import styles from './mdx-components.module.css'
import './remark-gfm.css'

export function useMDXComponents(components: MDXComponents): MDXComponents {
   return {
      ...components,
      wrapper: ({ children }) => <div className={styles._mdxWrapper}>{children}</div>,
   }
}

Note: This style definition will affect all content on the page, even outside an MDX component. 

Summary

I was led down a bunch of rabbit holes due to NextJS’s Markdown support not matching the documented steps. With the steps described in this post, others should be able to get it working without the headaches I had to go through.

1. Npm-install mdx support packages
2. Update VSCode file association settings (optionally)
3. Update “next.config.mjs”
4. Create src/mdx-components.tsx and import a CSS module to define and wrap tag style definitions
5. If GitHub markdown support is desired, add the plugin and import CSS definitions into mdx-components.tsx

Then you can use Markdown content for App Router pages as page.mdx React components, implicitly.

# Page Title

This is an example a NextJS App Router page, written with Markdown syntax. 

import UpdateContent from "./updates.mdx" // Markdown content

export default async function UpdatesPage() { // App Router page component

return (
  <>
     <h1>Updated News</h1>
     <UpdateContent/> {/* Render Markdown component */}
  </>
)

macOS pbpaste and pbcopy

macOS has two commands, pbpaste and pbcopy, which “paste” from the pasteboard to stdout and copies from stdin to the pasteboard, respectively.macOS calls their clipboard a “pasteboard”, so the pb… prefix makes sense.  For the command-line, these will only transfer text content. With these commands, then, you can pipe or redirect content as you would with any other command-line filter.

An example which would use both these commands; say, you are in your browser and want to copy the URL from your browser and use it in a command on the command-line, after copying the URL from the browser, you could run a command like:

curl `pbpaste` | pbcopy

The clipboard/pasteboard then contains the output of the curl command of the URL, previously held in the clipboard. You can paste the content into a text editor to see the raw output returned by the URL. (For the uninitiated, those single-quotes (`) are backwards single quotes).

Linux

For Linux, install the xclip command:

sudo apt install xclip

Then, define the aliases to mimic the macOS commands:

if type xclip &>/dev/null; then
  alias pbcopy='xclip -sel clip'
  alias pbpaste='xclip -sel clilp -o'
fi

Cygwin

On Windows, I use Cygwin for consistent command line capability with macOS and Linux. Having found pbpaste and pbcopy on macOS, I figured similar functionality in Cygwin; but it works differently. They implement a clipboard device at /dev/clipboard. We can create a couple of aliases to make the device act like the macOS commands:

if [ -e /dev/clipboard ]; then
  alias pbcopy='cat >/dev/clipboard'
  alias pbpaste='cat /dev/clipboard'
fi

With those settings, you can use copy/paste commands in the same fashion as in macOS and write scripts that will work in both environments.

3/25/2023 — This post was originally published Dec 3, 2013 and updated to include the Linux solution.

showStack() {
  local i
  for (( i=1; i < ${#BASH_SOURCE[@]}; i++ )); do
    [ "${FUNCNAME[$i]}" = source ] && echo "  ${BASH_SOURCE[$i]}:${BASH_LINENO[(($i - 1))]}"
  done
}

Each of my startup dot-files echo their name when they start, so their call to showStack might look like:

.bash_profile...
.profile...
  /home/bill/.profile:31
  /home/bill/.bash_profile:28
.bashrc...
  /home/bill/.bashrc:30
  /home/bill/.profile:243
  /home/bill/.bash_profile:28

The explicit output shows that .bash_profile is started, followed by .profile. In .profile, is a call to showStack which displays the script calls: .bash_profile at line 28 invokes .profile, which, at line 31, calls showStack. Later, .bashrc is invoked and it calls showStack at line 30; it was invoked from .profile at its line 243; which was invoked by .bash_profile‘s line 28.

The three Bash variables, BASH_SOURCE, BASH_LINENO, and FUNCNAME, are arrays whose corresponding elements describe the script files, their line numbers, and function names which make up the call-stack. If the invocation is not contained within a function, then the corresponding FUNCNAME element is set to source.

caller Builtin

I was aware of the Bash variables and wanted the exercise of figuring them out; but if I’d queried StackOverflow on the topic, would have revealed other’s similar solutions; notably, one using Bash’s builtin command, caller:

showStack() {
  while caller $i; do
    ((i++))
  done
}

Which, for the same scripts, would output (here, I did not filter for the source entries and includes the function calls):

.bash_profile...
.profile...
31 source /home/bill/.profile
21 _sourceFiles /home/bill/.bash_profile
25 _sourceDotFiles /home/bill/.bash_profile
30 source /home/bill/.bash_profile
.bashrc...
30 source /home/bill/.bashrc
243 source /home/bill/.profile
21 _sourceFiles /home/bill/.bash_profile
25 _sourceDotFiles /home/bill/.bash_profile
30 source /home/bill/.bash_profile

These are well illustrated by @kyb in his utils.bash script:

function stacktrace { 
   local i=1
   while caller $i | read line func file; do 
      echodbg "[$i] $file:$line $func()"
      ((i++))
   done
}
function stacktrace2 {
   local i=${1:-1} size=${#BASH_SOURCE[@]}
   ((i<size)) && echodbg "STACKTRACE"
   for ((; i < size-1; i++)) ;do  ## -1 to exclude main()
      ((frame=${#BASH_SOURCE[@]}-i-2 ))
      echodbg "[$frame] ${BASH_SOURCE[$i]:-}:${BASH_LINENO[$i]} ${FUNCNAME[$i+1]}()"
   done
}

Here’s an example of how you can use this function to parse command-line arguments:

use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();

    // The first argument is always the path to the executable
    let program_name = &args[0];

    // The rest of the arguments are the ones passed by the user
    let user_args = &args[1..];

    println!("Program name: {}", program_name);

    // Print the user-provided arguments
    for arg in user_args {
        println!("User argument: {}", arg);
    }
}

In this example, we use env::args to collect all the command-line arguments into a vector of Strings. We then separate the program name (which is always the first argument) from the user-provided arguments by slicing the vector. Finally, we print out the program name and each of the user-provided arguments.

From here, you can parse the user-provided arguments based on their position or by using a library like clap or structopt to define a more complex set of command-line options.

Can I use std::env::args to handle option switches?

use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();

    let mut verbose = false;
    let mut input_file = String::new();

    for arg in args.iter().skip(1) {
        match arg.as_str() {
            "-v" | "--verbose" => verbose = true,
            file => input_file = String::from(file),
        }
    }

    println!("Using input file: {}", input_file);

    if verbose {
        println!("Verbose mode is enabled");
    }
}

clap and structopt are two popular Rust crates for parsing command-line arguments. Here are some differences between the two:

• clap provides more flexibility and configurability than structopt. It allows you to define complex command-line interfaces with subcommands, argument groups, default values, and more. structopt, on the other hand, is more opinionated and focuses on providing a concise and easy-to-use interface for parsing simple command-line arguments.
• clap has a more traditional Rust API, where you define options and arguments separately and manually parse the command-line arguments. structopt, on the other hand, uses a macro-based approach where you define a struct to represent the command-line options, and the crate generates the parsing code for you.
• structopt has a simpler and more concise syntax than clap. It allows you to define command-line options and arguments using Rust struct field attributes, which makes the code more readable and easier to maintain.
• clap has more features than structopt, such as support for environment variables, YAML configuration files, and more. structopt focuses on providing a minimal and easy-to-use interface, which makes it more suitable for small to medium-sized projects.

When to use clap:

• If you need to define complex command-line interfaces with subcommands, argument groups, default values, and more.
• If you need to integrate your command-line interface with environment variables, YAML configuration files, or other external sources.
• If you prefer a more traditional Rust API where you define options and arguments separately and manually parse the command-line arguments.

When to use structopt:

• If you have simple command-line arguments that can be represented using a Rust struct.
• If you want a concise and easy-to-use syntax for defining command-line options and arguments.
• If you want to minimize the amount of code you write for parsing command-line arguments.

[dependencies]
structopt = "0.3.21"

use structopt::StructOpt;

#[derive(Debug, StructOpt)]
#[structopt(name = "My Rust Program", about = "Does awesome things")]
struct Opt {
    #[structopt(short, long, help = "Sets the level of verbosity")]
    verbose: bool,

    #[structopt(name = "FILE", help = "Sets the input file to use")]
    input_file: String,
}

fn main() {
    let opt = Opt::from_args();

    println!("Using input file: {}", opt.input_file);

    if opt.verbose {
        println!("Verbose mode is enabled");
    }
}

First, add clap to your Cargo.toml file:

[dependencies]
clap = "3.0.0"

Next, use clap to define your command-line options:

use clap::{App, Arg};

fn main() {
    let matches = App::new("My Rust Program")
        .version("1.0")
        .author("Your Name <you@example.com>")
        .about("Does awesome things")
        .arg(
            Arg::new("input")
                .about("Sets the input file to use")
                .value_name("FILE")
                .index(1)
                .required(true),
        )
        .arg(
            Arg::new("verbose")
                .short('v')
                .long("verbose")
                .about("Sets the level of verbosity"),
        )
        .get_matches();

    let input_file = matches.value_of("input").unwrap();
    let is_verbose = matches.is_present("verbose");

    println!("Using input file: {}", input_file);

    if is_verbose {
        println!("Verbose mode is enabled");
    }
}

In this example, we define two command-line options using Arg::new. The first option is a positional argument named input that is required and takes a single value. The second option is a flag named verbose that can be set with either -v or --verbose.

We then use get_matches to parse the command-line arguments and store the results in the matches variable. We can retrieve the values of the input and verbose options using the value_of and is_present methods on the matches object, respectively.

Note that clap provides many more options for defining command-line arguments, such as specifying default values, specifying allowed values, and grouping arguments into subcommands. Check out the clap documentation for more information.

FactoryBot

RSpec is a testing framework for the Ruby programming language, and FactoryBot (formerly known as Factory Girl) is a library for creating test data in Ruby. Together, these tools can be used to write unit-tests for a Ruby application.

In FactoryBot, a factory is a blueprint for creating test data objects. A factory can define various attributes of the objects it creates, such as the object’s type, the values of its attributes, and any associations it has with other objects.

Traits

A trait in FactoryBot is a named group of attributes that can be can be applied to a factory, used to create an object. Traits allow you to define common attribute sets that can be shared across multiple factories or used to override the default values in a factory. Instead of having to specify the same attributes every time you create an instance of a factory, you can use a trait to define those attributes once, and then include the trait in any factory that needs those attributes.

If you have a factory for creating a user object in your application, this factory might have various attributes for the user, such as their name, email address, and password. You can use a trait to group together a set of attributes that are commonly used together.

Here’s an example of how you might use a trait in your factory:

FactoryBot.define do
  factory :user do
    name 'John Doe'
    email 'johndoe@example.com'
    password 'password'

    trait :admin do
      admin true
    end
  end
end

In this example, the :admin trait sets the admin attribute to true for the user object. You can use this trait when creating a user object to specify that the user should be an admin. Here’s an example:

user = FactoryBot.create(:user, :admin)

This will create a new user object with the name, email, password, and admin attributes set. The admin attribute will be true because of the :admin trait.

Here’s an example of how you might use a trait to define a :with_email attribute for a User factory:

# Define the trait
RSpec.define_trait :with_email do
  transient do
    email { "user@example.com" }
  end

  after(:build) do |user, evaluator|
    user.email = evaluator.email
  end
end

# Use the trait in a factory
FactoryBot.define do
  factory :user, traits: [:with_email] do
    # other attributes for the user go here
  end
end

# Create an instance of the factory with the trait
user = create(:user, :with_email)

In this example, the :with_email trait defines an attribute email with a default value of "user@example.com", and an after(:build) hook that sets the user’s email attribute to the value of the email attribute when the factory is built. When you create an instance of the :user factory and include the :with_email trait, the user’s email attribute will be set to the value defined in the trait.

Overall, traits in FactoryBot provide a way to group together commonly used sets of attributes, which can make it easier to create objects in your tests.

Transients

A “transient attribute” is an attribute that is not saved to the database when an object is created. This can be useful when you want to specify certain values for an object when it is created for a test, but you don’t want those values to be persisted in the actual database. …are used only for the duration of a factory’s execution. They can be useful for setting temporary values that are needed for a specific test but are not relevant for the long-term state of the object.

To use a transient attribute in a factory, you can define it using the transient method’s block, in a FactoryBot factory. For example, you might define a :admin trait for a User factory that sets the admin attribute to true and the email attribute to a specific value.

FactoryBot.define do
  factory :user do
    transient do
      admin false
    end

    name 'John Smith'
    email 'john@example.com'
    password 'password'
    is_admin admin
  end
end

In this example, the admin attribute is a transient attribute that is set to false by default. When an instance of the :user factory is created, the is_admin attribute will be set to the value of the admin transient attribute.

Its value can be set using the after(:build) hook, as in:

FactoryBot.define do
  factory :user do
    transient do
      admin false
    end

    after(:build) do |user, evaluator|
      user.admin = evaluator.admin
    end
  end
end

You can then use the transient attribute when creating an object using the factory:

user = FactoryBot.create(:user, admin: true)

This will create a User object with the admin attribute set to true.

after(:build)

after(:build) is a hook that allows you to specify a block of code to be run after an object is built using a factory. The :build symbol refers to the  build method provided by FactoryBot, used to create an instance of a model without saving it to the database. The block passed to after(:build) is executed after the object is built, but before it is returned. This allows you to modify the object or perform other actions on it before it is used in your tests.

Here’s an example to customize the behavior of a factory:

# Define a factory for a User model
FactoryBot.define do
  factory :user do
    # Set some attributes for the user
    name { "John Smith" }
    email { "john@example.com" }
    password { 'password' }

    # Use the after(:build) hook to customize the user
    after(:build) do |user|
      user.name = 'Jane Smith' if user.email == 'jane@example.com'
    end
  end
end

# Now, when you use the factory to build a new user, it will have the
# attributes specified in the factory as well as the password set to "password"
user = build(:user)

The block takes a single parameter, which is the object that has been built by the factory. In this example, the after(:build) block modifies the name attribute of the user object if the email attribute is set to 'jane@example.com'.

sets the password attribute of the user object, being created by the factory, to the value “password”.

You can also pass a symbol representing a method to after(:build) instead of a block, like this:

after(:build, &:set_password)

This will call the set_password method on the object after it has been built by the factory.

You can also define multiple after(:build) blocks in a single factory; each block will be executed in the defined order:

factory :user do
  # define user attributes here

  after(:build) do |user|
    user.password = "password"
  end

  after(:build) do |user|
    user.email = "user@example.com"
  end
end

# create a new user object with the password attribute set to "password" and the email attribute set to "user@example.com"
user = build(:user)

Note that the after(:build) is only run when you use the build method to create an instance of the model. It will not be run when you use the create method, which both builds and saves the model to the database. If you want to customize the behavior of a factory when it is used with create, you can use the after(:create) hook instead.

• Maybe, simply start with the HTML5 Security Cheat Sheet which is what this post set out to do
• Protect <a href="..." target="_blank"> vulnerability to hacked target page by including rel="noopener noreferrer". See Target=”_blank” – the most underestimated vulnerability ever

Staying away from programming for too long, things change faster than I’d ever expected. Even with a strong foundation, when things move ahead so quickly, too many things change and it isn’t as easy to hop back on the train, as I would have thought. Today, I am trying to catch up with technology train that is web development. How did I become so disconnected?

1. My initial disinterest was that I wasn’t very interested. With web “development,” writing text-markup was not “programming” (it still isn’t). It has taken a couple of decades for web-programming to require the skills of true developers. But it is here, today. In the mean time, I’d left it behind and as a result, it left me behind.
2. When I recently started looking at getting into web-development, the landscape was changing and evolving so quickly that it was hard to pin down which of the dozens of technologies to focus on. If I’d picked Perl, ColdFusion, Ruby, AngularJS, etc.… ”the list is endless” I’d be an expert in another obsolete technology. However, avoiding a pick, meant that I did not get my hands dirty and did not stay keen about the evolving landscape of web-development.
3. What I never expected is that it isn’t just the languages and frameworks which have changed, it is also the technology infrastructure which has changed and, notably, this has changed development workflow.

The result is that, not only do I need to learn new languages and their nuances, I even need to learn a new workflow, a new way of doing programming. While I am not starting from scratch, a lot of my prior “expertise” is not directly applicable; so it feels like starting from scratch.

I could just stick to the old technologies that I am still expert at, but that isn’t cutting edge. Still I could do that. Then I wouldn’t have anything to be stressed about. And, that wouldn’t be so bad, now would it?

I should mention that I had a specific goal to better encapsulate data within the component. While I could pass in all the needed data as properties, that would require the surrounding component know what to pass and how to get it. That shouldn’t necessarily be necessary; the component knows what it needs and how to retrieve it.

For example, say you have a component which accepts a phone number and displays the phone number and the state that it’s from. Certainly, you could write a simple component that accepts both pieces of information as properties.

<ShowPhoneLocation number="+12065551212" city="Seattle" />

Which might be implemented as:

class ShowPhoneLocation extends React.Component {
  render() {
    return (
      <div>{this.props.number} is from {this.props.city}</div>
    )
  } // render()
} // class ShowPhoneLocation

But, since the component should be able to infer the state from the phone number (by its area code), it shouldn’t be incumbent on its container to know what it is.

class ShowPhoneLocation extends React.Component {
  static getDerivedStateFromProps(nextProps, prevState) {
    let location = getCityFromPhone(nextProps.number)
    return {
      city: location
    }
  }
  render() {
    return (
      <div>{this.props.number} is from {this.state.city}</div>
    )
  } // render()
} // class ShowPhoneLocation

That’s all well and good, but what if getCityFromPhone() has to call a web service? We don’t want getDerivedStateFromProps() to stall, waiting for a response. However, it is static and does not have a this reference to the object for which it is returning state; so an asynchronous fetch doesn’t know what object’s state to set. Instead, don’t wait for the result to save in the state, save the request’s Promise in the state and update the state, once the promise resolves.

function getCityFromPhone(number) {
  return fetch('http://saas.com/get/'+number+'/city') // Returns fetch promise
}
class ShowPhoneLocation extends React.Component {
  static getDerivedStateFromProps(nextProps, prevState) {
    let location = getCityFromPhone(nextProps.number)
    return {
      city: location
    }
  }
  componentDidUpdate() {
    let location = this.state.city
    if (location instanceof Promise) {
      this.setState({ city: '...waiting...' })
      location.then(city => this.setState({ city: city }) )
        .catch(() => this.setState({ city: 'not found' }) )
    }
  }
  render() {
    return (
      <div>
        {this.props.number} is from {this.state.city instanceof Promise
         ? '...'
        : this.state.city}</div>
    )
  } // render()
} // class ShowPhoneLocation

In componentDidUpdate() you can define the completion handlers to set the object’s state, base on the returned information from the service.

It is a common pattern to perform a fetch in componentDidMount(). The problem is that there may not be enough information to perform the fetch, that early, or the information for the fetch changes after the component has been mounted.

I am going to miss componentWillReceiveProps()… without it, things become a bit more convoluted but it’s going the way of the Dodo.