DEV Community: koyopro

After a Year of Wanting a Typed Rails and Starting Development, I Released a Framework for TypeScript

koyopro — Fri, 28 Mar 2025 16:25:15 +0000

I released version 1.0 of Accella, a TypeScript-oriented web framework, in February 2025. In this article, I’ll provide a brief introduction to Accella, followed by a chronological overview of its development process and the design intentions behind it.

What is Accella?

Accella is a server-side web application framework designed for TypeScript. Below is an excerpt of its features from the opening section of the official website (https://accella.dev):

Server-First

Accella follows the tradition of full-stack MVC frameworks. Based on Astro, it returns pre-rendered HTML to the client from the server. By keeping the architecture simple, it enhances both development efficiency and user experience.

ORM Integration

Accella utilizes Accel Record, an ORM implemented with the Active Record pattern. This integration enhances development efficiency, particularly for database CRUD operations.

Type Safety

Accella provides a type-safe development environment with TypeScript, covering everything from table operations to template rendering.

For more details about the framework, check out the official website. It includes sample code for application development and comparisons with other frameworks.

Design Intentions and Development Journey

I’ll outline the journey from the start of Accella’s development to its release, focusing particularly on aspects related to its design intentions.

Starting with an ORM Library

Development of Accella began in January 2024. At the time, I wanted to contribute to open-source software (OSS) while also thinking, “I wish TypeScript had a framework as efficient as Ruby on Rails.”

The elements I sought in this “Rails-like development efficiency” included:

Development based on SSR (Server-Side Rendering) for MPA (Multi-Page Applications), not SPA (Single-Page Applications).
The ability to implement RDB (Relational Database) CRUD functionality with minimal code.
A framework covering the MVC (Model-View-Controller) domains.

After researching existing frameworks, I couldn’t find one that sufficiently met these criteria. Further analysis led me to conclude that a powerful ORM like Rails’ Active Record was necessary, so I started the project by developing an ORM for TypeScript.

I wrote about the motivations behind this in more detail in the following article:

Seeking a Type-Safe Ruby on Rails in TypeScript, I Started Developing an ORM

Using Prisma for Table Definitions and Migrations

While developing the ORM, I considered how to handle table definitions and migrations.

I discovered that Prisma’s generator feature allows arbitrary code generation from Prisma’s table definition files. Even query builder libraries like Kysely can use Prisma generators to output necessary type definition files. For this ORM, I decided to use Prisma for table definitions and migrations, automatically generating required files with Prisma’s generator. While Rails’ migrations involve creating differential files, I personally find Prisma’s approach—automatically generating migration files from schema files—more convenient, which was one reason for this choice.

Adopting a Synchronous API for the ORM

Typically, JavaScript/TypeScript libraries use asynchronous APIs for external access like database operations. However, as development progressed, I began to think that designing the ORM’s interface as a synchronous API would be better.

With asynchronous APIs that return Promises, the common approach is to use await to wait for completion:

const user = await User.first(); // Fetch the first User from the database

I found that asynchronous APIs limited the library’s interface, making it difficult to achieve the usability of Rails’ Active Record. So, I adopted a synchronous API that allows calling operations without await. This was the most challenging part of the ORM’s design and implementation, but it’s also where its uniqueness shines.

I’ve written more about synchronous APIs in the following articles, so feel free to check them out if you’re interested:

Releasing the ORM as Accel Record

In April 2024, I released version 1.0 of the ORM library “Accel Record.” It implements core CRUD operations for tables, featuring a synchronous API and type safety, such as changing model types before and after persistence.

Introduction to "Accel Record": A TypeScript ORM Using the Active Record Pattern

Afterward, I added more features to the ORM, heavily inspired by Rails’ Active Record:

Validation
Factories
Bulk Inserts
Serialization
Transactions
Internationalization (I18n)
Callbacks
PostgreSQL Support
Password Authentication
Scopes
Advanced Search
Locking
Composite Key Support
Form Objects

Using Astro Components for Rendering

In Rails, pagination and forms can be easily created based on Active Record data. I wanted to achieve similar functionality in Accella. I also wanted the View templates (like erb in Rails) to be type-safe. Traditional server-side JS template engines (EJS, Pug, etc.) didn’t seem capable of this. That’s when Astro came up as a candidate. I found that Astro components allow type-safe server-side template rendering, similar to React or Vue.

By August 2024, the ORM’s features were fairly robust, so I began implementing functionalities such as form building integrated with the ORM using Astro components:

Pagination
Forms
Request Parameter Parsing
Session Management
CSRF Protection

Contributing to Astro

To use Astro components as a template engine, Astro needed to serve as Accella’s base. In MVC terms, the Model is handled by Accella’s custom ORM, while the View and Controller are managed by Astro’s features.

While developing features, I frequently worked with Astro and contributed to its community by addressing issues I encountered.

In Rails, session data is stored in cookies by default. I created a library for Astro to store sessions in cookies and shared it on Reddit, receiving a lot of positive feedback:
I just published "Astro Cookie Session", middleware for managing sessions using cookies on Astro. : r/astrojs

I also submitted two bug-fix pull requests to Astro’s main repository, which were merged.

Polishing it as a Framework

Around November 2024, I worked on refining the features I’d built into a usable framework. Like Rails’ rails new, I aimed for an environment where application development could start immediately with npm create.

I ensured that SQLite could be used for development right after setup and that tests involving table read/write operations could run, focusing on completing database-related setup. Accella uses Vitest as its testing framework, but since Vitest runs tests in multiple processes (or threads), I had to devise ways to properly prepare multiple test databases.

Ultimately, running npm create accella sets up an environment where database-driven development can begin immediately.

Documentation and Version 1.0 Release

Starting in January 2025, I prepared Accella’s documentation site, creating a starter guide while fixing usability issues and bugs. I built the documentation with Astro Starlight and hosted it on Netlify, which made the process quite smooth.

On February 26, 2025, I released version 1.0 of Accella.

I posted about it on Reddit and received a lot of responses:

Introducing Accella: A Full-Stack Framework Built on Astro : r/astrojs

Future Development

With version 1.0 released and documentation prepared, Accella is now in a state where others can try it out. I believe I’ve created one direction for my initial motivation: “I want a TypeScript framework as efficient as Ruby on Rails.” In particular, the ORM featuring the “Active Record pattern” and “synchronous API” could offer a new option for server-side JavaScript.

Currently, I’m developing a CarrierWave-like library that integrates with ORM models to easily upload files to S3.

In the future, I’d like to work on:

A library for efficiently managing initial (seed) database data (like Seed Fu).
A library for easily creating internal admin panels (like Active Admin).

If you’re interested, I’d be delighted if you’d star the repository:
https://github.com/koyopro/accella

Thank you for reading to the end!

Released a Library for Synchronous Execution of Asynchronous Processes in JS/TS

koyopro — Mon, 16 Dec 2024 18:57:26 +0000

I have released a library called sync-actions that allows asynchronous processes to be executed synchronously in JavaScript/TypeScript. Especially in TypeScript, you can call defined functions in a type-safe manner. It is intended for use in cases where you want to execute asynchronous processes within functions that you do not want (or cannot) mark as async.

Features

Utilizes Node.js worker_threads
- Asynchronous processes are executed in a sub-thread, and the main thread waits synchronously for their completion.
Type-safe function calls
- In TypeScript, you can utilize the type information of defined functions.
Published as Native ESM
- It is made simple by not supporting CommonJS.

Repository

https://github.com/koyopro/sync-actions

Usage

Installation

It is published as an npm package, so please install it using npm install or similar.

npm install sync-actions

Basic Usage

By passing an asynchronous function that returns a Promise object to defineSyncWorker(), you can define the interface and start the worker thread with launch(). It is assumed that the file defining the worker is created separately from other processing files.

// worker.js
import { defineSyncWorker } from "sync-actions";

export const { actions, worker } = defineSyncWorker(import.meta.filename, {
  ping: async () => {
    // Execute asynchronous process,
    await new Promise((resolve) => setTimeout(resolve, 1000));
    // Return the result as a return value
    return "pong";
  }
}).launch();

// main.js
import { actions, worker } from "./worker.js";

// You can execute asynchronous functions synchronously
console.log(actions.ping()); // => "pong" is output after 1 second

worker.terminate();

Type-safe Function Calls

In TypeScript, you can call functions defined with defineSyncWorker in a type-safe manner.

// worker.ts
import { defineSyncWorker } from "sync-actions";

export const { actions, worker } = defineSyncWorker(import.meta.filename, {
  // By specifying the types of arguments and return values, type-safe calls are possible
  add: async (a: number, b: number): Promise<number> => {
    return a + b;
  }
}).launch();

// main.ts
import { actions, worker } from "./worker.js";

// Type-safe call
actions.add(1, 2); // => 3 (number)

// @ts-expect-error
actions.add("1", 2);
// => Argument of type 'string' is not assignable to parameter of type 'number'

worker.terminate();

Background

The content so far is the same as the README, so I will describe the background of its creation.

I am developing an ORM called Accel Record.¹ Unlike general ORMs, Accel Record is designed to perform DB access with a synchronous interface.² The part that executes DB access synchronously was realized by executing asynchronous processes in a subprocess started with the child_process module.³ I thought that by using worker_threads instead of child_process, I could reduce the overhead at runtime.

Accel Record is also designed to be similar to Ruby on Rails' Active Record in terms of usability, and one of the things I want to achieve in the future is to create a library like CarrierWave. CarrierWave allows you to save images to external storage services (such as AWS S3) when saving records, and to achieve this with Accel Record, it is necessary to execute asynchronous processes such as image uploads synchronously. I expect that this process can be executed faster by using worker_threads instead of subprocesses.

So I once looked for a library that synchronously executes asynchronous processes using worker_threads. I found several libraries such as synckit and deasync, but none of them worked as expected on my end, so I decided to create my own. Since I was at it, I thought I would make an interface that can be used in a type-safe manner with TypeScript.

More Internal Details

Until the asynchronous process in the sub-thread started with worker_threads is completed, the main thread is blocked using Atomic.wait().
MessageChannel is used for communication between threads. The source code of synckit was very helpful for this part of the implementation.
When starting a Worker with worker_threads, it is necessary to transpile the .ts file to .js. For that part, I am using esbuild.
When starting a Worker, I wanted to pass the transpiled source code as a string to the Worker for execution, but it did not work properly in my environment. This is the part where I struggled the most. In the end, I wrote the file under node_modules and passed its path to the Worker. This method turned out to be the most stable.

Password Authentication with Auth.js in Astro and Customizing Session Information (auth-astro)

koyopro — Tue, 01 Oct 2024 21:51:57 +0000

Background

I wanted to implement a feature in Astro that allows authentication with an email and password and stores session information in cookies.
It seemed possible with auth-astro, which is officially introduced in Astro.
- auth-astro is a wrapper library that makes Auth.js (formerly NextAuth.js) easier to use in Astro.
I couldn't find consolidated information for the following two points, so I organized them:
- How to set up password authentication.
- How to customize the authentication information saved in cookies.

Important Note

After trying this, I found Auth.js to be somewhat difficult to use, so it's worth considering carefully before deciding to use it. Refer to the Impressions section for details.

Environment

Node.js: 20.11
astro: 4.15.2
auth-astro: 4.1.2
@auth/core: 0.35.3

※ In auth-astro 4.1.2, "@auth/core": "^0.32.0" is specified in the dependencies, but version 0.32.x had an issue where a 500 error occurred during error handling for CredentialsSignin, so I specified the latest version.

Final Code

Assuming that auth-astro has already been integrated into a project created with Astro, you can set up password authentication and customize session information by configuring auth.config.mjs as follows. The example below saves the logged-in user's ID as a session token in cookies.

// auth.config.mjs
import { CredentialsSignin } from "@auth/core/errors";
import Credentials from "@auth/core/providers/credentials";
import { defineConfig } from "auth-astro";

export default defineConfig({
  providers: [
    Credentials({
      name: "Email",
      credentials: {
        email: { type: "email", required: true, label: "Email" },
        password: { type: "password", required: true, label: "Password" },
      },
      authorize: async (credentials) => {
        const { email, password } = credentials;
        const user = await authorize(email, password); // your logic here
        if (!user) throw new CredentialsSignin();
        return { id: user.id };
      },
    }),
  ],
  callbacks: {
    async jwt({ user, token }) {
      if (user) {
        return { id: user.id };
      }
      return token;
    },
    session({ session, token }) {
      return {
        ...session,
        user: { id: token.id },
      };
    },
  },
});

UI

Using the login screen provided by Auth.js, the following behavior can be seen:

Login Screen (/api/auth/signin)

When Authentication Fails (/api/auth/signin?error=CredentialsSignin&code=credentials)

When Authentication Succeeds

After successful authentication, you are redirected to another page, and you can retrieve session information using getSession.

// pages/example.astro
---
import { getSession } from 'auth-astro/server';

const session = await getSession(Astro.request)
console.log(session)
// {
//   user: { id: 1 },
//   expireds: '2024-10-01T00:00:00.000Z'
// }
---
{session?.user ? (
  <p>Logged in as User {session.user.id}</p>
) : (
  <p>Not logged in</p>
)}

When authentication is successful, a cookie named authjs.session-token is saved, with its contents encrypted in JWT format by Auth.js.

Example of a Session Token

eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoiTjEzYW5aS3hzMmpXT0pDUmNYaTRCYjZCMkdUNmxZdmxaa3lUVEdfbHRYZG14UEJVYkVkNkJxaVlRRnhNdTFuZjRBa3BGRmxhTlI1dW11ZENRc3JaQ0EifQ..IAkEwYkG1M9Y-J5rTju63g.haLgQeSxUEqctr2Gjn23sMaNEAaGb9y1ott-dZnws-oo7Sdcz1fnPRRIvpLpBe6LkJN2JMELAHbElbAl-41BrgAzUDTeWnGlNTeFVa3Em6iWObNtfwX_H7nOtnddB3OZ.aOZQ_jzdVkNvdepksoAFc9I8Qz7fuFlcAtJcN-Tp-ng

Customizing the Session Token

Default Behavior

When using Credentials, the default behavior is to save email as the unique key in the cookie. If you don't need to change the format, customization of the callbacks is unnecessary. The following settings would suffice.

// auth.config.mjs
import { CredentialsSignin } from "@auth/core/errors";
import Credentials from "@auth/core/providers/credentials";
import { defineConfig } from "auth-astro";

export default defineConfig({
  providers: [
    Credentials({
      name: "Email",
      credentials: {
        email: { type: "email", required: true, label: "Email" },
        password: { type: "password", required: true, label: "Password" },
      },
      authorize: async (credentials) => {
        const { email, password } = credentials;
        const user = await authorize(email, password); // your logic here
        if (!user) throw new CredentialsSignin();
        return { email: user.email };
      },
    }),
  ],
});

Contents of the session

const session = await getSession(Astro.request)
console.log(session)
// {
//   user: { email: 'test@example.com', name: undefined, image: undefined },
//   expireds: '2024-10-01T00:00:00.000Z'
// }

Customization Details

If you want to save information other than the email in the session token, you will need to specify the callbacks. The example below replaces the email with the user ID. This is reflected in the code shown in the "Final Code" section of this article.

authorize: async (credentials) => {
  // ...
  return { id: user.id }; // Change the return format
},

callbacks: {
  // Change the token format saved in the cookie
  async jwt({ user, token }) {
    if (user) {
      return { id: user.id };
    }
    return token;
  },
  // Change the format of the information read from the token
  session({ session, token }) {
    return {
      ...session,
      user: { id: token.id },
    };
  },
},

In this case, you can retrieve the session in the following format:

const session = await getSession(Astro.request)
console.log(session)
// {
//   user: { id: 1 },
//   expireds: '2024-10-01T00:00:00.000Z'
// }

Impressions

The feature I wanted to implement, "password authentication with email and saving session information in cookies with Astro," was achieved with the above configuration.

However, after working with Auth.js, I felt that customizing its behavior might be challenging.

For example, in the following cases, there is no official support, so you would likely need to prepare a custom page and implement it yourself:

If you want to change error messages (for multilingual support, etc.)
If you want to modify the appearance of the login page

Also, keeping the email address entered in the field after an authentication failure seems quite difficult with the current Auth.js system. Since there is a redirect during the authentication process, the information entered in the form is lost.

In my research, I also came across the following opinions:

You're not a bad engineer, NextAuth is a bad library. - Reddit

Conversely, it feels like NextAuth was written with the express goal of avoiding the complexity of auth, and it does it badly. It lets you get something working quickly, but later causes immense pain trying to customise it.
Why is next-auth (or Auth.js) so popular? - Reddit

I have tried to build a new website with auth, and my experience with Auth.js (v5) was nothing short of a disaster. The docs was horrible, it offers little customizability, and the configuration just doesn't work. If I were the project lead, I wouldn't promote this piece of shit until it gets stable.

If you're using the default behavior of Auth.js, there might not be any issues, but if you're considering any customizations, it might be worth reviewing beforehand.

References

Authentication | Astro
https://docs.astro.build/en/guides/authentication/#authjs
nowaythatworked/auth-astro: Community maintained Astro integration of @auth/core
https://github.com/nowaythatworked/auth-astro
Credentials | Auth.js
https://authjs.dev/getting-started/authentication/credentials
Callbacks | NextAuth.js
https://next-auth.js.org/configuration/callbacks

Two Reasons Why I Often Use Python for Creating Personal Tools (Plus One Complaint)

koyopro — Sat, 21 Sep 2024 16:39:40 +0000

I often use Python when creating tools for personal use. The tools I create are generally for automating day-to-day tasks or for fun application projects.

These are usually small projects that I complete in a few days and don’t update much afterward. The considerations are different for larger, publicly released services, but here are two reasons why I frequently choose Python for small tool development.

Reason 1: Python Can Do Almost Anything

When I want to accomplish something, Python often already has a library for it. Here are some examples of Python libraries I've used for personal projects.

Machine Learning

Python is likely the most well-equipped language for machine learning libraries.
Although I don’t personally train deep learning models often, I sometimes use scikit-learn or XGBoost to build and apply models.

Image Processing

I’ve written scripts for managing personal photos.
Libraries like PIL (Python Imaging Library) and Pillow help me retrieve Exif data or resize images.

Scraping

I’ve created tools to periodically check information on certain websites.
You can use simple libraries like Requests, or more comprehensive ones like Scrapy to make scraping even easier.

Cryptocurrency Trading

I once wanted to use a cryptocurrency exchange API.
Thanks to the library ccxt, which allows you to use the APIs of over 100 exchanges with a unified interface, I could achieve what I wanted.
It was very helpful not to have to investigate the API specifications of each exchange and to be able to trade with a consistent interface.

Web Applications

Sometimes I want to control the above functionalities through a GUI.
In such cases, I often use Django to run it as a web application.
I particularly like Django because it provides an admin panel by default, making it easy to manage settings and check data.

Reason 2: It’s Cheap to Run in the Cloud

Since personal tools aren’t used frequently, I want to keep the costs low when running them on a server. Python has long been supported by free cloud platforms, which is another reason I choose it for personal tool development.

Google App Engine (GAE)

GAE offers a free tier in its standard environment.
Since it has supported Python since its release in 2008, I’ve often used it for running personal tools.
It’s also handy that you can set up cron jobs for scheduled execution through the management console.

AWS Lambda

AWS Lambda was released in 2014, and Python has been supported since October 2015.
It also offers a free tier, so I sometimes run tools on it nowadays.
Using the Serverless Framework provides a smooth experience from local development to deployment.

(Depending on the situation, I also run tools on EC2 or Heroku.)

Complaint About Developing with Python

There are some aspects of Python that I find unsatisfactory. In particular, the management of virtual environments and packages tends to be unstable. When I check back after some time, I often find a new method has been introduced or an old method has been deprecated. I’ve used the following tools, but it’s easy to get confused if you don’t understand how to use each one properly. (I’m not sure what the current best practices are.)

virtualenv
venv
pipenv
pip-tools
poetry

Conclusion

I’ve listed two reasons why I often use Python for creating personal tools and added one complaint for good measure. I hope this has been helpful.

Git Feature Flow – A More Flexible Branch Model for Incremental Releases Than Git-Flow

koyopro — Sun, 08 Sep 2024 17:33:50 +0000

Background

In a server-side development project, we were using Git-Flow (or something similar), but we faced difficulties during production releases. This article is about how we changed the Git workflow to solve these issues.

First, I'll explain the problem in order, so if you're only interested in the conclusion (the new workflow), you can skip to this section.

There are several well-known Git workflows, such as Git-Flow, GitHub Flow, and GitLab Flow, but our new workflow felt a bit different from any of these, so I decided to summarize it.

Overview of the Project Where It Was Introduced

The best workflow depends on the project, so I'll briefly describe the project where we introduced this new workflow.

There are fewer than 10 developers (engineers).
- It's a relatively small team, but larger than just one or two people.
The contents of the develop branch are always reflected on the testing server.
- Updates to the develop branch are automatically uploaded via CI.
The contents of the master branch are reflected in the production environment.
- The master branch must always be in a releasable state.
Feature branches are developed locally.
- Most people develop on their Mac locally.
There is only one testing server.
- We have considered setting up a server for each branch, but the current operation has determined that one server is more suitable.
Production releases occur about once every few days to two weeks.
- It's not the kind of environment where we release to production multiple times a day.
- The release process itself is simple, just one command if the updates are in the master branch, so the cost of the process is low.

The Original Workflow

Branch Model

Although we called it Git-Flow, it wasn’t the full Git-Flow but rather a workflow with the release branch omitted.

develop
- The branch for internal testing.
feature/xxx
- A local branch for developing features.
- Branched off from develop.
master
- The branch for production.

In the diagram above, two feature branches are created and reflected on the testing server when merged into develop. After passing the tests for each branch, merge develop into master and release.

Unable to release without other feature tests passing

Here’s a scenario where this flow causes problems.

The same flow as before, but it becomes problematic when you want to release feature/2 immediately after it has passed the tests. This is because feature/1, which requires fixes and testing, gets released together.

You might think that you can simply fix and test feature/1 right away, but there are various reasons in the project that make it not easy to do so. (For example, there may be a need for specification changes after testing, or the person in charge may not be available for the next 3 business days. Even if the fixes can be done quickly, there are important people who need to check it during the internal testing stage and they are not easily available.)

The feature/2 branch has passed the tests, but it cannot be released immediately in the usual flow. We need to wait for the fixes and tests on the feature/1 branch to be completed, or we need to take measures such as cherry-picking only certain commits. This is relatively easy if there are only a few branches, but it becomes quite difficult to coordinate the timing of releases when the number of developers increases and they are working on separate feature developments.

We only have one server for internal testing, and as long as we follow the procedure of releasing to production after passing the tests, I think the same problem will occur with GitHub Flow or GitLab Flow.

The New Workflow

Branch Model

The new workflow still uses three types of branches:

develop
- The branch for internal testing. Reflected on the testing server.
- No direct commits/pushes.
- Updated by merging feature branches.
master
- The branch for production. Reflected on the production server.
- No direct commits/pushes.
- Updated by merging feature branches.
feature/xxx
- A local branch for developing features.
- Branched off from master.
- Created for each feature that is to be released (multiple feature branches can exist at the same time).

The biggest difference from Git-Flow is that the feature branches are always branched from master. It's similar to a hotfix branch in Git-Flow. This allows features to be released individually.

Pros

You can release each feature individually.
- There’s no need to coordinate release timing with other people or features.
No need to create hotfix branches.
- Since feature branches always branch off from master, they handle hotfixes the same way.
- In Git-Flow, post-release fixes involve irregular branch operations, but this method is much simpler.

Cons

You need to manage each feature until it’s released.
- Merging into develop doesn’t automatically mean the feature will be reflected; if a feature branch is forgotten, it may never be released.
- However, if you link tasks in your task management tool with feature branches, this shouldn’t be much of a problem.
- A tip: when creating a pull request from a feature branch to develop, simultaneously create a pull request to master to avoid forgetting.
The possibility of conflicts between features increases.
- If a feature is developed over a long period without being merged into master, it may conflict with other features during the develop merge.
- In such cases, you’ll need to coordinate with the feature branch causing the conflict.

Thoughts

In the project I’m working on, multiple features are developed in parallel. Not having to consider others’ timelines when releasing has made the process much easier.
As a result, whereas we previously released once every two weeks due to the hassle of coordinating everything, we’re now able to release small feature additions and fixes every two days.
I used Gitgraph.js to create the flow diagrams. It was my first time using it, but I found it really easy!
I wanted a name for this new flow, and I found an article referring to a similar method as "GitFeatureFlow." This name felt right to me, so I’ll be using this term from now on. ¹

GitFlowは使わない！シンプルな「GitFeatureFlow」を紹介します - ぐるなびをちょっと良くするエンジニアブログ (in Japanese) ↩

How to Perform Error Handling Across Pages in Astro

koyopro — Fri, 30 Aug 2024 16:58:54 +0000

To handle errors across pages in Astro's server mode, you can use Middleware.

By using await next(), you can execute the subsequent process and handle errors with try-catch.

// src/middleware.ts
import { defineMiddleware } from "astro/middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  try {
    return await next();
  } catch (e) {
    // Handle errors here
    throw e;
  }
});

