DEV Community: kohii

Writing Brain-Friendly Code: Principles of Extraction and Abstraction

kohii — Tue, 17 Feb 2026 13:00:00 +0000

AI-powered agentic coding has become the norm. It's not much of an exaggeration to say that development productivity now depends on how fully you can put AI to work.

It's easy to get caught up in AI coding techniques and tooling. But whether your codebase itself is ready for AI is a more fundamental question. What does an AI-ready codebase look like? Low cognitive load. Easy to change. Easy to test. Well-documented. In short, just good software design.

How do you structure code so that treating each piece as a black box doesn't cause things to break?
How do you get AI to write code that's easy for reviewers to understand at a glance?

Building a codebase like this requires you to make sound design decisions yourself and to give AI clear direction. I wrote about these design principles in Japanese two years ago. I think they might apply even more now, so I translated the article into English.

Original article (Japanese)

My code has a decent reputation for readability, or so I like to think. Here are the personal principles I follow to write code that's easy for the reader's brain to absorb.

About Me

Software engineer at a healthcare startup. I also build side projects.
Social accounts:
- kohii on GitHub
- @kohii00 on X
Side project:
- SmoothCSV: The ultimate CSV editor you've been waiting for. Think "VS Code for CSV".

The Act of Extracting Functions and Classes

Why do we split code?

We split code because the overall scale and complexity of a codebase far exceeds the limits of human cognitive capacity. The fundamental strategy for handling something massive and complex is divide and conquer.

There are various ways to split code: functions, classes, components, packages, modules, microservices, etc. These are all essentially the same: mechanisms to hide details and procedures, presenting them in a different way.

Extracting a function or class shouldn't just be about deduplication or moving code around. It should be an exercise in creating understandable abstractions.

Code design is much like UI design

In UI design, we hide technical complexities that the user doesn't need to know. We present them as well-thought-out concepts that can be understood and operated intuitively.

Designing functions, classes, components, and modules is the same. It's about deciding what details to push behind which interface.

The fractal structure of abstraction

A car provides interfaces like the gas pedal and the steering wheel, which hide the internal machinery and give the driver a way to move the vehicle. From the driver's perspective, operating these controls feels like the objective itself. But from a higher-level perspective ("getting from point A to point B"), those operations are merely the means.

The systems we develop are also a means to the greater goal of providing value to users. Building a system means creating multiple layers of this Goal (Interface) → Means (Implementation) structure within it.

How to Extract Functions and Classes in a Brain-Friendly Way

In this section, I'll use "functions and classes" as a general term for all units of abstraction, including components, modules, and so on.

If they need to read the implementation, you've lost

A well-designed API or library lets you understand what it does and how to use it just from its interface. This should be the ideal when you create your own functions and classes.

By extracting code and pushing it behind an interface, you are creating parts where the reader can say, "I don't need to read any further" or "I don't need to think about what happens past this point." This reduces cognitive load.

If a reader can't understand the code without diving into the implementation, then that extraction has failed.

// NG: You have to look inside to see what kind of filtering is happening
function filterUsers(users: User[]): User[]

// OK: The behavior can be inferred from the function name and signature
function filterActiveUsers(users: User[]): User[]

If you abstract, hide the details completely

In nominal typing languages like Kotlin or C#, we often use value objects to wrap primitive values instead of using them directly.

For example, imagine an Email value object. Suppose we want to extract the domain name from this email.

class Email(val value: String)

val email: Email = ...
val domain = email.value.substringAfter("@") // Extracting the domain

This might look fine at first glance, but it directly uses the internal value that the value object is supposed to hide. It's like a driver reaching into the car to manually manipulate the engine instead of using the pedals.

When you abstract something, the consumer should interact with the abstraction itself.

class Email(val value: String) {
  fun domain(): String {
    return this.value.substringAfter("@")
  }
}

val email: Email = ...
val domain = email.domain()

Here's another example. Two different interfaces for a React component that displays a notification:

// A
<Alert onClickDismissButton={...}>Some notification</Alert>

// B
<Alert onDismiss={...}>Some notification</Alert>

From the property name onClickDismissButton, Option A reveals that the Alert component has a button to close the notification and that clicking it triggers the callback. These are internal details the consumer doesn't need to know.

Option B hides these details. It leaves it up to the Alert component to decide how to handle the dismissal or whether to include a button at all. You could change it to trigger onDismiss via a keyboard shortcut without affecting the consumer.

Exposing details makes your code fragile to changes and undermines the stability of the interface.

Let the function or class define its own interface

There are two ways to think about the relationship between a function and its caller:

A. The signature is determined by the caller's needs.
B. The function defines its own appropriate signature, and the caller adapts to it.

With Option A, the function must fulfill its own responsibility while also catering to the caller's circumstances. This makes the Single Responsibility Principle hard to achieve. Option B is generally simpler and easier to understand. (For private functions, I often choose A for convenience. The further the distance from the caller, the more you should lean toward B.)

The bad example

Below is a use case for searching Pokémon in your possession, written in TypeScript:

type SearchMyPokemonRequest = {
  query: string;             // Search string
  limit: number;             // Number of items to fetch
  type: PokemonType | null;  // Pokémon type
  outputFormat: 'json' | 'xml' | 'csv'; // Output format
}

// Use Case: Search my Pokémon (excluding those obtained via trade)
async function searchMyPokemons(
  request: SearchMyPokemonRequest,
  authContext: AuthContext, // Auth info (framework-dependent)
) {
  const pokemons = await findPokemons(request, authContext);
  return outputPokemons(pokemons, request);
}

// Data Access Layer
function findPokemons(
  input: SearchMyPokemonRequest,
  authContext: AuthContext,
): Promise<Pokemon[]> {
  return prisma.pokemon.findMany({
    where: {
      name: { contains: input.query },
      type: input.type,
      ownerUserId: authContext.userId,    // Owned by me
      capturedUserId: authContext.userId,  // Caught by me (= excludes trades)
    },
    take: input.limit,
  })
}

