yedra 0.9.0

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2024 WeMakeFuture AG
+
+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,326 @@
+# @wemakefuture/y
+
+## Table Of Contents
+
+- [Introduction](#introduction)
+- [Getting Started](#getting-started)
+- [Endpoints](#endpoints)
+- [Apps](#apps)
+- [Error Handling](#error-handling)
+- [Schemas](#schemas)
+- [HTTP Client](#http-client)
+- [Paths](#paths)
+- [Changelog](#changelog)
+
+## Introduction
+
+y is a simple web framework for TypeScript. It includes a validation library
+similar to Zod, and a simple route system similar to express. y is very
+opinionated and not suitable for all use cases, e.g. since it doesn't provide
+good support for custom middleware or data formats other than JSON.
+
+Instead, it makes it easy to build well-documented software: y supports
+automatic generation of OpenAPI documentation for all endpoints. This includes
+generating JSON schemas for all request and response bodies that are specified
+using y schemas.
+
+## Getting Started
+
+First, install y with your favorite package manager:
+
+```bash
+npm install @wemakefuture/y
+yarn add @wemakefuture/y
+bun add @wemakefuture/y
+```
+
+Then, create your first endpoint in `src/routes/up.ts`:
+
+```ts
+import { y } from "@wemakefuture/y";
+
+export default y.endpoint("/up", {
+  summary: "Get server status.",
+  method: "GET",
+  query: y.object({}),
+  headers: y.object({}),
+  req: y.object({}),
+  res: y.object({ message: y.string() }),
+  do(req) {
+    return {
+      body: {
+        message: "Healthy.",
+      },
+    };
+  },
+});
+```
+
+And add this to `src/index.ts`:
+
+```ts
+import { y } from "@wemakefuture/y";
+
+y.app(`${__dirname}/routes`).then((app) => {
+  app.listen(3000);
+});
+```
+
+This starts a server with all endpoints in `src/routes` and listens on
+port 3000.
+
+## Endpoints
+
+The core construct of y is the `endpoint`. Endpoints are created like this:
+
+```ts
+import { y } from "@wemakefuture/y";
+
+export default y.endpoint("/up", {
+  summary: "Get server status.",
+  description:
+    "Returns a 200 status code if the server is running, otherwise a 502.",
+  method: "GET",
+  query: y.object({}),
+  headers: y.object({}),
+  req: y.object({}),
+  res: y.object({
+    message: y.string(),
+  }),
+  do(req) {
+    if (isHealthy()) {
+      return {
+        status: 200,
+        body: {
+          message: "Healthy.",
+        },
+      };
+    }
+    return {
+      status: 502,
+      body: {
+        message: "Not healthy.",
+      },
+    };
+  },
+});
+```
+
+This is a lot, so let's break it down:
+
+1. `/up` is the HTTP endpoint [path](#paths).
+2. `summary` is a simple summary of the endpoint. This will appear as the title
+   in the OpenAPI documentation.
+3. `description` is an optional longer description that will appear after
+   expanding the OpenAPI documentation for this endpoint.
+4. `method` is the HTTP method used to access the endpoint. Options are `GET`,
+   `POST`, `PUT`, and `DELETE`.
+5. `query` is the schema for the query parameters.
+6. `headers` is the schema for the HTTP headers.
+7. `req` is the schema for the request body. This should be empty for `GET` and
+   `POST`.
+8. `res` is the schema for the response body.
+9. `do` is the function that will actually be executed. It can be either sync or
+   async, and must return a response body, and optionally status codes and
+   headers.
+
+Schemas are described in more detail [here](#schemas). In more complex
+endpoints, [error handling](#error-handling) is also an important topic.
+
+Inside the `do` function, the request data can be accessed using the `req`
+parameter.
+
+1. `req.body` is the validated request body, matching the schema specified for
+   the endpoint.
+2. `req.headers` is just like `req.query`, but for headers.
+3. `req.http` is a request-specific HTTP client, which is described in detail
+   [here](#http-client).
+4. `req.log` is a request-specific logger. Currently, the logger isn't used for
+   anything and just prints everything to the console, but that will change in
+   the future.
+5. `req.params` are the parameters extracted from the path. Unfortunately, they
+   are not type-checked statically.
+6. `req.query` is the typed object containing all query parameters. If the query
+   parameters do not match the schema specified for the endpoint, an error is
+   raised.
+7. `req.url` is the HTTP path, so it does not include the hostname, and starts
+   with `/`.
+
+## Apps
+
+Endpoints are always part of an entire application. With y, you create an
+application like this:
+
+```ts
+const app = await y.app(`${__dirname}/routes`);
+```
+
+This will automatically find all endpoints in the provided directory. Right now,
+all `.ts` and `.js` files are loaded, except for any `.test.ts`, `.schema.ts`,
+`.util.ts`, `.d.ts`, `.test.js`, `.schema.js`, or `.util.js` files. Only the
+default export is considered as an endpoint, so every endpoint will need to be
+put into its own file. The `routes` path should be absolute. There is currently
+no way to add endpoints manually to an application.
+
+Once the application is created, it can be started like this:
+
+```ts
+const context = app.listen(3000);
+```
+
+This starts an HTTP server and listens on port 3000. The `context` that is
+returned can be used for stopping the server again:
+
+```ts
+await context.stop();
+```
+
+This stops the server, but still continues to serve all current connections.
+Once every connection is closed, the method returns.
+
+Apps can also be used to generate OpenAPI documentation:
+
+```ts
+const docs = app.docs({
+  info: {
+    title: "My title.",
+    description: "My description.",
+    version: "1.0.0",
+  },
+  servers: [
+    {
+      url: "prod.example.com",
+      description: "The production server.",
+    },
+  ],
+});
+console.log(docs);
+```
+
+## Schemas
+
+To make y mostly typesafe, query parameters, headers, and the request and
+response bodies are specified using schemas. If you have worked with Zod,
+schemas should be very familiar.
+
+There is a large number of functions that create a schema. Some of them take
+subschemas, others can be configured using methods called on the schemas. In all
+cases, the schema itself is immutable, and modifying functions like
+`.optional()` always create a new schema instead of modifying the existing one.
+The schemas should be very self-explanatory in general, and contain
+documentation comments. The best way to learn is to try them! Here is a list of
+all schemas:
+
+- y.array
+- y.boolean
+- y.date
+- y.enum
+- y.intersection
+- y.number
+- y.object
+- y.record
+- y.string
+- y.undefined
+- y.union
+- y.unknown
+
+These are the same names as the schemas in Zod. Some schemas, like `z.any` in
+Zod, won't be added to y, since using any leads to lots of type unsafety.
+Instead, use `y.unknown` and use explicit type-checking.
+
+There is also the more general `y.BodyType`. All of the above schemas are
+subclasses of `y.BodyType`, but there are also:
+
+- y.raw, which accepts any raw buffer with the specified content type
+- y.either, which works just like y.union, except it may also contain a y.raw
+
+Schemas can be passed to [endpoints](./endpoints.md) for validation, but you can
+use them to validate things yourself, too. You can do that with the `y.parse`
+function. It takes an unknown value and returns a typed and parsed value, or
+throws a `y.ValiationError`.
+
+If you need to use the type of a `y.BodyType`, you can do this using
+`y.Typeof<typeof bodyType>`. In this case, `typeof bodyType` is the TypeScript
+type of the schema itself, and `y.Typeof` turns that into the parsed type.
+
+## Error Handling
+
+It is generally possible to return any status code from an endpoint, including
+status codes that indicate failure. However, it is often simpler to just throw
+an error, especially in nested method calls. To reduce boilerplate code
+associated with catching these errors, y automatically handles errors derived
+from `y.HttpError`, and returns their message and status code as an HTTP
+response. There are some predefined error classes:
+
+- `y.BadRequestError`
+- `y.UnauthorizedError`
+- `y.PaymentRequiredError`
+- `y.ForbiddenError`
+- `y.NotFoundError`
+- `y.ConflictError`
+
+If any other error is thrown inside an endpoint and not caught, y will
+automatically return a 500 response, with the message `Internal Server Error`.
+This is supposed to prevent accidental leakage of sensitive information.
+
+## HTTP Client
+
+y contains a small embedded HTTP client that directly interfaces with the
+logger. It is similar to Axios, but based on `fetch`. You can access the HTTP
+client using `req.http`, the methods are fairly self-explanatory.
+
+## Paths
+
+HTTP paths are used for specifying how the endpoint can be reached. They always
+start with `/`, and can contain multiple segments, each separated using `/` from
+the others. Segments can only contain lower-case letters, digits and hyphens.
+Segments can be optional, in which case they are followed by `?`. Optional
+segments must be at the end of the path, i.e. they may not be followed by
+non-optional segments. Segments can also be parameters, in which case they are
+preceded by `:`. This means they can match any segment.
+
+All of these rules are checked automatically once creating the path. If you want
+to check a path programmatically, you can use `y.validatePath`, which checks the
+path and throws an exception if it is invalid.
+
+The path parameters can be accessed inside [endpoints](./endpoints.md) using
+`req.params`.
+
+## Changelog
+
+y generally tries to follow a semantic versioning model. Right now, y is
+pre-1.0, so breaking changes can occur on every minor release.
+
+- 0.8.0 - Removed `identity` encoding, changed error field to `errorMessage`
+- 0.7.3 - Changed `accept-encoding` for `y.Http` to `identity` to prevent memory leak
+- 0.7.2 - Added time and connection count to connection log
+- 0.7.1 - Made headers on test service methods optional
+- 0.7.0 - Added test service and env parser
+- 0.6.7 - Fixed failed 0.6.6 release
+- 0.6.6 - Made `request` method of `y.Http` public
+- 0.6.5 - Fixed crash when validation error occurs
+- 0.6.4 - Added changelog and custom category option for endpoints
+- 0.6.3 - Updated documentation and fixed NodeJS compatibility
+- 0.6.2 - Fixed auto-importing of utility files
+- 0.6.1 - Fixed auto-import error
+- 0.6.0 - Replaced `y.router` with `y.app`, removed CLI completely
+- 0.5.0 - Removed need for `y fix`
+- 0.4.1 - Updated `y init` command
+- 0.4.0 - Added listen context to correctly terminate server
+- 0.3.11 - Added basic way to stop server after `y.listen`
+- 0.3.10 - Improved OpenAPI generation
+- 0.3.9 - Fixed parsing of empty JSON body
+- 0.3.8 - Fixed incorrect NPM version
+- 0.3.7 - Added `y doc` command
+- 0.3.6 - Added `req.http` client
+- 0.3.5 - Added log on each request
+- 0.3.4 - Fixed endpoint result schema
+- 0.3.3 - Fixed `y.either` export status
+- 0.3.2 - Added `y.either`
+- 0.3.1 - Fixed request body parsing
+- 0.3.0 - Added `y.raw`
+- 0.2.1 - Fix for `y fix` command
+- 0.2.0 - Added NodeJS support and CLI interface
+- 0.1.2 - Fixed y.number() minimum and maximum checks
+- 0.1.1 - Added test cases, documentation and license
+- 0.1.0 - Initial release

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import * as y from './lib';
+export { y };

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.y = void 0;
+const y = require("./lib");
+exports.y = y;

package/dist/lib.d.ts

@@ -0,0 +1,28 @@
+export { type EndpointOptions, type EndpointRequest, type EndpointResponse, endpoint, } from './routing/endpoint';
+export { HttpError, BadRequestError, UnauthorizedError, PaymentRequiredError, ForbiddenError, NotFoundError, ConflictError, } from './routing/errors';
+export { type Context } from './routing/listen';
+export { Log } from './routing/log';
+export { type Endpoint, app } from './routing/app';
+export declare const validatePath: (path: string) => void;
+export { TestService } from './routing/test';
+export { parseEnv } from './routing/env';
+export { route } from './routing/route';
+export { array } from './validation/array';
+export { boolean } from './validation/boolean';
+export { date } from './validation/date';
+export { _enum as enum } from './validation/enum';
+export { ValidationError } from './validation/error';
+export { intersection } from './validation/intersection';
+export { number } from './validation/number';
+export { object } from './validation/object';
+export { record } from './validation/record';
+export { Schema } from './validation/schema';
+export { BodyType, type Typeof } from './validation/body';
+export { raw } from './validation/raw';
+export { none } from './validation/none';
+export { either } from './validation/either';
+export { HttpResponse, HttpRequestError, Http } from './routing/http';
+export { string } from './validation/string';
+export { _undefined as undefined } from './validation/undefined';
+export { union } from './validation/union';
+export { unknown } from './validation/unknown';

package/dist/lib.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unknown = exports.union = exports.undefined = exports.string = exports.Http = exports.HttpRequestError = exports.HttpResponse = exports.either = exports.none = exports.raw = exports.BodyType = exports.Schema = exports.record = exports.object = exports.number = exports.intersection = exports.ValidationError = exports.enum = exports.date = exports.boolean = exports.array = exports.route = exports.parseEnv = exports.TestService = exports.validatePath = exports.app = exports.Log = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.PaymentRequiredError = exports.UnauthorizedError = exports.BadRequestError = exports.HttpError = exports.endpoint = void 0;
+const path_1 = require("./routing/path");
+// routing
+var endpoint_1 = require("./routing/endpoint");
+Object.defineProperty(exports, "endpoint", { enumerable: true, get: function () { return endpoint_1.endpoint; } });
+var errors_1 = require("./routing/errors");
+Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return errors_1.HttpError; } });
+Object.defineProperty(exports, "BadRequestError", { enumerable: true, get: function () { return errors_1.BadRequestError; } });
+Object.defineProperty(exports, "UnauthorizedError", { enumerable: true, get: function () { return errors_1.UnauthorizedError; } });
+Object.defineProperty(exports, "PaymentRequiredError", { enumerable: true, get: function () { return errors_1.PaymentRequiredError; } });
+Object.defineProperty(exports, "ForbiddenError", { enumerable: true, get: function () { return errors_1.ForbiddenError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "ConflictError", { enumerable: true, get: function () { return errors_1.ConflictError; } });
+var log_1 = require("./routing/log");
+Object.defineProperty(exports, "Log", { enumerable: true, get: function () { return log_1.Log; } });
+var app_1 = require("./routing/app");
+Object.defineProperty(exports, "app", { enumerable: true, get: function () { return app_1.app; } });
+const validatePath = (path) => {
+    new path_1.Path(path);
+};
+exports.validatePath = validatePath;
+var test_1 = require("./routing/test");
+Object.defineProperty(exports, "TestService", { enumerable: true, get: function () { return test_1.TestService; } });
+var env_1 = require("./routing/env");
+Object.defineProperty(exports, "parseEnv", { enumerable: true, get: function () { return env_1.parseEnv; } });
+var route_1 = require("./routing/route");
+Object.defineProperty(exports, "route", { enumerable: true, get: function () { return route_1.route; } });
+// validation
+var array_1 = require("./validation/array");
+Object.defineProperty(exports, "array", { enumerable: true, get: function () { return array_1.array; } });
+var boolean_1 = require("./validation/boolean");
+Object.defineProperty(exports, "boolean", { enumerable: true, get: function () { return boolean_1.boolean; } });
+var date_1 = require("./validation/date");
+Object.defineProperty(exports, "date", { enumerable: true, get: function () { return date_1.date; } });
+var enum_1 = require("./validation/enum");
+Object.defineProperty(exports, "enum", { enumerable: true, get: function () { return enum_1._enum; } });
+var error_1 = require("./validation/error");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return error_1.ValidationError; } });
+var intersection_1 = require("./validation/intersection");
+Object.defineProperty(exports, "intersection", { enumerable: true, get: function () { return intersection_1.intersection; } });
+var number_1 = require("./validation/number");
+Object.defineProperty(exports, "number", { enumerable: true, get: function () { return number_1.number; } });
+var object_1 = require("./validation/object");
+Object.defineProperty(exports, "object", { enumerable: true, get: function () { return object_1.object; } });
+var record_1 = require("./validation/record");
+Object.defineProperty(exports, "record", { enumerable: true, get: function () { return record_1.record; } });
+var schema_1 = require("./validation/schema");
+Object.defineProperty(exports, "Schema", { enumerable: true, get: function () { return schema_1.Schema; } });
+var body_1 = require("./validation/body");
+Object.defineProperty(exports, "BodyType", { enumerable: true, get: function () { return body_1.BodyType; } });
+var raw_1 = require("./validation/raw");
+Object.defineProperty(exports, "raw", { enumerable: true, get: function () { return raw_1.raw; } });
+var none_1 = require("./validation/none");
+Object.defineProperty(exports, "none", { enumerable: true, get: function () { return none_1.none; } });
+var either_1 = require("./validation/either");
+Object.defineProperty(exports, "either", { enumerable: true, get: function () { return either_1.either; } });
+var http_1 = require("./routing/http");
+Object.defineProperty(exports, "HttpResponse", { enumerable: true, get: function () { return http_1.HttpResponse; } });
+Object.defineProperty(exports, "HttpRequestError", { enumerable: true, get: function () { return http_1.HttpRequestError; } });
+Object.defineProperty(exports, "Http", { enumerable: true, get: function () { return http_1.Http; } });
+var string_1 = require("./validation/string");
+Object.defineProperty(exports, "string", { enumerable: true, get: function () { return string_1.string; } });
+var undefined_1 = require("./validation/undefined");
+Object.defineProperty(exports, "undefined", { enumerable: true, get: function () { return undefined_1._undefined; } });
+var union_1 = require("./validation/union");
+Object.defineProperty(exports, "union", { enumerable: true, get: function () { return union_1.union; } });
+var unknown_1 = require("./validation/unknown");
+Object.defineProperty(exports, "unknown", { enumerable: true, get: function () { return unknown_1.unknown; } });

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "yedra",
+  "version": "0.9.0",
+  "repository": "github:0codekit/yedra",
+  "main": "dist/index.js",
+  "devDependencies": {
+    "@biomejs/biome": "^1.8.3",
+    "@types/bun": "^1.1.6",
+    "@types/node": "^20.14.10",
+    "typescript": "^5.5.3"
+  },
+  "bugs": "https://github.com/0codekit/yedra/issues",
+  "contributors": ["Justus Zorn <jzorn@wemakefuture.com>"],
+  "description": "A TypeScript web framework with OpenAPI generation.",
+  "keywords": ["typescript", "web", "http", "schema", "validation", "openapi"],
+  "license": "MIT",
+  "files": ["./dist/*"],
+  "scripts": {
+    "check": "biome check src/*"
+  },
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "glob": "^10.4.5"
+  }
+}