jxp 3.0.0 → 4.0.0

package/docs/installation.md

@@ -4,27 +4,31 @@ JXP would typically run as a stand-alone server, although you can include it as
 
 ## Requirements
 
-JXP runs on [Node JS](https://nodejs.org/en/). We support Node v10 and above, and recommend Node v16. It has been tested up to Node v17.
+JXP runs on [Node.js](https://nodejs.org/en/). **Node.js 22 or newer is required** (`engines.node` is `>=22.0.0` in the package). We recommend the current Node 22 LTS release.
 
-JXP requires a [Mongo](https://www.mongodb.com/) database server to connect to. You can host your own, or we also support connecting to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), which has a free tier if you don't want to have Mongo running locally. 
+JXP requires a [MongoDB](https://www.mongodb.com/) database server to connect to. You can host your own, or connect to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), which has a free tier if you don't want Mongo running locally.
 
-JXP will also take advantage of Memcache if you have it installed, although it's not a requirement. We can use a local or external Memcache server.
+Optional in-process response caching is available via environment variables (see [Caching](caching.md)). No external Memcache server is required.
 
-If you want to send out forgotten password links, you'll need an SMTP server you can connect to.
+If you want to send forgotten-password links, configure SMTP on your `JXP()` options object (see [Configuration](configuration.md#smtp-and-password-recovery)).
+
+### JXP 4
+
+JXP 4 is implemented in TypeScript and published as compiled JavaScript in `dist/`. The npm package includes a prebuilt `dist/`; `npm install jxp` does not compile from source. Cloning the repo and running `npm install` builds automatically when `src/` is present. Consumer apps still define models as `*_model.js` files in `MODEL_DIR`.
 
 ## Running on Docker
 
-You can run JXP on Docker using Docker Compose. Just run `docker-compose up -d` and it should Just Work (tm).
+The repository includes `Dockerfile` and `docker-compose.yml`. Review those files and align environment variables with [Configuration](configuration.md) (`MONGO_CONNECTION_STRING` or `MONGODB_*` vars) before running `docker compose up -d`.
 
 ## Installing the easy way
 
-JXP has a helper that will set up and configure an instance for you. 
+JXP has a helper that will set up and configure an instance for you.
 
 First, install JXP globally:
 
 `npm install --global jxp`
 
-Now run `jxp-setup <directory>` and follow the prompts. This will install the necessary files, give you a few models to get started, and help you set up an admin username and password. 
+Now run `jxp-setup <directory>` and follow the prompts. This will install the necessary files, give you a few models to get started, and help you set up an admin username and password.
 
 Once the setup is complete, use `npm start` to start the server.
 
@@ -42,7 +46,8 @@ Then include in your project:
 
 NOTE: All the `/setup` endpoints will only run if the user table is empty to ensure that you can't overwrite an existing installation.
 
-You can set up a first user using the `/setup` endpoint, with the following default properties that you can override:
+You can set up a first user using the `/setup` endpoint (GET or POST), with the following default properties that you can override:
+
 ```js
 {
     email: "admin@example.com",
@@ -51,7 +56,8 @@ You can set up a first user using the `/setup` endpoint, with the following defa
 }
 ```
 
-Response: 
+Response:
+
 ```js
 {
   status: "success",
@@ -61,7 +67,7 @@ Response:
 }
 ```
 
-You can scaffold an entire system by using the `/setup/data` endpoint. This writes directly to the database, and doesn't go through the API, so be careful -- features like the automatic password encryption will not take effect. You also need to use the collection names, not the model names, eg. the `user` model becomes `users`.
+You can scaffold an entire system by using the `/setup/data` endpoint. This writes directly to the database, and doesn't go through the API, so be careful — features like automatic password encryption will not take effect. You also need to use the collection names, not the model names, eg. the `user` model becomes `users`.
 
 ```js
 {
@@ -76,22 +82,21 @@ You can scaffold an entire system by using the `/setup/data` endpoint. This writ
 ```
 
 Response:
+
 ```js
 {
-  status: 'success',
+  status: "success",
   results: {
     users: {
-      result: [Object],
-      ops: [Array],
+      acknowledged: true,
       insertedCount: 2,
-      insertedIds: [Object]
+      insertedIds: { ... }
     },
     tests: {
-      result: [Object],
-      ops: [Array],
+      acknowledged: true,
       insertedCount: 1,
-      insertedIds: [Object]
+      insertedIds: { ... }
     }
   }
 }
-```
+```

package/docs/permissions.md

@@ -3,29 +3,46 @@
 ## Access Control
 
 You can set permissions on each model for user groups which you can define yourself. There are also a few special groups:
+
 * `all` -- All users, whether they authenticate or not.
-* `owner` -- The user who created an item. This requires the model to have a `_owner_id` property (see the above example).
+* `owner` -- The user who created an item. This requires the model to have a `_owner_id` property (added automatically by JXPSchema).
 * `user` -- Any authenticated user.
 * `admin` -- Any admin user.
 
 Each group can have one, some or all of the following permissions:
+
 * `c` -- Create -- the ability to create a new record (a POST operation)
 * `r` -- Retrieve -- the ability to read a record or all records (a GET operation)
 * `u` -- Update -- the ability to update an existing record (a PUT operation)
-* `d` -- Delete -- the ability to delete an existin record (a DELETE operation)
+* `d` -- Delete -- the ability to delete an existing record (a DELETE operation)
 
-The permissions are defined in the model as follows:
+The permissions are defined in the schema constructor options (preferred):
+
+```js
+const TestSchema = new JXPSchema({
+    foo: String,
+}, {
+    perms: {
+        admin: "crud",
+        owner: "rud",
+        user: "cr",
+        all: "r",
+    },
+});
+```
+
+Alternatively, after creating the schema:
 
 ```js
 TestSchema.set("_perms", {
-    admin: "crud", // CRUD = Create, Retrieve, Update and Delete
+    admin: "crud",
     owner: "rud",
     user: "cr",
-    all: "r" // Unauthenticated users will be able to read from test, but that is all
+    all: "r",
 });
 ```
 
-In this case, the admin and record owner have full permissions. (We don't need to set "create" for the owner, obvz.) An authenticated user can create and retrive records. Everyone can read everything.
+In this case, the admin and record owner have full permissions. (We don't need to set "create" for the owner, obvz.) An authenticated user can create and retrieve records. Everyone can read everything.
 
 To make a model completely private, just don't set the perms.
 
@@ -36,32 +53,29 @@ You can add and remove groups to a user with the `/groups/:user_id` endpoint. Th
 * GET gets all the groups for the user
 * PUT adds a group
 * POST rewrites the user's groups
-* DELETE deletes the matching group  
+* DELETE deletes the matching group
 
 The field needs to be named `group`. You can even have an array of groups, eg. `group[0]`, `group[1]` etc.
 
 ***Example***
 
-Note that you'll need to authenticate as an admin through one of the methods described for these examples
+Note that you'll need to authenticate as an admin through one of the methods described in [Authentication](authentication.md).
 
 Set the user's group to `test`
 
 ```
-curl -X POST -F "group=test" "http://localhost:3001/groups/5485bd62fbad8791660d2658"
+curl -X POST -F "group=test" "http://localhost:4001/groups/5485bd62fbad8791660d2658"
 ```
 
-Add the groups `test1` and `test2`
+Add the groups `test0` and `test1`
 
 ```
-curl -X PUT -F "group[0]=test0" -F "group[1]=test1" "http://localhost:3001/groups/5485bd62fbad8791660d2658"
+curl -X PUT -F "group[0]=test0" -F "group[1]=test1" "http://localhost:4001/groups/5485bd62fbad8791660d2658"
 ```
 
 ### Adding custom permission logic
 
-Maybe you want to do some more checks on permissions than the "crud" we offer. You can catch
-the user object in your model as a virtual attribute. (I suppose you could use a real Mixed attribute too.)
-
-Eg.
+Maybe you want to do more checks on permissions than the built-in `crud` strings. You can capture the user object in your model as a virtual attribute (JXP sets `__user` on documents during API operations):
 
 ```js
 var sender;
@@ -71,10 +85,10 @@ LedgerSchema.virtual("__user").set(function(usr) {
 });
 ```
 
-And then later, say in your pre- or post-save...
+And then later, say in your pre- or post-save:
 
 ```js
-(!sender.admin)) {
-    return next(new Error( "Verboten!"));
+if (!sender.admin) {
+    return next(new Error("Verboten!"));
 }
-```
+```

package/docs/queries.md

@@ -2,24 +2,28 @@
 
 You can post complex queries through the `/query/<modelname>` endpoint, such as doing `$and` or `$or` queries, or regex expressions.
 
-Wrap it all in a "query" variable and POST it as JSON.
+Dangerous operators (e.g. `$where`, `$function`) are rejected. Per-model opt-out: `advanced_queries: { query: false }` in schema options.
+
+Wrap your MongoDB filter in a `"query"` object and POST it as JSON. URL query parameters for `GET /api/<model>` also work here: `limit`, `page`, `sort`, `populate`, `filter`, `autopopulate`, and `fields`. See [The Restful API](api.md) for those features.
 
 Eg.
 
-```JSON
+```json
 {
     "query": {
         "$and": [
-            { 
+            {
                 "foo": {
                     "$regex": "foo",
                     "$options": "i"
                 }
             },
-            {	
+            {
                 "bar": "Bar"
             }
         ]
     }
 }
-```
+```
+
+Note: the top-level `search` query parameter does not apply to `/query` — express search conditions inside the posted `query` object instead.

package/docs/schemas.md

@@ -10,9 +10,9 @@ The schemas are based on Mongoose, so anything you can do with a [Mongoose schem
 
 ## Defining a schema
 
-Schemas are all found in the `/models` directory, and have the format `/models/<name>_model.js`. Each schema represents a collection in Mongo, with the Mongo collection name being the plural of the schema name. Eg. the data for `user_model.js` is stored in the `users` collection in Mongo.
+Schemas are loaded from `MODEL_DIR` (default `./dist/models` on the sample server). Each file is named `<name>_model.js`. Each schema represents a collection in Mongo, with the Mongo collection name being the plural of the schema name. Eg. the data for `user_model.js` is stored in the `users` collection in Mongo.
 
-A typical schema looks like `/models/test_model.js`:
+A typical schema looks like `test_model.js` in your model directory:
 ```javascript
 /* global JXPSchema ObjectId Mixed */
 
@@ -108,6 +108,12 @@ _owner_id: ObjectId
 
 This is a link to the `user` that originally created the document. This is used for permissioning the `owner` rights.
 
+```javascript
+_updated_by_id: ObjectId
+```
+
+Set on PUT to the user who last updated the document (populated as `_updated_by` when using `map_to`).
+
 ```javascript
 createdAt: Date,
 updatedAt: Date
@@ -116,25 +122,28 @@ updatedAt: Date
 We always store the created and updated timestamp.
 
 ```javascript
-_v: Number
+__v: Number
 ```
 
-The version is tracked.
+Mongoose version key.
 
 ## Stored Procedures
 
-You can write your own stored procs in your schemas to do whatever you want. You can access these through the `/call` endpoint. Declare these as a static Mongoose function.
-
-`/call/test/test`
+You can expose selected static methods via the `/call` endpoint. Declare the static on the schema and list its name in **`callable_statics`** (only listed methods are callable; all others return 403).
 
 ```js
+const TestSchema = new JXPSchema({ ... }, {
+  perms: { ... },
+  callable_statics: ["test"],
+});
+
 TestSchema.statics.test = function(data) {
     console.log(data);
     return "Testing OKAY!";
 };
 ```
 
-You can GET your static, or POST data to it.
+`/call/test/test` — GET or POST. Unlisted statics are rejected.
 
 You can even prepopulate the function with an item:
 
@@ -147,8 +156,10 @@ TestSchema.statics.testItem = function(item, data) {
 };
 ```
 
-The static call will include the user's data as `data.__user`. [NOTE: This will probably change to "sender" before v2 is finalised.]
+The static call will include the authenticated user on `data.__user` when a user is logged in.
+
+You can also set permissions after construction with `TestSchema.set("_perms", { ... })`, but the usual pattern is the `perms` option in the constructor (see above).
 
-## Pre- and post-fuctions
+## Pre- and post-functions
 
 You can use [Mongoose pre- and post-middleware](https://mongoosejs.com/docs/middleware.html#post) to do advanced validation or to return a calculated field with your results.

package/docs/special.md

@@ -1,8 +1,8 @@
 # Special Features
 
-## We allways encrypt passwords
+## We always encrypt passwords
 
-You should note that if you send through anything called "password", it will automagically encrypt using bcrypt, unless you send the parameter `password_override=1`.
+If you send anything called `password`, it is encrypted with bcrypt automatically. The query parameter `password_override=1` skips hashing but **requires an admin user** (for setting a pre-computed hash).
 
 ## Reflection/navel gazing
 
@@ -12,7 +12,7 @@ The endpoint `/model/modelname` gives us a description of a model.
 
 ## Cache
 
-The `/cache` endpoint should show us some info about the state of our Memcached server.
+When caching is enabled, `GET /cache/stats` returns in-process cache statistics (see [Caching](caching.md)). Use `GET /cache/clear` to flush the cache.
 
 ## Downloading data as CSV
 
@@ -30,4 +30,4 @@ You can permanently delete a document by passing the parameter `?_permaDelete=1`
 
 You can delete all of the rows that reference a row you're deleting by adding `?_cascade=1` to your endpoint.
 
-You can combine permanent and cascade deleting.
+You can combine permanent and cascade deleting.

package/docs/typescript.md

@@ -0,0 +1,86 @@
+# TypeScript (v4)
+
+JXP 4 is written in TypeScript and published as compiled JavaScript plus `.d.ts` declaration files.
+
+## Building from source
+
+```bash
+git clone https://github.com/WorkSpaceMan/jxp.git
+cd jxp
+npm install --legacy-peer-deps
+npm run build   # compiles src/ → dist/
+npm test        # build + mocha (requires MongoDB for integration tests)
+npm start       # runs dist/bin/server.js
+```
+
+During development:
+
+```bash
+npm run dev     # rebuild on src/ changes and restart the sample server
+```
+
+## Consuming JXP from JavaScript
+
+No changes are required for existing `*_model.js` apps:
+
+```javascript
+/* global JXPSchema ObjectId Mixed */
+const MySchema = new JXPSchema({ name: String }, { perms: { admin: "crud", all: "r" } });
+module.exports = JXPSchema.model("MyModel", MySchema);
+```
+
+`require("jxp")` resolves to the compiled entry at `dist/libs/jxp.js`.
+
+Deep imports remain supported, e.g. `require("jxp/libs/query_manipulation")`.
+
+## Editor types for JS models
+
+Add a dev dependency on `jxp@^4` and reference globals in model files:
+
+```javascript
+/// <reference types="jxp/globals" />
+/* global JXPSchema ObjectId Mixed */
+```
+
+## Authoring models in TypeScript
+
+```typescript
+import JXPSchema from "jxp/libs/schema"; // or relative path when in-repo
+import type { Types } from "mongoose";
+
+export interface IWidget {
+  _id?: Types.ObjectId;
+  name?: string;
+}
+
+const WidgetSchema = new JXPSchema(
+  { name: String },
+  { perms: { admin: "crud", all: "r" } }
+);
+
+const Widget = JXPSchema.model<IWidget>("Widget", WidgetSchema);
+export default Widget;
+```
+
+Compile app models to `*_model.js` in your `model_dir`, or extend the loader in a future release to accept `_model.ts` directly.
+
+## Built-in document types
+
+JXP ships typed built-in models (import from your compiled `dist/models` path when developing JXP itself):
+
+| Model | Interface |
+|-------|-----------|
+| User | `IUser` |
+| Token | `IToken` |
+| RefreshToken | `IRefreshToken` |
+| APIKey | `IAPIKey` |
+| Usergroup | `IUserGroup` |
+| Link | `ILink` |
+| Test | `ITest` |
+
+## Breaking changes in v4
+
+- **Published package** — npm installs ship prebuilt `dist/` (not `src/`). Building from source (`npm run build`) is only required when developing from a git clone.
+- **Entry point** — `main` is `dist/libs/jxp.js`; `types` points to matching `.d.ts`.
+- **Node** — requires Node.js 22+.
+- **Relative `model_dir`** — resolved from `process.cwd()` (typical for npm scripts), not from the server script path.

package/docs/websocket.md

@@ -1,3 +1,101 @@
 # Websockets
 
-Documentation coming soon...
+JXP exposes a WebSocket server on the same HTTP port as the REST API (upgrade on the shared Restify server). Clients receive real-time notifications when documents are created, updated, or deleted, subject to the same permission checks as the REST API.
+
+## Connecting
+
+Connect to the WebSocket URL for your server (same host and port as the API, `ws://` or `wss://` scheme).
+
+## Message format
+
+Send JSON messages with:
+
+| Field | Description |
+|-------|-------------|
+| `action` | One of `ping`, `auth`, `subscribe`, `unsubscribe` |
+| `msg_id` | Client-chosen id echoed in the response (required) |
+| `data` | Action-specific payload (optional object) |
+
+Responses include `status` (`okay` or `error`), `msg_id`, `client_id`, and optionally `result` or `message`.
+
+### ping
+
+Request:
+
+```json
+{ "action": "ping", "msg_id": "1", "data": {} }
+```
+
+Response `result`: `"pong!"`
+
+### auth
+
+Authenticate before subscribing. Provide one of:
+
+- `data.email` and `data.password`
+- `data.apikey`
+- `data.token` (Bearer access token)
+
+Request:
+
+```json
+{
+  "action": "auth",
+  "msg_id": "2",
+  "data": { "email": "user@example.com", "password": "secret" }
+}
+```
+
+### subscribe
+
+Subscribe to changes on a model. Requires prior `auth`.
+
+**Collection-wide** (post, put, delete on any document):
+
+```json
+{
+  "action": "subscribe",
+  "msg_id": "3",
+  "data": { "model": "test" }
+}
+```
+
+**Single document** (put and delete on one id):
+
+```json
+{
+  "action": "subscribe",
+  "msg_id": "4",
+  "data": { "model": "test", "id": "5eb7cf838c9fba641e0e9dcb" }
+}
+```
+
+Optional `data.filter` limits which events are delivered (field values must match on the changed document).
+
+### unsubscribe
+
+Same `data` shape as `subscribe` (`model`, optional `id`).
+
+## Events pushed to the client
+
+When a subscribed change occurs, the server sends JSON with a `data` object such as:
+
+```json
+{
+  "client_id": "<ws client id>",
+  "data": {
+    "event": "put",
+    "modelname": "test",
+    "item": { ... },
+    "user_id": "...",
+    "user_name": "...",
+    "user_email": "..."
+  }
+}
+```
+
+`event` is one of `post`, `put`, or `del`.
+
+## Hooks
+
+Server `pre_hooks` on `post`, `put`, and `delete` run in the same process as the WebSocket emitter. Use hooks to enforce extra rules; subscribers only receive events the acting user was allowed to perform.

package/mkdocs.yml

@@ -3,6 +3,7 @@ nav:
   - Home: index.md
   - Installation: installation.md
   - Configuration: configuration.md
+  - TypeScript: typescript.md
   - Authentication: authentication.md
   - Schemas: schemas.md
   - Restful API: api.md