There are several issues with this findPokemons function:

It knows too much: It receives the entire SearchMyPokemonRequest and the full AuthContext (even though it only needs userId). This stamp coupling makes the function's responsibility ambiguous.
It requires use-case knowledge to understand: The logic for "excluding traded Pokémon" is use-case-specific. The fact that query means a partial name match is also use-case-specific (or even UI-form-specific). These behaviors are hard to infer from the signature alone.

The improved example

The function defines the parameters it needs, regardless of the caller's convenience:

// Use Case: Search my Pokémon (excluding those obtained via trade)
async function searchMyPokemons(
  request: SearchMyPokemonsRequest,
  authContext: AuthContext,
) {
  // Call findPokemons according to its own signature.
  // The behavior is obvious from the signature, so no need to look inside.
  const pokemons = await findPokemons({
    nameContains: request.query,
    type: request.type,
    ownerUserId: authContext.userId,
    capturedUserId: authContext.userId,
  }, request.limit);
  return outputPokemons(pokemons, request);
}

// Data Access Layer
function findPokemons(
  // Define parameters based on the responsibility of "fetching Pokémon matching criteria"
  criteria: {
    nameContains?: string;
    type?: PokemonType | null;
    ownerUserId?: UserId;
    capturedUserId?: UserId;
  },
  limit?: number,
): Promise<Pokemon[]> {
  ...
}

If you only think about the caller's convenience, it's tempting to pass existing variables directly to child functions. But this causes deeper layers of code to depend on unnecessary context, making the code harder to understand.

Minimize the context being pulled in

Functions and classes exist within a certain context:

The execution environment, infrastructure, or framework.
The caller, the caller's caller, and so on.
A specific business flow or use case.

Having a function define its own signature, as discussed above, is essentially stripping away the caller's context.

Functions and classes with minimal context have many advantages:

Self-contained understanding: Fewer context dependencies mean less extra information to hold in your head while reading.
High reuse value: Less context makes code more generic and easier to reuse or relocate.
Stability: Minimal context means fewer reasons for the code to change.
Ease of testing: Stable interfaces and minimal inputs make unit tests straightforward and test data easy to prepare.
AI-friendly: Less context means AI agents can generate, review, and refactor each piece more accurately. As agentic coding becomes the norm, this is becoming increasingly important.

Mind the overhead of extraction

Look at these two TypeScript snippets. Which is easier to read?

function dumpActiveUsers() {
  const users = findUsers();
  const activeUsers = filterActiveUsers(users);
  console.log(activeUsers);
}

function filterActiveUsers(users: User[]) {
  return users.filter((user) => user.isActive); // This function hides almost nothing
}

function dumpActiveUsers() {
  const users = findUsers();
  const activeUsers = users.filter((user) => user.isActive); // Declarative enough. Directly expresses intent.
  console.log(activeUsers);
}

I find the latter more readable. Extracting functions (or classes, or components) comes with overhead:

Increase in code volume (boilerplate to define the function).
Management burden for the extracted function.
The cognitive cost of jumping to the definition.

If the amount of information hidden by a function is negligible, it's often better not to extract it at all.

Write slightly generous comments

Some argue that good design doesn't need comments. I recommend erring on the side of "slightly generous" when in doubt, especially with documentation comments like JSDoc or JavaDoc.

Interfaces have limits. Sometimes a signature simply can't express everything.
Skill and mental models vary. People have different ideas of what "good design" looks like. The metaphors or vocabulary that click for one person might not work for another.
Save the reader's time. Good design makes meaning guessable, but guessing still takes effort. If you can reduce the reader's burden, do it.
Record the "why." Sometimes you write imperfect or tricky logic for specific reasons. Comments convey your design decisions to others and your future self.
Discover flaws. If you find a function hard to explain in a comment, it may be a sign that the design itself needs work.

Think twice

To judge whether an interface is appropriate, toggle between two perspectives:

From the function's perspective:
- Is the context minimized?
- What should it know, and what should it not know, to fulfill its responsibility?
From the caller's perspective:
- Can I guess the meaning just from the interface?
- Would I still think so if someone else wrote this?
- Is there room for misinterpretation or misuse?

Good design is often discovered gradually as you go. When unsure, start with a simple, naive approach.

Where to invest effort

Designing everything to perfection is exhausting. Pick your battles.

Invest effort when:

The code is used in many places (including tests).
The code is called across different services, teams, layers, or features.
The code is expected to live long or belongs to the core domain.

Closing Thoughts

There is no single correct method for every situation. The best way to learn is to try, fail, and iterate. I hope these ideas help you in that process.

(Please try SmoothCSV if you ever need to work with CSV files)
(Cover art by my wife, a painter. It is unrelated to the text.)

The Technology Behind SmoothCSV - The Ultimate CSV Editor

kohii — Mon, 30 Jun 2025 22:07:04 +0000

My self-developed CSV editor SmoothCSV (v3) has become Generally Available, so I'd like to share some technical insights and innovations behind it.

Also launching on Product Hunt on July 1st (PT) 🚀

producthunt.com

About Me

I work as a software engineer at a healthcare startup while doing personal development projects.

@kohii00 on X (en: @kohiidev)
kohii on GitHub

About SmoothCSV

SmoothCSV is a CSV editor for macOS and Windows. (Linux coming soon)
I've been developing the original SmoothCSV for 15 years, and started working on v3 last year.

SmoothCSV - The ultimate CSV editor for macOS & Windows

SmoothCSV is the ultimate CSV editor for macOS & Windows. It's fast, easy to use, and packed with powerful features.

smoothcsv.com

Features:

Excel-like operation for intuitive use
Equipped with basic to advanced tools necessary for handling CSV
Supports various formats and character encodings. Can handle CSVs with different column counts
Fast! Handles large files smoothly

