doc update
authorJustin Wind <justin.wind+git@gmail.com>
Thu, 20 Jul 2023 22:04:14 +0000 (15:04 -0700)
committerJustin Wind <justin.wind+git@gmail.com>
Thu, 20 Jul 2023 22:06:28 +0000 (15:06 -0700)
README.md
package.json

index c67a282dc8bd12b015ce86c630edafa186413318..7056184ac2f0341b2477190fd357482e34f632f7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
 # Another In-House API Server Frameworklet
 
 # Another In-House API Server Frameworklet
 
-I just wanted a basic little API server for toy projects, without having to park a container-ship of modules under it.
+I just wanted a basic little API server for toy projects, without having to park a container-ship of modules under them.
 
 
-This is in no way intended to replace any mature, full-featured framework.  It is spartan in some aspects, brings some unexpected baggage in others, makes some questionable design decisions, has the occasional opinion, and is likely somewhat idiosyncratic from an outside perspective.
+So here is a low-dependency toy web server framework.  It includes a simple router, some bundled middlewares such as body-parsing and content-negotiation, convenience functions, and a number of opinions.
 
 
-This was also created as a means to gain a better understanding of the existing web framework ecosystem by fussing with all the involved fiddly bits, a priori, from the bottom up.
+This is not drop-in compatible with the industry standards, and is in no way intended to replace any mature, full-featured framework.  It is spartan in some aspects, brings some unexpected baggage in others, probably makes some questionable design decisions, and is likely somewhat idiosyncratic from an outside perspective.
 
 The primary design goals are:
 
 The primary design goals are:
-- self-contained: as few external dependencies as feasible
-- not-infinitely-extensible: only does the things it needs to do as dictated by the projects it is used in
-- learning from mistakes made along the way
+- self-contained: Uses as few external dependencies as are feasible.
+- not-infinitely-extensible: The projects it gets used in drive the feature set.
+- learning from mistakes made along the way: This was partly created as a means to gain a better understanding of the existing web framework ecosystem by fussing with all the involved fiddly bits, a priori, from the bottom up.
 
 ## Getting Started
 
 
 ## Getting Started
 
@@ -20,15 +20,18 @@ Within the server request handler:
 
 Within the application implementation:
 - `on(method, urlPath, handler)` declares a thing to do when a request matches.
 
 Within the application implementation:
 - `on(method, urlPath, handler)` declares a thing to do when a request matches.
-- `preHandler(req, res, ctx)` can be overridden to do something to every request before it is handled.
-
-Handled content types can be extended by overriding:
-- `parseBody(contentType, ctx)` for incoming types.
-- `renderError(contentType, err)` for outgoing types.
+- `preHandler(req, res, ctx)` is called on every request before the handler function, by default adding some request information to the context.
 
 Within your handlers:
 
 Within your handlers:
+- parameters from the route and query, along with other metadata, are set in each context.
 - `setResponseType(responseTypes, req, res, ctx)` can be called to negotiate content types.
 - `setResponseType(responseTypes, req, res, ctx)` can be called to negotiate content types.
-- `async ingestBody(req, res, ctx)` will parse request body data.
+- `async ingestBody(req, res, ctx, options)` will parse request body data.
 - throw an `Error.ResponseError` with an `Enum.ErrorResponse` for a simple status code with optional details, when something goes awry.
 
 - throw an `Error.ResponseError` with an `Enum.ErrorResponse` for a simple status code with optional details, when something goes awry.
 
-Parameters and metadata are set in each request context.
+Negotiated content types can be extended by overriding:
+- `parseBody(contentType, ctx)` for incoming types.
+- `renderError(contentType, err)` for outgoing types.
+
+Some handler functions are provided:
+- `handlerGetStaticFile(req, res, ctx, file)` will return a file from a configured directory, and also supports including CERN-style header metadata.  It will also serve pre-encoded variations (e.g `.gz` or `.br`) if available and requested.
+- `handlerRedirect(req, res, ctx, newPath, statusCode)` will return a redirect response.
index 36b32087d0024ef0a09f3f393e9336204aa67524..dd6cf7fad7ef19b222b87044fffd3ba3119b1dea 100644 (file)
@@ -1,7 +1,7 @@
 {
   "name": "@squeep/api-dingus",
   "version": "1.2.9",
 {
   "name": "@squeep/api-dingus",
   "version": "1.2.9",
-  "description": "A minimal API server framework",
+  "description": "An API server framework",
   "main": "index.js",
   "scripts": {
     "coverage": "nyc --all npm test",
   "main": "index.js",
   "scripts": {
     "coverage": "nyc --all npm test",