@ti-engine/core 1.7.2 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 This document contains the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.8.1
+
+Presentation and documentation only — no functional change. The npm page is the first thing a prospective user sees, and it was working against the package.
+
+The two JSDoc corrections here were found while attempting to generate TypeScript declarations from the framework's JSDoc. That work is **deferred to a later release**: the generated declarations did not type-check for a consumer using TypeScript's default settings, and fixing that properly means rewiring the cross-file typedef graph rather than patching the output. These two fixes stand on their own regardless, because the JSDoc was wrong.
+
+* fix(types): correct the `TiEnum` typedef's function-property annotations. `function( (number|string), [string] ): (string|undefined)` cannot be parsed — the JSDoc-optional bracket inside a function type is not readable — so `name`, `description` and `contains` were described as unnamed `Function` members. Documentation that reads correctly to a person and not at all to a parser
+* refactor(tools): declare the enum factory as a named constant and export it as `module.exports.enum = createEnum`. Identical export name, arguments and behaviour; a direct assignment to a reserved word emits invalid syntax in a generated declaration, so this removes the obstacle ahead of the deferred work
+* fix(docs): remove the CodeRabbit badge, which rendered as `provider or repo not found` — an error message sitting in the first line of the package page
+* fix(docs): remove the `npms.io` popularity and quality badges. They were not broken; they worked, and published `popularity 4%` and `quality 47%` about this package on its own front page. Popularity is a restatement of the download count, which no niche framework wins, and there is no reason to advertise either
+* feat(docs): show `npm version`, monthly downloads, the supported Node range, the licence and CI status instead — facts that stay true on their own, sourced from npm and GitHub rather than a third-party scoring service. Provenance needs no badge: npm renders it natively beside the version
+* feat(docs): open the README with the install command and a minimal working service — the class and the handler — so the first screenful shows what using the framework looks like rather than three paragraphs about it
+* fix(package): replace the description, which was the generic monorepo blurb shared verbatim with `tester`, with one that says what this package is. It is the line npm shows in search results
+* fix(package): drop the `pubsub` keyword and add `message-queue`, `ioredis` and `microservice-framework`. The framework does not use Redis pub/sub at all — its exchange is built on lists, hashes and RedisJSON — so that keyword advertised something it does not do
+
+## Version 1.8.0
+
+`ioredis` 6 makes RESP3 its default wire protocol. The framework does not set the `protocol` option, so this changes how every `core` connection talks to Redis without a line of framework code changing — and the suite here never touches a live Redis, so a green test run says nothing about it either way. It was checked against a real server rather than assumed: for every command the framework issues — `hgetall`, `smembers`, `hget`, `get`, `brpop`, the same commands through the generic `call()` path used for RedisJSON, and again inside `multi` — RESP3 and RESP2 return **identical** JavaScript values, because `ioredis` maps the new protocol's map and set types back to the objects and arrays it always returned. No consumer code changes.
+
+The cost is the Redis floor. `ioredis` negotiates with a `HELLO 3` on connect and **throws** when the server cannot answer it — there is no fallback to RESP2 — so a server older than 6.0 now fails to connect instead of working as it did before.
+
+* build(deps)!: update `ioredis` from ^5.11.1 to ^6.0.0. **BREAKING**: raises the minimum Redis version from 5.0.14 to **6.0**, because `ioredis` 6 defaults to RESP3 and refuses a server that cannot negotiate it. A deployment pinned to Redis 5 must upgrade the server; a consumer that needs the old wire protocol for another reason can pass `protocol: 2` in its Redis options
+* docs(core): correct the documented Redis prerequisite from 5.0.14 to 6.0 and record why the floor moved
+* build(release): bump package version from `1.7.2` to `1.8.0`
+
 ## Version 1.7.2
 
 No functional change — the framework code is what `1.7.1` shipped. The version exists to exercise the automated npm publish that replaced the release-triggered workflow, and to prove this package's own trusted publisher configuration on npmjs.com: OIDC trust is granted per package, so it is only ever validated by an actual publish of that package.

package/README.md

@@ -1,15 +1,45 @@
 # ti-engine core
 