Technical Elements

Main Technology Stack

Desktop App
- Framework: Tauri
- Backend: Rust
- Frontend: TypeScript + React + Vite + pnpm
- Styling: Tailwind CSS
- State Management: MobX
- Testing: Node.js built-in test runner
- Formatter, Linter: Biome
Website (kohii/smoothcsv-website)
- Static Site Generator: Astro
- Hosting: Cloudflare
Distribution, Communication (kohii/smoothcsv3)
- GitHub Issues, Releases

Technical Architecture

Being a desktop application, the technical architecture is quite simple. There's no external communication except for checking and downloading updates.

1. Technology for Building Complex Desktop Applications

SmoothCSV aims to be a feature-rich yet simple and highly extensible application.

Tauri is Great

Tauri is a desktop application framework that serves as an alternative to Electron. (From Tauri v2, it also supports mobile apps.)

While Electron uses Node.js for the backend and Chromium for the frontend, Tauri uses Rust for the backend and the OS's bundled web renderer for the frontend. This results in smaller distribution size and lower memory usage.

Tauri comes with comprehensive APIs and plugins that make it easy to implement desired features.

Separation of Concerns through Package Extraction

Managing as a monorepo with pnpm workspaces + Turborepo.

(root)
├─ apps
│  └─ desktop             # SmoothCSV desktop app main body (depends on packages/*)
└─ pakages
   ├─ csv                 # CSV parsing and stringification
   ├─ grid-editor         # React component library for tabular editor
   ├─ result              # Result type TypeScript implementation
   ├─ utils               # General utilities
   ├─ js-sql              # TypeScript SQL parser and evaluation engine
   ├─ framework           # General desktop app foundation. Command system, key bindings, settings, etc.
   ├─ context-expression  # VSCode-compatible conditional expression parser
   └─ l10n                # VSCode-compatible localization API

Under packages, independent concerns that don't depend on SmoothCSV-specific context are extracted as libraries. This makes individual concerns easier to handle while reducing the complexity of the desktop main body.
Within desktop, code is also structured by independent concerns as much as possible. (package by feature, etc.)

Command-Centric System

In SmoothCSV, operations that users can execute on the application are defined as commands. While this was similar in the previous version of SmoothCSV, this time it's built as an API similar to VS Code.

Commands consist of handler functions and metadata (ID, title, availability conditions, etc.).

Image of a command to close a tab:

aCommand = {
  command: "view.closeEditor",
  title: "Close Editor",
  category: "View",
  handler: async () => {
    // Processing when command is invoked
  }
}

Commands are mapped to UI elements such as keyboard shortcuts, context menus, and buttons, and are triggered. You can also search for and execute any command from the "Command Palette".

Example of assigning a keyboard shortcut to the close tab command:

{
  "keybindings": [{
    "command": "view.closeEditor",
    "key": "ctrl+w",
    "mac": "cmd+w"
  }]
}

Example of executing from the Command Palette:

For applications with a certain level of complexity, having command-centric extension points makes it easier to add features.

System for Declaring Command and Menu Enabling Conditions

This is also a system mimicking VS Code's when clause contexts.

Each command, menu, and key binding has situations where it cannot be used.
For example, the command to start cell editing requires the Grid editor to have focus and not be in cell editing mode.
SmoothCSV provides a notation to declaratively express such conditions.

{
  "command": "cellEditor.startEditingCell", // Command to start cell editing
  "enablement": "gridEditorCellFocus && inReadyMode", // Command is available when Grid editor is focused and not in cell editing mode
  ...
}

While implementing parsing is somewhat difficult, having such a system allows requirements to be configured and facilitates future extensions and customizations.

Providing Extension APIs from the Initial Stage

As with commands, extension APIs are created first rather than immediately building individual features.

While this is partly for users to create extensions in the future, the main purpose is to make standard features easier to build. Having stable APIs makes development easier, and several features are actually built as system extensions.

Things built as extensions within SmoothCSV:

Advantages

Separation of concerns
- Concerns are contained within each extension's directory
- Organized and easy to read
Easy to have AI create
- Even if design and code structure are somewhat rough, it doesn't matter much as it's contained within the extension
- If you don't like it anymore, you can just throw away the entire extension and rebuild
Lazy loading
- Code loading is deferred until extension features are actually used → Performance improvement

However, this approach may work well only in limited situations. It's likely to waste time as it's difficult to see what APIs are needed at the initial stage. (SmoothCSV was relatively predictable as it was a replacement development)

Adopting MobX for State Management

For frontend state management, after trying various options like a self-made simple Store → Zustand → self-made again... I settled on MobX.
In early development, I was particular about handling state as plain objects, but this resulted in more work to implement each use case and difficulty managing computed values.

These problems were well resolved by using MobX.
MobX manages state with class-based objects and reactively reflects them in React components.

// MobX object holding state
class FindWidget { // Model governing the widget for search/replace
  @observable mode: "find" | "replace" | "hidden";　// @observable makes property changes observable
  @observable.ref findParams: FindParams;　// @observable.ref observes only reference changes. (FindParams is readonly object, so it's replaced as a whole when updated)
  @observable.ref replaceParams: ReplaceParams;

  @computed // Derived property (value is cached)
  get isVisible() { return this.mode !== "hidden" }

  @action.bound // Add @action to change state
  hide() { this.mode = "hidden" }
}

// Using from React component (wrapped with observer to render reactively to state changes)
const FindWidgetComponent = observer(() => {
  const model: FindWidget = ...
  if (!model.isVisible) return null;
  return <FindWidgetForm findParams={model.findParams} onHide={model.hide} />; // Call pure component
});

However, I try to minimize the scope of MobX dependencies.

