@tahminator/sapling 1.5.0 → 1.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tahmid Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+# Sapling
+
+A lightweight library that brings some structure to Express.js
+
+## Table of Contents
+
+- [Why?](#why)
+- [Examples](#examples)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Features](#features)
+  - [Controllers](#controllers)
+  - [HTTP Methods](#http-methods)
+  - [Responses](#responses)
+  - [Error Handling](#error-handling)
+  - [Middleware](#middleware)
+  - [Redirects](#redirects)
+  - [Dependency Injection](#dependency-injection)
+  - [Custom Serialization](#custom-serialization)
+
+## Why?
+
+1. Express is great, but it can get really messy really quickly. Sapling lets you define controllers and routes using decorators instead of manually wiring everything up.
+
+2. I took a lot of inspiration from Spring, but I don't believe that it would be correct to try to force Express.js or Typescript to adopt OOP entirely, which leads me to my next point:
+    - The best reason to use Sapling is that you can also eject out of the object oriented environment and run regular functional Express.js without having to do anything extra or hacky.
+
+3. I prefer Sapling to other libraries like Nest.js because they are usually too heavy of an abstraction. I only want what would be helpful to improve development speed without getting in my way, nothing more & (ideally) nothing else.
+
+## Examples
+
+Check the `/example` folder for a basic todo app with database integration.
+
+Sapling is also powering one of my more complex projects with 600+ users in production, which you can view at [instalock-web](https://github.com/tahminator/instalock-web).
+
+## Install
+
+```bash
+# we <3 pnpm
+pnpm install @tahminator/sapling
+```
+
+## Quick Start
+
+```typescript
+import express from "express";
+import {
+  Sapling,
+  Controller,
+  GET,
+  POST,
+  ResponseEntity,
+  Class,
+} from "@tahminator/sapling";
+
+@Controller({ prefix: "/api" })
+class HelloController {
+  @GET()
+  getHello(): ResponseEntity<string> {
+    return ResponseEntity.ok().body("Hello world");
+  }
+}
+
+@Controller({ prefix: "/api/users" })
+class UserController {
+  @GET()
+  getUsers(): ResponseEntity<string[]> {
+    return ResponseEntity.ok().body(["Alice", "Bob"]);
+  }
+
+  @POST()
+  createUser(): ResponseEntity<{ success: boolean }> {
+    return ResponseEntity.status(HttpStatus.CREATED).body({ success: true });
+  }
+}
+
+// you still have full access of app to do whatever you want!
+const app = express();
+Sapling.registerApp(app);
+
+const controllers: Class<any>[] = [HelloController, UserController];
+controllers.map(Sapling.resolve).forEach((r) => app.use(r));
+
+app.listen(3000);
+```
+
+Hit `GET /api` for "Hello world" or `GET /api/users` for the user list.
+
+## Features
+
+### Controllers
+
+Use `@Controller()` to mark a class as a controller. Routes inside get a shared prefix if you want:
+
+```typescript
+@Controller({ prefix: "/users" })
+class UserController {
+  @GET("/:id")
+  getUser() {
+    /* ... */
+  }
+
+  @POST()
+  createUser() {
+    /* ... */
+  }
+}
+```
+
+### HTTP Methods
+
+Sapling supports the usual suspects:
+
+- `@GET(path?)`
+- `@POST(path?)`
+- `@PUT(path?)`
+- `@DELETE(path?)`
+- `@PATCH(path?)`
+- `@Middleware(path?)` - for middleware
+
+Path defaults to `"/"` if you don't pass one.
+
+### Responses
+
+`ResponseEntity` gives you a builder pattern for responses:
+
+```typescript
+@Controller({ prefix: "/users" })
+class UserController {
+  @GET("/:id")
+  getUser(): ResponseEntity<User> {
+    const user = findUser(id);
+    return ResponseEntity.ok().setHeader("X-Custom", "value").body(user);
+  }
+}
+```
+
+For status codes you can use `.ok()` (200) or `.status()` to define a specific status with the `HttpStatus` enum.
+
+You can also set custom status codes:
+
+```typescript
+@Controller({ prefix: "/api" })
+class CustomController {
+  @GET("/teapot")
+  teapot(): ResponseEntity<string> {
+    return ResponseEntity.status(HttpStatus.I_AM_A_TEAPOT).body("I'm a teapot");
+  }
+}
+```
+
+### Error Handling
+
+Use `ResponseStatusError` to handle bad control paths:
+
+```typescript
+@Controller({ prefix: "/users" })
+class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @GET("/:id")
+  async getUser(request: Request): ResponseEntity<User> {
+    const user = await this.userService.findById(request.params.id);
+
+    if (!user) {
+      throw new ResponseStatusError(HttpStatus.NOT_FOUND, "User not found");
+    }
+
+    return ResponseEntity.ok().body(user);
+  }
+}
+```
+
+Make sure to register an error handler middleware:
+
+```typescript
+Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
+  res.status(err.status).json({ error: err.message });
+});
+```
+
+### Middleware
+
+Load Express middleware plugins using `@Middleware()`:
+
+```typescript
+import { Controller, Middleware } from "@tahminator/sapling";
+import cookieParser from "cookie-parser";
+import { NextFunction, Request, Response } from "express";
+
+@MiddlewareClass() // works the same as @Controller, semantically different
+class CookieParserMiddleware {
+  private readonly plugin: ReturnType<typeof cookieParser>;
+
+  constructor() {
+    this.plugin = cookieParser();
+  }
+
+  @Middleware()
+  register(request: Request, response: Response, next: NextFunction) {
+    return this.plugin(request, response, next);
+  }
+}
+
+// Register it like any controller
+app.use(Sapling.resolve(CookieParserMiddleware));
+
+// You can also still choose to load plugins the Express.js way
+app.use(cookieParser());
+```
+
+### Redirects
+
+```typescript
+@Controller({ prefix: "/api" })
+class RedirectController {
+  @GET("/old-route")
+  redirect() {
+    return RedirectView.redirect("/new-route");
+  }
+}
+```
+
+### Dependency Injection
+
+Mark services with `@Injectable()` and inject them into controllers:
+
+```typescript
+@Injectable()
+class UserService {
+  getUsers() { ... }
+}
+
+@Controller({
+  prefix: "/users",
+  deps: [UserService]
+})
+class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @GET()
+  getAll() {
+    return ResponseEntity.ok().body(this.userService.getUsers());
+  }
+}
+```
+
+Injectables can also depend on other injectables:
+
+```typescript
+@Injectable()
+class Database {
+  query() { ... }
+}
+
+@Injectable([Database])
+class UserRepository {
+  constructor(private readonly db: Database) {}
+
+  findAll() {
+    return this.db.query("SELECT * FROM users");
+  }
+}
+```
+
+### Custom Serialization
+
+By default, Sapling uses `JSON.stringify` and `JSON.parse` for serialization. You can override these with custom serializers like [superjson](https://github.com/flightcontrolhq/superjson#readme) to automatically handle Dates, BigInts, and more:
+
+```typescript
+import superjson from "superjson";
+
+Sapling.setSerializeFn(superjson.stringify);
+Sapling.setDeserializeFn(superjson.parse);
+```
+
+This affects how `ResponseEntity` serializes response bodies and how request bodies are deserialized.
+
+## License
+
+MIT

package/dist/src/annotation/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./controller";
 export * from "./injectable";
 export * from "./route";
+export * from "./middleware";

package/dist/src/annotation/index.js

@@ -1,3 +1,4 @@
 export * from "./controller";
 export * from "./injectable";
 export * from "./route";
+export * from "./middleware";

package/dist/src/annotation/middleware.d.ts

@@ -0,0 +1,9 @@
+import { Controller } from "./controller";
+/**
+ * Used to define a middleware-only class.
+ *
+ * __NOTE:__ `@MiddlewareClass` works exactly the same as `@Controller`. As such, you
+ * can still register `@Route` and `@Middleware` methods, though you very well should not
+ * for the sake of semantics.
+ */
+export declare function MiddlewareClass(...args: Parameters<typeof Controller>): ClassDecorator;

package/dist/src/annotation/middleware.js

@@ -0,0 +1,11 @@
+import { Controller } from "./controller";
+/**
+ * Used to define a middleware-only class.
+ *
+ * __NOTE:__ `@MiddlewareClass` works exactly the same as `@Controller`. As such, you
+ * can still register `@Route` and `@Middleware` methods, though you very well should not
+ * for the sake of semantics.
+ */
+export function MiddlewareClass(...args) {
+    return Controller(...args);
+}

package/dist/src/annotation/route.js

@@ -8,7 +8,7 @@ export function _Route({ method, path = "", }) {
         var _a;
         const ctor = target.constructor;
         const list = (_a = _routeStore.get(ctor)) !== null && _a !== void 0 ? _a : [];
-        list.push({ method, path, fnName: String(propertyKey) });
+        list.push({ method, path: path !== null && path !== void 0 ? path : "", fnName: String(propertyKey) });
         _routeStore.set(ctor, list);
     };
 }

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "@tahminator/sapling",
-  "version": "1.5.0",
+  "version": "1.5.3",
+  "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
+  "repository": {
+    "url": "git+https://github.com/tahminator/sapling.git"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "pnpm run build",
     "build": "rm -rf dist && tsc"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "packageManager": "pnpm@10.12.4",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
   "files": [
     "/dist"
   ],
+  "keywords": [],
+  "license": "ISC",
+  "packageManager": "pnpm@10.12.4",
   "dependencies": {
     "@types/express": "^5.0.6",
     "express": "^5.2.1"