-![GitHub top language](https://img.shields.io/github/languages/top/Belleal/ti-engine)
-![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/Belleal/ti-engine)
-![npms.io (scoped package)](https://img.shields.io/npms-io/maintenance-score/%40ti-engine/core)
-![npms.io (scoped package)](https://img.shields.io/npms-io/popularity-score/%40ti-engine/core)
-![npms.io (scoped package)](https://img.shields.io/npms-io/quality-score/%40ti-engine/core)
+[![npm version](https://img.shields.io/npm/v/%40ti-engine/core)](https://www.npmjs.com/package/@ti-engine/core)
+[![npm downloads](https://img.shields.io/npm/dm/%40ti-engine/core)](https://www.npmjs.com/package/@ti-engine/core)
+[![node](https://img.shields.io/node/v/%40ti-engine/core)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/%40ti-engine/core)](https://github.com/Belleal/ti-engine/blob/master/LICENSE.md)
+[![CI](https://github.com/Belleal/ti-engine/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Belleal/ti-engine/actions/workflows/ci.yml)
 
 ![Logo](https://raw.githubusercontent.com/Belleal/ti-engine/master/packages/core/docs/ti-engine-icon.ico)
 
 Flexible framework for the creation of microservices with [node.js](https://nodejs.org/).
 
+Every release is published from CI with a [provenance attestation](https://docs.npmjs.com/generating-provenance-statements), so the tarball on npm is verifiably built from the commit it names.
+
+```shell
+npm install @ti-engine/core
+```
+
+A service is a class and a handler. The class declares the lifecycle; the handler is the business logic:
+
+```javascript
+// my-service.js — the instance
+const ServiceProvider = require( "@ti-engine/core/service-provider" );
+
+class MyService extends ServiceProvider {
+    onStart() {
+        return Promise.resolve();
+    }
+}
+
+module.exports = MyService;
+```
+
+```javascript
+// services/v1/greet.js — one service, registered in the service registry JSON
+module.exports.service = ( serviceDefinition, serviceParams, serviceCallContext ) => {
+    return Promise.resolve( { greeting: `hello, ${ serviceParams.name }` } );
+};
+```
+
+Point `TI_INSTANCE_CLASS` at the class, `TI_INSTANCE_NAME` at the service domain, and start it with `node ./node_modules/@ti-engine/core/bin/start-instance.js`. Calls between instances travel over Redis as an envelope plus a payload, traced end to end. The rest of this document covers that machinery in detail — start with [Prerequisites & installation](#prerequisites--installation).
+
 ## Introduction
 
 The **ti-engine** is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using **node.js**. The architectural concept of the framework is based on a standard _messaging system_ that allows for certain customization but also provides predictability and traceability of its behavior.
@@ -36,7 +66,9 @@ Being a messaging system, the **ti-engine** relies on a message broker for the a
 To run the basic **ti-engine** framework, you will need a couple of things:
 
 * A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **20.12.0** (the `core` package requires `process.loadEnvFile`)
-* A local or remote [Redis cache installation](https://redis.io/download) with a minimum version of **5.0.14**
+* A local or remote [Redis cache installation](https://redis.io/download) with a minimum version of **6.0**
+
+> The Redis floor moved from 5.0.14 to 6.0 in `core` 1.8.0, when `ioredis` 6 made RESP3 its default wire protocol. RESP3 arrived in Redis 6.0, and the client negotiates it with a `HELLO 3` on connect — an older server rejects that and the connection fails outright rather than falling back, so this is a hard requirement rather than a recommendation. Replies are unaffected: `ioredis` maps every RESP3 reply back to the same JavaScript value RESP2 produced, so nothing in your service code changes.
 
 If you are working under Windows 10+ OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/). You could also use [Redis Cloud](https://app.redislabs.com/) for development as it offers a free basic account.
 

package/components/definitions.types.js

@@ -117,10 +117,10 @@
 
 /**
  * @typedef {Object} TiEnum
- * @property {Object.<number|string,TiEnumValue>} properties
- * @property {function( (number|string), [string] ): (string|undefined)} name
- * @property {function( (number|string), [string] ): (string|undefined)} description
- * @property {function( (number|string) ): boolean} contains
+ * @property {Object.<string,TiEnumValue>} properties
+ * @property {(enumValue: number|string, placeholder?: string) => string|undefined} name
+ * @property {(enumValue: number|string, placeholder?: string) => string|undefined} description
+ * @property {(enumValue: number|string) => boolean} contains
  */
 
 /**

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.7.2",
-  "description": "The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.",
+  "version": "1.8.1",
+  "description": "Microservice framework for Node.js: a Redis-backed message exchange with end-to-end call tracing, retries and tamper-evident message envelopes.",
   "keywords": [
     "microservices",
+    "microservice-framework",
     "framework",
     "node",
     "redis",
+    "ioredis",
     "messaging",
-    "pubsub",
+    "message-queue",
     "distributed-systems"
   ],
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
@@ -59,12 +61,11 @@
     "#tools": "./utils/tools.js"
   },
   "dependencies": {
-    "ioredis": "^5.11.1",
+    "ioredis": "^6.0.0",
     "lodash": "^4.18.1",
     "node-schedule": "^2.1.1"
   },
-  "optionalDependencies": {
-  },
+  "optionalDependencies": {},
   "files": [
     "bin/",
     "components/",
@@ -87,4 +88,4 @@
   "engines": {
     "node": ">=20.12.0"
   }
-}
+}

package/utils/tools.js

@@ -49,7 +49,11 @@ module.exports.deepFreeze = ( object, seen = new WeakSet() ) => {
  * @returns {Object} This is a {@link TiEnum} object. Setting the proper reference here would unfortunately break IDE support.
  * @public
  */
-module.exports.enum = ( seed ) => {
+// Declared as a named constant and exported below rather than assigned straight onto `module.exports`:
+// `enum` is a reserved word in TypeScript, and a direct assignment makes the generated declaration
+// `export declare var enum`, which is a syntax error. Named and re-exported, it emits the aliased
+// form instead. The runtime export is unchanged — this is still `tools.enum( ... )`.
+const createEnum = ( seed ) => {
     const enumObject = Object.create( null );
     const properties = Object.create( null );
     const reserved = new Set( [ "properties", "name", "description", "contains", "__proto__", "prototype", "constructor" ] );
@@ -147,6 +151,7 @@ module.exports.enum = ( seed ) => {
 
     return enumObject;
 };
+module.exports.enum = createEnum;
 
 /**
  * Used to get the name of an {@link TiEnum} value if such exists.