Usage Examples

Sending error logs

If you want to send error logs when an error occurs, you can simply throw the caught error.
This can be useful when notifying error collection services like Sentry.
(Assuming there is a function called notifyError)

// src/middleware.ts

import { defineMiddleware } from "astro/middleware";
import { notifyError } from "./notifyError";

export const onRequest = defineMiddleware(async (context, next) => {
  try {
    return await next();
  } catch (e) {
    // Send error logs
    notifyError(e);
    throw e;
  }
});

Displaying a 404 page for specific errors

If you want to display a 404 page for specific errors, you can check the error content and return a 404 page.
For example, when the data specified by a path parameter does not exist in the database, instead of returning a 500 error, you can display a 404 page.
(Assuming an error called NotFoundError is thrown in such cases)

// src/middleware.ts

import { defineMiddleware } from "astro/middleware";
import { NotFoundError } from "./errors";

export const onRequest = defineMiddleware(async (context, next) => {
  try {
    return await next();
  } catch (e) {
    // Display a 404 page for NotFoundError
    if (e instanceof NotFoundError) {
      return context.rewrite("/404");
    }
    throw e;
  }
});

Alternative Approach

Another approach is to create a custom 500 page and handle errors.
https://docs.astro.build/en/basics/astro-pages/#custom-500-error-page
However, using Middleware is more versatile in my opinion.