Container/Presentational Pattern-like
- Create core parts as pure and controllable function components (Presenter)
- Only top-level components (Container) depend on MobX and map from MobX objects to Presenter component props
Important/complex logic is also created as independent pure functions
- Creating as methods of MobX objects creates unnecessary property dependencies (most functions don't need the entire object)

Components and functions without unnecessary dependencies are highly stable and become assets.
SmoothCSV is particular about building up these assets.

Auto-update

SmoothCSV has a mechanism to automatically detect when a new version is released, notify users, and allow them to download and install it directly.
This mechanism is crucial for rapidly adding features and fixing bugs.

Tauri has an updater plugin that makes it easy to implement these processes.
SmoothCSV uploads JSON with update information, distribution files, and signatures to GitHub Releases, and checks for new versions at application startup.

2. Technology for Building Tabular Editors

SmoothCSV has an Excel-like tabular editor.
The core React component is built as a library independent from SmoothCSV.

Cell Rendering

CSV files can contain large amounts of data, such as millions of rows.
Rendering all cells directly is impractical, so SmoothCSV uses virtual scrolling. However, there are actually limitations to regular virtual scrolling, so I've built the scrolling mechanism from scratch.
Details here:

kohii

Oct 8 '24

How to Implement Virtual Scrolling Beyond the Browser's Limit

Comments

6 min read

Cell Editing

In Excel and Google Sheets, typing any character immediately enters cell editing mode.

While this behavior is common in many tabular editors, few work correctly with Japanese input.

Common Implementation

Monitor keydown to start cell editing
Set the entered character as the initial value of the cell editor and display it

This causes "a" to be entered when trying to input "あ" in Japanese.

SmoothCSV's Implementation

Place an invisible textarea and keep it focused
When any character is entered, display this textarea as the cell editor

Dynamically Expanding/Contracting Cell Editor Based on Input

When text is entered into the cell editor, its width and height change according to the content.
The mechanism involves placing an invisible span with exactly the same style as the textarea, copying the content entered in the textarea into it. The width and height of this span are obtained and set as the style of the textarea.

3. Technology for Building SQL Integration Features

SmoothCSV has two features that utilize SQL.

Filter

A feature that displays only rows matching specified conditions and hides others. While Excel and Google Sheets also have filter features, SmoothCSV allows specifying conditions with SQL WHERE clauses for more flexible filtering.

The main purpose is to express filter conditions as strings, borrowing the widely familiar SQL notation for this.

Filter conditions being strings makes them easy to save and reuse with copy & paste
Easy to have AI generate
Can be handled as structured data when parsed

Also, there's a feature to edit filter conditions with a GUI, making it easy for non-technical users to use.

Inside, it converts SQL ↔ AST ↔ GUI data model.

SQL Console

The SQL Console is a feature that issues SQL SELECT statements against files opened in SmoothCSV or local CSV files.
Using notation like "@file:/Path/To/File.csv", you can treat CSV files as tables.

Mechanism

Uses embedded SQLite. When SQL is entered and executed, table notation is extracted from the SQL, corresponding temporary tables are created, data is loaded, and then the actual SQL is executed.

CREATE TEMPORARY TABLE "@file:/Path/To/File.csv" ( -- SQLite allows any table name when enclosed in ""
  /* columns */
)

Conclusion

Thank you for reading to the end!
There's so much I wanted to write about that the explanations became brief, so if you have questions about how something works, please feel free to ask.

If you have questions, requests, or feedback, please let me know through comments or GitHub Issues.

Upvotes and comments on Product Hunt would also be encouraging 🙏

producthunt.com

Bonus

Your support for development would be appreciated.

kohii is SmoothCSV, a powerful and intuitive tool for editing CSV files - Buymeacoffee

Hi there👋I'm kohii — full-stack developer, architect, designer, and indie hacker. I work at a medical startup while developing my own products in my spare time.Right now, I’m building SmoothCSV (v3),

buymeacoffee.com

How to Implement Virtual Scrolling Beyond the Browser's Limit

kohii — Tue, 08 Oct 2024 09:19:10 +0000

Introduction

I am currently developing a CSV editor called SmoothCSV. It uses the framework Tauri, and for the renderer, I employ web technologies (React + TypeScript).

CSV editors need to display a large number of rows and cells. In web technologies, virtual scrolling is the standard approach for such scenarios. SmoothCSV also utilized virtual scrolling, but I encountered a problem where extremely large datasets, such as those with millions of rows, could not be fully displayed due to the limitations of virtual scrolling.

In this article, I will introduce the basics of virtual scrolling and explain how I overcame its limitations.

Why Do We Need Virtual Scrolling?

Ordinary Scrolling

When displaying lists or tables with a very large number of items in a browser, a naive implementation will suffer performance degradation as the number of items increases, eventually causing the browser to freeze. This is because the browser constructs and renders the DOM tree for all items, including those outside the viewport.

Virtual Scrolling as a Solution

To solve this problem, virtual scrolling is often used. Virtual scrolling is a technique where only the items visible based on the scroll position are dynamically generated using JavaScript, thereby reducing the load on the browser.

The visible area is called the viewport, and the content outside the viewport is called the buffer. To enable proper scrolling in the browser, dummy elements (spacers) are placed in the buffer areas to maintain the height of the content.

(Alternatively, you can specify the height of the content container and position the displayed items using position: absolute.)

How to Implement Virtual Scrolling

There are many libraries available to easily implement virtual scrolling, and usually, you would use these. In React, the following are well-known:

I personally prefer using TanStack Virtual, which also supports Vue, Svelte, Solid, Lit, and Angular besides React.

The Limits of Virtual Scrolling

It's not widely known, but there is an upper limit to the width and height of elements that can be displayed in a browser. The values I measured are as follows:

Safari: 33,554,428px
Chromium: 16,777,216px

Elements with height or width larger than this will be truncated to the maximum value. (Properties like top, left, margin, and padding also have such upper limits.)

<!-- Example in Safari -->
<!-- Truncated to 33,554,428px -->
<div style="height: 9999999999999px;"></div>

<!-- Same even without directly specifying the size -->
<!-- Should total 40,000,000px, but truncated to 33,554,428px -->
<div>
  <div style="height: 20000000px"></div>
  <div style="height: 20000000px"></div>
</div>

Virtual scrolling is also affected by this limitation. If the height of the scrollable content (i.e., the total height of all items) exceeds this upper limit, you cannot scroll to the end even with virtual scrolling.

In my CSV editor, since the height per row is 22px, the limit is reached at around 1,525,200 rows on macOS (Safari), resulting in the inability to display rows beyond that point.

While this number of rows might not be a common consideration, CSV files can have a very large number of rows. Accepting this limitation would diminish the value of a CSV editor.

Strategies to Overcome the Limits

Virtual scrolling relies on the browser for the scrolling mechanism itself, so the height of the scrollable content, including the buffer, must be the same as the actual total height of all rows. In other words, as long as we depend on the browser's scrolling functionality, we are bound by this limitation.

So, let's create our own scrolling mechanism!

(it might even be better to render using canvas.)

Implementing Beyond the Limits

Let's try implementing this in React.

1. Creating a Scrollbar

First, we'll create a scrollbar by combining div elements. Generally, the rail of the scrollbar is called the Track, and the thumb is called the Thumb.

The ScrollBar component receives properties such as the viewport height (viewportSize), the height of the content to be scrolled (contentSize), and the current scroll position (scrollPosition), and renders a custom scrollbar. It notifies the result of user interactions via a callback (onScroll).

The implementation is roughly as follows. It is a stateless, controlled component.

export type ScrollBarProps = {
  viewportSize: number; // Size of the viewport
  contentSize: number; // Total size of the content
  scrollPosition: number; // Scroll position
  onScroll?: (scrollPosition: number) => void; // Callback when scroll position changes
};

export function ScrollBar({
  contentSize,
  viewportSize,
  scrollPosition,
  onScroll,
}: ScrollBarProps) {
  // Calculate the size and position of the scrollbar from contentSize, viewportSize, and scrollPosition
  const scrollRatio = viewportSize / contentSize;
  const thumbSize = Math.max(
    16, // Minimum size of the thumb (to prevent it from becoming too small)
    scrollRatio * viewportSize
  );
  const maxScrollPosition = contentSize - viewportSize;
  const thumbPosition =
    (scrollPosition / maxScrollPosition) * (viewportSize - thumbSize);

  // Do not display the scrollbar if the content fits within the viewport
  const scrollBarVisible = contentSize > viewportSize;

  // Convert the thumb position back to the actual scroll position
  const translateToScrollPosition = (thumbPosition: number) => {
    const newPosition =
      (thumbPosition / (viewportSize - thumbSize)) * maxScrollPosition;
    return Math.min(maxScrollPosition, Math.max(0, newPosition));
  };

  // Handler for when the thumb is grabbed and dragged
  const handleMouseDownOnThumb = (event: React.MouseEvent) => {
    if (!scrollBarVisible) return;
    event.preventDefault();
    event.stopPropagation();

    const startMousePosition = event.clientY;
    const startThumbPosition = thumbPosition;

    // Handler for mouse movement while holding down the button
    // (Register the event on the document to capture movement anywhere)
    const handleMouseMove = (event: MouseEvent) => {
      const delta = event.clientY - startMousePosition;
      onScroll?.(translateToScrollPosition(startThumbPosition + delta));
    };

    const handleMouseUp = () => {
      document.removeEventListener('mousemove', handleMouseMove);
      document.removeEventListener('mouseup', handleMouseUp);
    };
    document.addEventListener('mousemove', handleMouseMove);
    document.addEventListener('mouseup', handleMouseUp);
  };

  const handleMouseDownOnTrack = (event: React.MouseEvent) => {
    // Handler for when the track outside the thumb is clicked
    // Option 1: Move the thumb to the clicked position
    // Option 2: Move one page in the clicked direction
  };

  return (
    <div
      style={{
        position: 'relative',
        height: viewportSize,
        width: 14,
      }}
      onMouseDown={handleMouseDownOnTrack}
    >
      {scrollBarVisible && (
        <div
          onMouseDown={handleMouseDownOnThumb}
          style={{
            position: 'absolute',
            top: thumbPosition,
            height: thumbSize,
            width: 8,
            borderRadius: 8,
            margin: '0 3px',
            background: 'rgba(0, 0, 0, 0.5)',
          }}
        />
      )}
    </div>
  );
}

Note that you need to handle more aspects to consider accessibility and behavior on mobile devices.

2. Creating a Scroll Pane

Next, we'll create a component that provides state management for the scrollbar and a viewport that displays content synchronized with it.
(This component provides only the scrolling mechanism, and the content to be rendered based on the scroll position is received via children.)

import type React from 'react';
import { useState } from 'react';
import { ScrollBar } from './ScrollBar';

export type ScrollPaneProps = {
  contentSize: number;
  viewportSize: number;
  // Receives a function as a child that returns content to display based on the scroll position
  // (Function as a Child (FaCC) pattern)
  children: (scrollPosition: number) => React.ReactNode;
};

export function ScrollPane({
  children,
  contentSize,
  viewportSize,
}: ScrollPaneProps) {
  const [scrollPosition, setScrollPosition] = useState(0);

  const handleWheel = (event: React.WheelEvent) => {
    // Handler for scrolling with mouse wheel
    setScrollPosition((prev) => {
      const newScrollPosition = prev + event.deltaY;
      return Math.max(
        0,
        Math.min(contentSize - viewportSize, newScrollPosition)
      );
    });
  };

  return (
    <div style={{ display: 'flex', height: viewportSize }} onWheel={handleWheel}>
      {/* Viewport */}
      <div style={{ flex: 1, position: 'relative', overflow: 'hidden' }}>
        {children(scrollPosition)}
      </div>
      <ScrollBar
        contentSize={contentSize}
        viewportSize={viewportSize}
        scrollPosition={scrollPosition}
        onScroll={setScrollPosition}
      />
    </div>
  );
}

Using this component looks like this; you pass the content you want to display in the ScrollPane as a function.

// Here, we're simply displaying the scroll position
export default function App() {
  return (
    <ScrollPane
      contentSize={1000}
      viewportSize={300}
      style={{ border: '1px solid #ddd' }}
    >
      {(scrollPosition) => <div>scrollPosition: {scrollPosition}</div>}
    </ScrollPane>
  );
}

3. Rendering the Content

Finally, we render the content we want to display based on the scroll position. Here, we'll show an example of displaying a list of items with uniform height.

const ITEM_HEIGHT = 30;

// Generate a list of 3 million items
const items = Array.from({ length: 3000000 }, (_, i) => `Item ${i}`);

// 3 million * 30px = 90,000,000px (> browser limit)
const totalHeight = ITEM_HEIGHT * items.length;
const viewportSize = 300;

export default function App() {
  return (
    <ScrollPane contentSize={totalHeight} viewportSize={viewportSize}>
      {(scrollPosition) => {
        // Calculate the items to display within the viewport
        const startIndex = Math.floor(scrollPosition / ITEM_HEIGHT);
        const endIndex = Math.min(
          Math.ceil((scrollPosition + viewportSize) / ITEM_HEIGHT) + 1,
          items.length
        );
        const visibleItems = items.slice(startIndex, endIndex);

        // Logical position of the first visible item
        const startPosition = startIndex * ITEM_HEIGHT;

        return (
          <div
            style={{
              position: 'absolute',
              top: startPosition - scrollPosition, // Distance from the top of the viewport
            }}
          >
            {visibleItems.map((item) => (
              <div key={item} style={{ height: ITEM_HEIGHT }}>
                {item}
              </div>
            ))}
          </div>
        );
      }}
    </ScrollPane>
  );
}

And with that, we're done! 🎉

We adjust the display position of the items by specifying the distance from the top of the viewport using top. For items towards the end, startPosition becomes very large, but since scrollPosition is also large, the value passed to top remains within a practical range.

Here's a cleaner version of the completed code (using TailwindCSS):

https://github.com/kohii/react-custom-scroll-example

Conclusion

Thank you for reading to the end 🙇‍♂️

Please give SmoothCSV a try if you're interested.

https://smoothcsv.com/
https://github.com/kohii/smoothcsv3

The Technology Behind “Moyuk”: Create, Run and Share Tools with TypeScript on Your Browser

kohii — Mon, 10 Apr 2023 11:38:27 +0000

After over a year of development, I launched my personal project, Moyuk, on Product Hunt. In this post, I'll share some technical insights and knowledges about the service.

What I Created

Moyuk

moyukapp.com

You can check out the Product Hunt launch here 🚀:

Brief Overview

Simplest way to create and share your custom tools

In short, Moyuk is a platform that turns functions written in TypeScript into web applications (or "Apps") that can be executed, managed, and shared directly from your browser.

Please check out the link below for more information:

Moyuk: Create, Run, and Share Tools on Your Browser | Medium

Kohei Ishikawa ・ Apr 10, 2023 ・
Medium

Overview of Technical Elements

In addition to the common application components (such as data input/output and UI rendering), Moyuk has several distinctive features:

Components that analyze and transpile user-written TypeScript
A sandboxed JavaScript execution environment for running transpiled code

These elements are all written in TypeScript and organized as a monorepo.

Main Technology Stack

Application
- TypeScript
- React
- Next.js (Application framework)
- MUI (UI library)
- tRPC (Frontend-backend communication)
- Prisma (ORM)
Infrastructure
- Vercel
- Supabase (DB, authentication, storage)
- Cloudflare (Workers, Pages)
Other
- Docusaurus (Documentation)
- Turborepo (Monorepo)

Configuration

The core application is built on Next.js
- Deployed on Vercel, with Supabase used for DB, authentication, and storage
A sandboxed JavaScript execution environment runs within the browser to execute user-written code
- Content for the sandbox is served from Cloudflare

Moyuk as a General Application

Moyuk is built on Next.js and deployed on Vercel.

Features Directory

One of the distinctive aspects of the project is the adoption of the features directory, inspired by Bulletproof React. I personally prefer organizing components with high functional cohesion close together, which is why I chose this structure. I try not to write too much logic inside the pages directory of Next.js and instead just combine and use components exported from features.

State Management

After considering various options, I decided not to use a library for global state management.

Initially, I used zustand as a lightweight state management library, but eventually replaced it with React's Context, which was deemed sufficient. This decision was based on a policy of minimizing global state, which has not caused much pain.

Generally, the React Query client manages data fetched from the server.
Other data states are handled within appropriate components or hooks.

Backend

The database is Supabase, with Prisma as the ORM, and tRPC for frontend-backend data exchange. tRPC endpoints are built on top of Next.js API Routes and deployed as Vercel Serverless Functions. Supabase is used as a managed PostgreSQL service.

Supabase is a BaaS "Firebase alternative," allowing direct data reads and writes from the frontend using a client library. Initially, I used this system but switched to tRPC + Prisma as it became difficult to handle complex configurations and store domain logic in stored procedures.

The combination of tRPC + Prisma offers a great developer experience.

UI

I'm using MUI as the component library. The richness of MUI components greatly helped in quickly building the UI.

Forms are built with the popular React Hook Form + Zod.

Page Rendering

Next.js offers various rendering methods, which are crucial for performance and Web Vitals scores.

Basic Policy

The policy for Moyuk is as follows:

Static pages (e.g., landing pages) → SG
- Generated statically at build time and cached on the CDN for speed.
Authenticated dynamic pages (e.g., dashboard) → CSR
- Data is fetched client-side.
Public dynamic pages (e.g., App or profile) → ISR
- Generated server-side (& cached on CDN), with revalidation on background requests when content becomes outdated.
- When page data is updated, cache is explicitly purged using On-demand revalidation.

tRPC and Rendering

tRPC offers SSR features, which enables automatic SSR for all pages. Initially, I used it without thinking but later stopped due to performance issues. Instead, I began explicitly prefetching the required data using Server-Side Helpers.

Rendering Pages with User-Selectable Private/Public Settings

Users can choose to make their created App public or private. If all App pages are rendered with ISR without consideration, CDN caches for private App pages will be created. Simply marking private App pages as 404 (notFound: true) will return a 404 to the App owner.

To resolve this, in Moyuk, getStaticProps fetches the App data. If the App is public, it renders normally with the data. For private (or non-existent) Apps, it renders a page with empty content. When users access the page, the App data is fetched again client-side. If the viewer is the App owner, the page continues to render. If not, a Not Found page is displayed.

Generating an App from User-Written TypeScript

Below is the UI for the App editing screen. When you write code in TypeScript, a preview of the App is displayed on the right side.

There are mainly two routes through which the user-written TypeScript is processed, and the App preview is generated.

1. Extracting Type Information from TypeScript Functions

In Moyuk, a form is automatically generated from the type information of the export default function.

The extraction of type information is done using the TypeScript Compiler API. It was quite challenging due to the lack of documentation and articles.

Helpful Resources

TypeScript Deep Dive - This resource helped in understanding internal concepts like the Scanner, Checker, and Binder.
Using the Compiler API - Sample code for specific use cases is provided, which helped in guessing the purpose of each API.
TypeScript AST Viewer - This viewer was useful in guessing the internal concepts and behavior of the Compiler API.

Support for Deno-compatible import statements

In Moyuk, you can use Deno-compatible import statements.

import { format } from "https://deno.land/std@0.181.0/fmt/duration.ts";
import { encode } from "npm:js-base64@^3.7";

The TypeScript Compiler itself does not have a mechanism for automatically resolving remote modules, so compiling them as it will result in errors. I will explain how this is resolved.

https

First, to resolve imports starting with https://, all import URLs in the code are extracted before calling the TS Compiler API, and the files they reference are downloaded in advance.

Files referenced by the downloaded files are also downloaded in a cascading manner.
If the reference destination supports the X-TypeScript-Type header on a CDN (e.g., esm.sh, Skypack), the corresponding .d.ts file is downloaded.

Next, the actual compiler is called, but with some modifications. The TS Compiler API has a component called CompilerHost that resolves the reference file for a module name. This is customized to resolve downloaded files for URL-formatted module names.

npm

By using the npm: prefix (npm: specifiers), you can import npm packages.

Moyuk uses a CDN called esm.sh to download npm packages. esm.sh builds and distributes npm packages in ES Module format, so you can use npm packages in web-standard JS runtimes like browsers.

In Moyuk, if there is an import statement starting with npm:, it is converted to an esm.sh URL, and then treated in the same way as the aforementioned https case.

npm:js-base64@^3.7 → https://esm.sh/js-base64@^3.7

2. Transpiling TypeScript to JavaScript

Since the TypeScript written by users is actually executed in the browser, it is transpiled to executable JavaScript. If an import statement references an external module, that module is bundled into a single JavaScript file along with the user-written TypeScript.

Internally, esbuild is used. Esbuild has a plugin system, and I created custom plugins to resolve import statements like npm: and https://.

By the way, during app editing and preview, these processes are executed within a Web worker. When you publish an app, the build is performed on the backend.

Executing User-Written Code Safely

Moyuk needs to actually execute the code written by users and obtain the results.
The famous method for dynamically executing code in JavaScript is eval, but it is not safe.
Considering the possibility that app creators may write malicious code, it is necessary to execute code in an isolated, safe environment.

Selecting a Sandbox Technology for the JS Runtime

After extensive research, it was difficult to decide because many options were not secure. The table below shows some promising technologies that were investigated.

Name	Client / Server	Description	Notes
QuickJS	Client	A lightweight JS engine developed by Fabrice Bellard. Can be run as WASM when combined with quickjs-emscripten. Figma plugins run on this.	Initially considered, but eventually abandoned because it was imperfect.
WebContainers	Client	A browser-based Node.js developed by StackBlitz. More faithful reproduction of Node.js compared to Sandpack.	Not considered because it was discovered late in development.
Sandpack	Client	A browser-based Node.js developed by CodeSandbox. Runs on more browsers compared to WebContainers.	Not considered because it was discovered late in development.
Deno Deploy Subhosting	Server	A new Deno Deploy-related service. An environment prepared for safely executing user-input JS/TS on the Edge.	Discovered midway through development but not noticed until recently. Still in Private Beta, but a top candidate depending on pricing.
ShadowRealm	Client	An API for creating separate Realms (similar to global scope).	Rejected due to many limitations and being in the proposal stage (Stage 3).
Custom runtime	Server	Setting up a custom server and creating a sandbox using Deno / Node.js or similar.	Rejected due to cost and maintenance concerns.
iframe sandbox	Client	An iframe with the sandbox attribute becomes sandboxed.	See below.

In the end, a combination of iframe sandbox, web worker, and Content Security Policy (CSP) was adopted.
The iframe sandbox isolates the environment, CSP restricts contact with the outside world, and the web worker executes the code.

iframe

First, create the iframe dynamically. Add the sandbox attribute to the iframe and serve the content loaded into the iframe from a separate domain (different origin) from moyukapp.com. This prevents any access from inside the iframe to the outside. Note that CodeSandbox also uses an iframe, but Moyuk's settings are much stricter.

const iframe = document.createElement("iframe");
iframe.setAttribute("sandbox", "allow-scripts allow-same-origin");
iframe.style.display = "none";
iframe.src = sandboxUrl;
document.body.appendChild(iframe);

Please note that it is dangerous to add allow-scripts and allow-same-origin to the sandbox attribute and fetch iframe content from the same origin, as this will break the sandboxing.

Web worker and CSP

Next, start a Web worker inside the iframe. The JS loaded into the Web worker has the following Content-Security-Policy (CSP) specified in the response header:

Content-Security-Policy: default-src 'none'; script-src blob:

This prevents scripts loaded into the Web worker from executing network access, eval, and other operations. Loading scripts from blob: URLs to execute user-written code is allowed (explained later).

In Moyuk, network access can be explicitly allowed by the user (Cloudflare Workers are used to dynamically rewrite the CSP).

Loading user-written code

Load the user-written code (transpiled to JS) into the aforementioned Web worker.

Moyuk's main application passes the code to the iframe, which in turn passes it to the Web worker. The Web worker converts the received code into a blob: URL and performs a dynamic import. The return value of the dynamic import allows you to obtain members exported from the user-written script.

class ExecutionContext {
  async importSourceCode(code: string) {
    const url = URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
    this.exportedMembers = await import(url);
  }

  ...
}

Scripts imported via blob: URLs inherit the parent (Web worker)'s CSP, so they cannot perform external network access or execute eval.

Note that in Firefox, dynamic import within a Web worker is not yet supported, making it an unsupported browser for Moyuk.

Executing user-written functions

Execute the target function with the values entered on the App's UI as arguments. The process looks something like this:

class ExecutionContext {
  ...

  async callFunction(functionName: string, args: unknown[]) {
    const f = this.exportedMembers[functionName];
    if (f && typeof f === "function") {
      const returnValue = f(...args);
      const value = await Promise.resolve(returnValue);
      return {
        type: "SUCCESS",
        value,
      };
    }
    return {
      type: "FUNCTION_NOT_FOUND",
    };
  }
}

Search for the function to be executed from the members exported from the code dynamically imported in the previous step, provide the arguments, and execute the function. If the result is a Promise, await and return the result.

Conclusion

Thank you for reading until the end!
As the content is quite partial, if you have any questions, please feel free to ask.

I'm also planning to write about personal development retrospectives and lessons learned at some point.

And please give Moyuk a try!
https://moyukapp.com/

I appreciate your feedback and am happy to answer any questions you may have. The following channels are available:

Send a DM/reply to @moyukapp on Twitter
Create an Issue in Moyuk's GitHub repository
Send an email to hello@moyukapp.com

Upvotes and comments on Product Hunt are also greatly appreciated and motivating 🙏

Resources

Moyuk onProduct Hunt:

Moyuk Beta - Create, run & share your custom tools effortlessly | Product Hunt

Moyuk makes building, running and sharing custom tools a breeze. Simply write a TypeScript function, and Moyuk turns it into a web app – ready to execute, manage, and share in the browser. No Moyuk-specific code is required.

producthunt.com

Introduction to Moyuk:

Moyuk: Create, Run, and Share Tools on Your Browser | Medium

Kohei Ishikawa ・ Apr 10, 2023 ・
Medium

Docs:
https://docs.moyukapp.com/

DEV Community: kohii

Writing Brain-Friendly Code: Principles of Extraction and Abstraction

About Me

The Act of Extracting Functions and Classes

Why do we split code?

Code design is much like UI design

The fractal structure of abstraction

How to Extract Functions and Classes in a Brain-Friendly Way

If they need to read the implementation, you've lost

If you abstract, hide the details completely

Let the function or class define its own interface

The bad example

The improved example

Minimize the context being pulled in

Mind the overhead of extraction

Write slightly generous comments

Think twice

Where to invest effort

Closing Thoughts

The Technology Behind SmoothCSV - The Ultimate CSV Editor

About Me

About SmoothCSV

SmoothCSV - The ultimate CSV editor for macOS & Windows

Technical Elements

Main Technology Stack

Technical Architecture

1. Technology for Building Complex Desktop Applications

Tauri is Great

Separation of Concerns through Package Extraction

Command-Centric System

System for Declaring Command and Menu Enabling Conditions

Providing Extension APIs from the Initial Stage

Advantages

Adopting MobX for State Management

Auto-update

2. Technology for Building Tabular Editors

Cell Rendering

How to Implement Virtual Scrolling Beyond the Browser's Limit

Cell Editing

Common Implementation

SmoothCSV's Implementation

Dynamically Expanding/Contracting Cell Editor Based on Input

3. Technology for Building SQL Integration Features

Filter

SQL Console

Mechanism

Conclusion

Bonus

kohii is SmoothCSV, a powerful and intuitive tool for editing CSV files - Buymeacoffee

How to Implement Virtual Scrolling Beyond the Browser's Limit

Introduction

Why Do We Need Virtual Scrolling?

Ordinary Scrolling

Virtual Scrolling as a Solution

How to Implement Virtual Scrolling

The Limits of Virtual Scrolling

Strategies to Overcome the Limits

Implementing Beyond the Limits

1. Creating a Scrollbar

2. Creating a Scroll Pane

3. Rendering the Content

Conclusion

The Technology Behind “Moyuk”: Create, Run and Share Tools with TypeScript on Your Browser

What I Created

Moyuk

Brief Overview

Moyuk: Create, Run, and Share Tools on Your Browser | Medium

Kohei Ishikawa ・ Apr 10, 2023 ・ Medium

Overview of Technical Elements

Main Technology Stack

Configuration

Moyuk as a General Application

Features Directory

State Management

Backend

UI

Page Rendering

Basic Policy

tRPC and Rendering

Rendering Pages with User-Selectable Private/Public Settings

Kohei Ishikawa ・ Apr 10, 2023 ・
Medium

Kohei Ishikawa ・ Apr 10, 2023 ・
Medium