// src/pages/500.astro
---
import { notifyError } from "../notifyError";

interface Props {
  error: unknown;
}

const { error } = Astro.props;
if (error instanceof NotFoundError) {
  return Astro.rewrite("/404", 404);
}
notifyError(error);
---

500 Internal Server Error

Thoughts

According to the Middleware documentation, it is possible to rewrite the response content, so it feels very flexible.

Techniques for Synchronous DB Access in TypeScript

koyopro — Fri, 05 Jul 2024 17:46:07 +0000

I am developing an ORM library for TypeScript called Accel Record. Unlike other TypeScript/JavaScript ORM libraries, Accel Record adopts a synchronous API instead of an asynchronous one.

However, to execute DB access synchronously, it was necessary to conduct thorough technical research.

In this article, I will introduce the techniques Accel Record employs to achieve synchronous DB access.

Supported Databases

Accel Record supports the following databases:

SQLite
MySQL
PostgreSQL

In the early stages of development, priority was given to supporting SQLite and MySQL. Therefore, this article focuses on SQLite and MySQL.

SQLite

When using SQLite with Node.js, the better-sqlite3 library is commonly used. Other ORM libraries also frequently use better-sqlite3 to access SQLite.

Upon investigation, we found that better-sqlite3 inherently provides a synchronous API. Thus, executing queries to SQLite synchronously was easily achievable using better-sqlite3.

MySQL

The challenge was with MySQL.

When using MySQL with Node.js, the mysql2 library is commonly used. However, mysql2 only offers an asynchronous API, making it impossible to use a synchronous API. We searched for other MySQL libraries that offered a synchronous API but could not find any that were well-maintained recently.

Next, we investigated whether there was a way to execute asynchronous APIs synchronously.

We found several older libraries claiming to execute MySQL queries synchronously, and we examined how they achieved synchronous processing.

The first method involved using Atomics.wait(). This method employs two threads: one for performing asynchronous operations and one for synchronously waiting for the result. Libraries such as synckit wrap this functionality to make it more user-friendly. However, synckit cannot be used outside the main thread and is not easily usable in a multi-threaded environment. In the Accel Record project, we use Vitest for testing. Vitest performs parallel testing using Node.js worker_threads, making this constraint a barrier to adoption.

The second method led us to a library called sync-rpc. This library uses Node.js's child_process module to create a separate process for executing asynchronous operations and waits synchronously for the result. Upon testing, we found that we could use sync-rpc to leverage mysql2's asynchronous API synchronously. However, since sync-rpc itself is an older library and did not always perform as expected, we incorporated its source code and made necessary modifications to achieve the desired functionality.

How sync-rpc Works

sync-rpc operates as follows:

The main process specifies the entry point file and starts a child process.
The child process reads the entry point file and starts as a server.
The main process requests function execution from the child process and waits synchronously for the result.
The child process executes the asynchronous function and returns the result to the main process.
The main process receives the result from the child process and continues processing synchronously.
When the main process exits, the child process also terminates.

Using sync-rpc, we realized that any asynchronous process could be used synchronously from the perspective of the main process.

Current Implementation of Accel Record

Currently, by using sync-rpc, we can execute asynchronous processes synchronously. Therefore, regardless of the database engine, queries are executed through sync-rpc for SQLite and PostgreSQL as well.

Specifically, SQL construction is performed in the main process, and only the query execution is handled by the child process using sync-rpc.

Future Improvements

While the current implementation uses sync-rpc to execute asynchronous processes synchronously, it relies on launching a child process.

However, using child processes has its drawbacks:

Overhead of inter-process communication
- There is overhead due to data exchange between the main process and the child process.
- Generally, this overhead is not significantly large compared to DB access latency, so it may not be a major issue in this case.
Operational complexity
- Launching child processes can complicate operations.
- Currently, we depend on Node.js's child_process for launching child processes, which might make it difficult to operate in environments other than Node.js.
- It is expected to work properly in typical Node.js environments and serverless environments where Node.js runs (e.g., AWS Lambda, Vercel Functions).

If we find a method that can overcome these drawbacks, we would consider adopting it.

Summary

We introduced the techniques Accel Record considered and adopted to achieve synchronous DB access. During the research phase, we explored methods to execute asynchronous processes synchronously using multi-threading and inter-process communication. Ultimately, we adopted sync-rpc, which spawns a separate process, to execute queries synchronously.

Please check out 'Introduction to "Accel Record": A TypeScript ORM Using the Active Record Pattern' and the README to see what kind of interface Accel Record can achieve by adopting a synchronous API.

Even Server-Side TypeScript Needs the Option to Avoid Asynchronous Processing

koyopro — Wed, 26 Jun 2024 17:15:11 +0000

I am developing a TypeScript ORM library called Accel Record.
Unlike other TypeScript/JavaScript ORM libraries, Accel Record adopts a synchronous API instead of an asynchronous API.

In the process of examining the ORM interface, we compared the advantages and disadvantages of asynchronous and synchronous APIs. In this article, I would like to organize those thoughts and discuss the idea that we might need an option to develop in synchronous processing even in server-side TypeScript.

What Is Asynchronous Processing in TypeScript/JavaScript?

When running JavaScript on the server side, Node.js is often used.
Node.js uses a single-threaded asynchronous I/O model, and it is common to implement applications that use asynchronous processing.

The way to write asynchronous processing has historically changed, but currently, writing with async/await is mainstream.

// Functions that perform asynchronous processing are marked with `async` and return a Promise
const fetchUsers = async (): Promise<User[]> => {
  // Process to retrieve users from the DB
  // ...
};

// Use await to wait for the result of the asynchronous process
const users = await fetchUsers();

As shown above, functions that perform asynchronous processing are implemented by marking them with async and returning a Promise. On the caller side, the result of the asynchronous process is awaited using await.

In the past, JavaScript achieved asynchronous processing using callback functions, but recently, using async/await has made writing asynchronous processing more intuitive. While the development experience has greatly improved, the necessity to be aware of whether the called function performs asynchronous processing and write await accordingly remains unchanged.

Calling an asynchronous function without await can lead to unintended behavior. Therefore, it is necessary to consider whether the called function is synchronous or asynchronous and decide whether to write await, a task that needs to be done every time.

Asynchronous Processing Used on the Server Side

If there are hardly any asynchronous calls, the above task may not be much of an issue. However, in server-side development for web applications, asynchronous processing is often used. This is because DB access in JavaScript libraries is basically implemented as asynchronous processing.

In server-side processing for web applications, the main flow is to receive an HTTP request, perform DB access such as data retrieval or writing, and return the final result as an HTTP response. The more complex the application, the more places where DB access is needed, and asynchronous processing is often used.

When there are many places to write asynchronous processing, the necessity to be aware of whether to write await increases. Compared to cases where asynchronous processing is not used at all, the cost of caring for such detailed parts increases, reducing development efficiency.

Benefits of Using Asynchronous Processing

So, what are the benefits of asynchronous processing, and why is it used?

The most significant advantage is the improvement of system performance.

In execution environments like Node.js, using asynchronous processing allows the time spent waiting for I/O to be utilized for other processes. As a result, it is expected that the overall system performance will be better than if asynchronous processing is not used. For example, when there is a process to access the DB upon receiving an HTTP request, it becomes possible to accept other requests while waiting for the response from the DB.

Node.js has the concept of an event loop, and it is considered important for performance to not block the event loop by properly using asynchronous processing.

The Option to Avoid Asynchronous Processing

However, during the process of examining the ORM interface, I started to question whether it is necessary to always use asynchronous processing just because it is a JavaScript execution environment. I realized that by assuming asynchronous processing, it becomes difficult to abstract the library and that every method that may involve DB access requires the use of await. I felt that if DB access can be done synchronously, it would allow for the realization of an ideal interface and create a more user-friendly library.¹ While implementing the application with a synchronous approach may result in some decrease in system performance compared to using asynchronous processing, there is also the benefit of reducing the effort of determining whether a function is asynchronous and adding await.

Taking these factors into consideration, I believe that by implementing a synchronous-centric approach instead of relying on asynchronous processing, we can improve the development efficiency of the application.

Depending on the nature of the product being developed, prioritizing development efficiency over system performance may be desirable in some cases. And I believe this is a fairly common scenario.

In other languages commonly used for server-side development, it is common to not use asynchronous processing. It is not always necessary to pursue performance by using asynchronous processing, and if there are other advantages, it is often adopted. (In fact, I still feel that choosing TypeScript/JavaScript for server-side development is not yet mainstream.)

Advantages of Choosing TypeScript for Server-Side Development

So, if we prioritize development efficiency over performance, are there any reasons to choose TypeScript for server-side development? I believe there are two major advantages:

1. Reducing Context Switching by Unifying Development Languages with the Frontend

Currently, TypeScript is widely used for frontend development in web applications. By adopting TypeScript for server-side development as well, the commonality with the frontend can be improved, and the burden on developers can be reduced by lowering the cost of switching languages.

2. Improved Development Experience Through Type Safety and Type Support

TypeScript is a statically typed language, which makes it easier to receive editor support such as autocompletion and allows for early bug detection through type checking. This type safety is a very powerful factor, especially in the development of large-scale applications. Compared to other languages chosen for server-side development, which are not always highly type-safe, the advantages of choosing TypeScript are significant.

These two advantages make it worthwhile to choose TypeScript for server-side development, even when prioritizing development efficiency.

Enhancing Development Efficiency in Server-Side TypeScript

From the above two points, development in TypeScript has the characteristic of maintaining high development efficiency. However, the current TypeScript server-side development environment, which requires an asynchronous processing-centric implementation, seems to be a factor that lowers that development efficiency. Moreover, it seems to affect various libraries. Due to the assumption of asynchronous processing, ideal interfaces may not always be adopted, resulting in compromised usability.

As a result, the advantage of choosing TypeScript for server-side development might be halved.

For server-side TypeScript development to become more widespread, I believe it is necessary to have the option to develop without using asynchronous processing. It is necessary to be able to choose a development experience where there is no need to care for asynchronous processing every time there is DB access.

When developing a new TypeScript ORM library, I decided to adopt a synchronous API. The reason is that by using a synchronous API, the interface can be more abstracted, and I believe the experience of library users will improve more than with an asynchronous API.

Until now, server-side JavaScript might have been chosen for performance.

However, I think server-side TypeScript might be chosen for development efficiency. And to support that, I believe the option to avoid asynchronous processing is necessary.

Conclusion

I discussed the idea that to improve development efficiency in server-side development using TypeScript, it might be necessary to have the option to develop without using asynchronous processing.

Please refer to 'Why We Adopted a Synchronous API for the New TypeScript ORM' which I wrote previously to see the impact of asynchronous processing on the ORM interface. ↩

Why We Adopted a Synchronous API for the New TypeScript ORM

koyopro — Thu, 20 Jun 2024 16:10:09 +0000

I am developing a TypeScript ORM library called Accel Record. Unlike other TypeScript/JavaScript ORM libraries, Accel Record has adopted a synchronous API instead of an asynchronous one.

In this article, I will explain the background and reasons for adopting a synchronous API in Accel Record.

The ORM We Wanted to Create

In the article "Seeking a Type-Safe Ruby on Rails in TypeScript, I Started Developing an ORM," I introduced the start of my work on a TypeScript ORM library.

My goal was to have a framework for TypeScript that is as efficient as Ruby on Rails. To achieve this, I decided to try creating an ORM in TypeScript with functionalities similar to Rails' Active Record. Hence, the first step in creating this new ORM was to imitate the API of Active Record.

Problems with Asynchronous APIs

In JavaScript/TypeScript, database access is typically done using asynchronous APIs with Promises or callbacks. Since libraries for database access also return Promises for each operation, the new ORM naturally implemented each API asynchronously.

When executing asynchronous APIs, it is common to use await to handle them in sequence. For example, when performing CRUD operations on the User model, it looks like this:

await User.create({ name: "Foo" }); // Create

const user = await User.find(1); // Read

await user.update({ name: "Bar" }); // Update

await user.delete(); // Delete

Although it’s somewhat tedious to write await each time, it wasn't a major issue initially. However, the problem became more significant when handling associations. Consider a case where the User model has a hasOne association with the Setting model.

Problem Example 1: Updating Associations

I wanted to write the update process like this, following the Active Record interface:

const setting = Setting.build({ theme: "dark" });
await user.setting = setting; // This is not possible

The reason for adding await here is that this operation might involve database access. In Rails' Active Record, if this setter causes a change in either the user or setting, a database access (save operation) occurs.

However, since TypeScript setters cannot be asynchronous, this kind of syntax is not possible. We needed to consider an alternative interface.

Problem Example 2: Loading Associations

When fetching associations, await needs to be written each time because there is a possibility of database access.

const theme = (await user.setting).theme;

In Active Record, associations are lazy-loaded, so database access may occur when fetching associations. If the user instance already has the setting cached, no database access occurs; otherwise, it does. This also necessitated reconsidering the interface due to usability issues.

Each of these issues could be somewhat resolved by designing the interface carefully. However, I felt that repeatedly making such adjustments was gradually leading the library’s usability away from the ideal. The asynchronous API was restricting the library's interface.

The Conceptual Shift to Synchronous APIs

Rails' Active Record abstracts database access processes by associating tables with model classes. However, making these APIs asynchronous means constantly being aware of the timing of database access, which hinders abstraction and reduces development efficiency.

Continuing with an asynchronous API to implement the ORM made me realize that achieving the same level of abstraction as Active Record would be difficult, and so would achieving high development efficiency, which was the initial goal.

So, I reconsidered the API design and thought there might be another approach.

I decided to question the assumption that "database access APIs in JavaScript/TypeScript must be asynchronous."

Synchronous API calls without Promises do not require await. If we could implement each API as a synchronous API rather than an asynchronous one, the aforementioned issues would not arise. There would be no need to worry about whether to add await to each method call, allowing a development experience closer to Active Record.

Thus, the next step was to answer the following questions:

Why do JS/TS database access libraries adopt asynchronous APIs?
Is it absolutely necessary to use asynchronous APIs?
Can an ORM be created using synchronous APIs?

Node.js Event Loop and Synchronous Processing

The goal of this ORM library is to provide a development experience similar to Ruby on Rails’ Active Record. Therefore, it is intended for server-side use, not for frontend use. The most common execution environment for server-side TypeScript (JavaScript) is Node.js. So, I investigated the challenges of using synchronous APIs in Node.js.

The most relevant information from Node.js official documentation includes:

Node.js uses a single-threaded, asynchronous I/O model, which achieves high performance by utilizing time waiting for I/O to perform other tasks. JavaScript and Node.js have the concept of an event loop, but synchronous processing can block the event loop, preventing other tasks from being processed during that time. This could potentially degrade system performance compared to using asynchronous processing.

The Downsides of Synchronous Processing and Mitigation Strategies

For example, if a web application handles HTTP requests only with synchronous APIs, it cannot accept other requests until the current one is completed. However, this behavior is common in other languages. In Ruby on Rails, for instance, a process typically cannot handle other requests until one request is completed.

Thus, while using synchronous APIs may lower performance compared to asynchronous Node.js applications, it is not necessarily inferior in performance compared to applications in other languages.

Moreover, this refers to the performance per thread. By running multiple processes or threads in parallel, overall system performance may not significantly decrease. Parallelizing server-side processing with multiple processes is very common in web applications. For instance, in Ruby, it's common to use application servers like Unicorn to run multiple processes.

Even in Node.js, processes can be run in parallel, and there are mechanisms to run certain tasks on separate threads without blocking the event loop . ¹
While using synchronous processing in Node.js may reduce performance per thread, system-level performance degradation can potentially be avoided through system architecture.

Additionally, in serverless environments like AWS Lambda, where handling multiple requests concurrently in a single process (container) is uncommon, synchronous processing may not impact performance significantly.

Prioritizing Development Efficiency Over System Performance

Ultimately, my goal is to have a framework for TypeScript with development efficiency comparable to Rails. What I prioritize is development efficiency, not system performance.

Many development environments prioritize development efficiency over system (per-thread) performance. If performance was the only concern, faster languages like C would always be chosen for server-side development. However, languages like PHP and Ruby, which are relatively slower, are also popular. This is because these languages and frameworks are considered to provide a more efficient development environment.

Adopting a Synchronous API in the New ORM

Based on the investigation, I have organized answers to the initial questions:

Why do JS/TS database access libraries adopt asynchronous APIs?
- To avoid blocking the JavaScript event loop. Blocking the event loop can lead to degraded system performance.
Is it absolutely necessary to use asynchronous APIs?
- Not necessarily. If the degradation in performance per thread is acceptable, synchronous APIs can be used. (And, as mentioned, there are ways to mitigate this downside through system architecture.)
Can an ORM be created using synchronous APIs?
- There seems to be no inherent restriction in JavaScript or Node.js preventing this.

If the ORM is designed with synchronous APIs, the main downside would be a degradation in (per-thread) performance. However, as discussed, this can be mitigated through system architecture. Therefore, weighing this downside against the benefit of improved development efficiency for library users, I concluded that the benefits of adopting synchronous APIs outweigh the downsides.

Thus, the new ORM, Accel Record, has adopted synchronous APIs despite being a TypeScript library.

Conclusion

In this article, I explained the background and reasons for adopting synchronous APIs in Accel Record.

First, it was challenging to achieve the ideal ORM interface with asynchronous APIs. Asynchronous APIs restricted the library's interface. This led to investigating whether a synchronous API could be adopted. Although there were concerns about system performance, considering the project's goals, we determined that the benefits (improved development efficiency) of realizing the ideal interface were significant.

To see how Accel Record achieves an ideal interface with synchronous APIs, please check out the Introduction to "Accel Record": A TypeScript ORM Using the Active Record Pattern or the README.

Cluster | Node.js v22.2.0 Documentation ↩

Seeking a Type-Safe Ruby on Rails in TypeScript, I Started Developing an ORM

koyopro — Tue, 11 Jun 2024 16:49:48 +0000

I am developing an ORM library for TypeScript called Accel Record. Recently, I published an article introducing this library, titled Introduction to "Accel Record": A TypeScript ORM Using the Active Record Pattern.

Next, I would like to explain why I decided to develop a new ORM for TypeScript.

Update (April 14, 2025)

For updates on the development progress, please check out the following article:

After a Year of Wanting a Typed Rails and Starting Development, I Released a Framework for TypeScript

Initial Motivation

As someone who uses Ruby on Rails for server-side development and TypeScript for front-end development, I often find myself thinking the following:

I want a framework for TypeScript with development efficiency comparable to Ruby on Rails.

This desire stems from wanting to use TypeScript for server-side development as well. The reasons are mainly as follows:

I want to develop the server-side with type safety.
I want to develop both the front-end and back-end in the same language to reduce context switching and learning costs.

This thought process seems common, and in fact, there are cases where TypeScript is adopted for server-side development for these reasons.

What Kind of Framework Do I Want?

So, what does a framework with development efficiency comparable to Ruby on Rails look like?

The requirements may vary from person to person, but in my case, I thought as follows:

It should be able to implement functionalities for common use cases in web application development with minimal code.

More specifically, I am looking for the following elements:

Based on developing MPA with SSR (not SPA)
Able to implement CRUD functions for RDB with minimal code
A framework that covers the MVC domain on the server-side

If such a framework existed, I believe server-side development with TypeScript could be as efficient as, if not more efficient than, using Ruby on Rails.

Existing Frameworks Were Not Satisfactory

I investigated whether a framework meeting the above requirements already existed.
The conclusion I reached was that there might not be a TypeScript framework that offers functionalities for server-side processes as efficiently and with as little code as Rails.
In general terms, existing TypeScript frameworks seem to focus more on routing and enhancing front-end/back-end integration. While they are rich in features related to View and Controller (in MVC terms), the Model part seems weaker compared to Rails.

Do We Need an ORM Like Active Record?

In Rails, the ORM handling the Model role is Active Record.
Of course, TypeScript also has ORMs, but Rails’ Active Record is more than just an ORM. It provides various functionalities related to the corresponding domain model, not just operations on DB records.

Rails is characterized by its ability to implement common functionalities with minimal code. This is possible because the model classes provided by Active Record have many features. They are tightly integrated with other parts like routing and controllers, resulting in high development efficiency.

From this perspective, I thought that to achieve the goal, TypeScript needs a highly functional ORM similar to Rails’ Active Record.

What Elements Should the ORM Have?

To provide an efficient development experience in TypeScript similar to Rails, I thought the ORM should have the following elements:

1. Active Record Pattern

It should adopt the Active Record pattern. This is because I want one class to handle not only operations on DB records but also features related to the corresponding domain model.
For instance, with an ORM adopting the Table Gateway pattern, the retrieved records are plain objects, making it difficult to attach methods related to the model.
Additionally, an Active Record pattern ORM would make it easier to integrate with features like routing and View as done in Rails.

2. Type Safety

Leveraging the advantages of TypeScript, the operations and query interface of the ORM should be type-safe.
The initial motivation was to develop the server-side with type safety, so sufficient type support is expected.

No Existing ORM Met the Requirements

Given the above considerations, I investigated existing ORMs but could not find one that was type-safe and adopted the Active Record pattern.

For example, the increasingly popular Prisma has high type safety but adopts the Table Gateway pattern.
The closest fit was TypeORM, which uses the Active Record pattern, but its type support is weaker compared to recent ORMs, and its release frequency has been low recently.

I Decided to Try Developing an ORM

Based on the above, I decided to start developing a type-safe ORM in TypeScript that adopts the Active Record pattern.
I wanted to try developing it to see if it was feasible and identify any potential challenges.

The subsequent development process will be detailed in another article, but ultimately, I published the new ORM as Accel Record.

Conclusion

In this article, I outlined why I decided to develop a new ORM for TypeScript.

The initial motivation was the desire for a framework in TypeScript with development efficiency comparable to Ruby on Rails. As I continued researching existing libraries, I realized the need for a type-safe ORM in TypeScript adopting the Active Record pattern.

Thus, I started development, and eventually released the library. To see what kind of ORM it has become, please check out Introduction to "Accel Record": A TypeScript ORM Using the Active Record Pattern and the README.

Introduction to "Accel Record": A TypeScript ORM Using the Active Record Pattern

koyopro — Tue, 04 Jun 2024 18:57:50 +0000

In this article, we'll briefly introduce Accel Record, an ORM for TypeScript that we're developing.

Overview of Accel Record

accel-record - npm

Accel Record is a type-safe, synchronous ORM for TypeScript.
It adopts the Active Record pattern, with an interface heavily influenced by Ruby on Rails' Active Record.

It uses Prisma for schema management and migration, allowing you to use your existing Prisma schema directly.

~~As of June 2024, it supports MySQL and SQLite, with plans to support PostgreSQL in the future.~~
MySQL, PostgreSQL, and SQLite are supported.

Features

Active Record pattern
Type-safe classes
Synchronous API
Validation
Native ESM
Support for MySQL, PostgreSQL, and SQLite

We will introduce some of these features in more detail below.

Usage Example

For example, if you define a User model as follows,

// prisma/schema.prisma
model User {
  id        Int    @id @default(autoincrement())
  firstName String
  lastName  String
  age       Int?
}

you can use it like this:

import { User } from "./models/index.js";

const user: User = User.create({
  firstName: "John",
  lastName: "Doe",
});

user.update({
  age: 26,
});

for (const user of User.all()) {
  console.log(user.firstName);
}

const john: User | undefined = User.findBy({
  firstName: "John",
  lastName: "Doe",
});

john?.delete();

You can also extend models to define custom methods.

// src/models/user.ts
import { ApplicationRecord } from "./applicationRecord.js";

export class UserModel extends ApplicationRecord {
  // Define a method to get the full name
  get fullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }
}

import { User } from "./models/index.js";

const user = User.create({
  firstName: "John",
  lastName: "Doe",
});

console.log(user.fullName); // => "John Doe"

For more detailed usage, see the README.

Active Record Pattern

Accel Record adopts the Active Record pattern.
Its interface is heavily influenced by Ruby on Rails' Active Record.
Those with experience in Rails should find it easy to understand how to use it.

Example of Creating and Saving Data

import { NewUser, User } from "./models/index.js";

// Create a User
const user: User = User.create({
  firstName: "John",
  lastName: "Doe",
});
console.log(user.id); // => 1

// You can also write it like this
const user: NewUser = User.build({});
user.firstName = "Alice";
user.lastName = "Smith";
user.save();
console.log(user.id); // => 2

Example of Retrieving Data

import { User } from "./models/index.js";

const allUsers = User.all();
console.log(`IDs of all users: ${allUsers.map((u) => u.id).join(", ")}`);

const firstUser = User.first();
console.log(`Name of the first user: ${firstUser?.firstName}`);

const john = User.findBy({ firstName: "John" });
console.log(`ID of the user with the name John: ${john?.id}`);

const does = User.where({ lastName: "Doe" });
console.log(`Number of users with the last name Doe: ${does.count()}`);

Type-safe Classes

Accel Record provides type-safe classes.
The query API also includes type information, allowing you to leverage TypeScript's type system.
Effective editor autocompletion and type checking help maintain high development efficiency.

A notable feature is that the type changes based on the model's state, so we'll introduce it here.

Accel Record provides types called NewModel and PersistedModel to distinguish between new and saved models.
Depending on the schema definition, some properties will allow undefined in NewModel but not in PersistedModel.
This allows you to handle both new and saved models in a type-safe manner.

import { User, NewUser } from "./models/index.js";

/*
Example of NewModel:
The NewUser type represents a model before saving and has the following type.

interface NewUser {
  id: number | undefined;
  firstName: string | undefined;
  lastName: string | undefined;
  age: number | undefined;
}
*/
const newUser: NewUser = User.build({});

/*
Example of PersistedModel:
The User type represents a saved model and has the following type.

interface User {
  id: number;
  firstName: string;
  lastName: string;
  age: number | undefined;
}
*/
const persistedUser: User = User.first()!;

By using methods like save(), you can convert a NewModel type to a PersistedModel type.

import { User, NewUser } from "./models/index.js";

// Prepare a user of the NewModel type
const user: NewUser = User.build({
  firstName: "John",
  lastName: "Doe",
});

if (user.save()) {
  // If save is successful, the NewModel is converted to a PersistedModel.
  // In this block, user is treated as a User type.
  console.log(user.id); // user.id is of type number
} else {
  // If save fails, the NewModel remains the same type.
  // In this block, user remains of type NewUser.
  console.log(user.id); // user.id is of type number | undefined
}

Synchronous API

Accel Record provides a synchronous API that does not use Promises or callbacks, even for database access.
This allows you to write simpler code without using await, etc.
This was mainly adopted to enhance application development efficiency.

By adopting a synchronous API, you can perform related operations intuitively, as shown below.

import { User, Setting, Post } from "./models/index.js";

const user = User.first()!;
const setting = Setting.build({ theme: "dark" });
const post = Post.build({ title: "Hello, World!" });

// Operations on hasOne associations are automatically saved
user.setting = setting;

// Operations on hasMany associations are also automatically saved
user.posts.push(post);

import { User } from "./models/index.js";

// Related entities are lazily loaded and cached
// You don't need to explicitly instruct to load related entities when fetching a user.
const user = User.first()!;

console.log(user.setting.theme); // setting is loaded and cached
console.log(user.posts.map((post) => post.title)); // posts are loaded and cached

Synchronous APIs have some drawbacks compared to implementations using asynchronous APIs, primarily related to performance.
We will discuss these trade-offs in a separate article. ¹

Validation

Like Ruby on Rails' Active Record, Accel Record also provides validation features.

You can define validations by overriding the validateAttributes method of the BaseModel.

// src/models/user.ts
import { ApplicationRecord } from "./applicationRecord.js";

export class UserModel extends ApplicationRecord {
  override validateAttributes() {
    // Validate that firstName is not empty
    this.validates("firstName", { presence: true });
  }
}

When using methods like save, validations are automatically executed, and save processing only occurs if there are no errors.

import { User } from "./models/index.js";

const newUser = User.build({ firstName: "" });
// If validation errors occur, save returns false.
if (newUser.save()) {
  // If validation errors do not occur, saving succeeds
} else {
  // If validation errors occur, saving fails
}

Conclusion

This concludes our brief introduction to Accel Record.
If you are interested, please check the links below for more details.

accel-record - npm
https://www.npmjs.com/package/accel-record

Seeking a Type-Safe Ruby on Rails in TypeScript, I Started Developing an ORM - DEV Community
https://dev.to/koyopro/seeking-a-type-safe-ruby-on-rails-in-typescript-i-started-developing-an-orm-1of5

Why We Adopted a Synchronous API for the New TypeScript ORM - DEV Community
https://dev.to/koyopro/why-we-adopted-a-synchronous-api-for-the-new-typescript-orm-1jm

Even Server-Side TypeScript Needs the Option to Avoid Asynchronous Processing - DEV Community
https://dev.to/koyopro/even-server-side-typescript-needs-the-option-to-avoid-asynchronous-processing-1opm

Why We Adopted a Synchronous API for the New TypeScript ORM ↩