@ti-engine/web-framework 1.23.0 → 1.24.1

package/components/config-change-notifier.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const { EventEmitter } = require( "node:events" );

package/components/config-drift.js

@@ -0,0 +1,150 @@
+/*
+ * 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.
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+/**
+ * Pure structural diff between a configuration document's file default and the value currently held in the store.
+ * <br/>
+ * The store seeds from a file default exactly once ({@link ConfigStore#seedIfEmpty}), so a release that changes a
+ * config file changes nothing an already-seeded deployment serves. This module is the detection half of the remedy:
+ * it answers "how does the shipped default differ from what this deployment is running", in terms legible enough for
+ * an admin to judge whether applying it is safe.
+ * <br/>
+ * No I/O — the caller supplies both values.
+ *
+ * @module config-drift
+ */
+
+const { isDeepStrictEqual } = require( "node:util" );
+
+const STATUS_IN_SYNC = "in-sync";
+const STATUS_DRIFTED = "drifted";
+const STATUS_ABSENT = "absent";
+const STATUS_NO_DEFAULT = "no-default";
+
+const KIND_ADDED = "added";
+const KIND_REMOVED = "removed";
+const KIND_CHANGED = "changed";
+
+/**
+ * @typedef {Object} ConfigDriftEntry
+ * @property {string} path Dot/bracket data path, matching the dialect used for schema validation issues.
+ * @property {string} kind One of "added", "removed", "changed".
+ * @property {number} [addedMembers] For a primitive array: how many members the file default adds.
+ * @property {number} [removedMembers] For a primitive array: how many members the file default drops.
+ */
+
+/**
+ * @param {*} value
+ * @returns {boolean} True for a non-null, non-array object.
+ */
+function isPlainObject( value ) {
+    return value !== null && typeof value === "object" && !Array.isArray( value );
+}
+
+/**
+ * @param {*} value
+ * @returns {boolean} True for an array holding no objects (a code list, a set of flags, …).
+ */
+function isPrimitiveArray( value ) {
+    return Array.isArray( value ) && value.every( ( item ) => item === null || typeof item !== "object" );
+}
+
+/**
+ * @param {string} base
+ * @param {string} key
+ * @returns {string} The child path, numeric keys in bracket notation.
+ */
+function joinPath( base, key ) {
+    return ( /^\d+$/.test( key ) ) ? `${ base }[${ key }]` : `${ base }.${ key }`;
+}
+
+/**
+ * Recursive worker. Appends to `entries` in place.
+ *
+ * @param {*} fileValue
+ * @param {*} storedValue
+ * @param {string} path
+ * @param {ConfigDriftEntry[]} entries
+ */
+function diffValue( fileValue, storedValue, path, entries ) {
+    if ( isPlainObject( fileValue ) && isPlainObject( storedValue ) ) {
+        const keys = new Set( [ ...Object.keys( fileValue ), ...Object.keys( storedValue ) ] );
+        for ( const key of keys ) {
+            const childPath = joinPath( path, key );
+            const inFile = Object.prototype.hasOwnProperty.call( fileValue, key );
+            const inStored = Object.prototype.hasOwnProperty.call( storedValue, key );
+            if ( inFile && !inStored ) {
+                entries.push( { path: childPath, kind: KIND_ADDED } );
+            } else if ( !inFile && inStored ) {
+                entries.push( { path: childPath, kind: KIND_REMOVED } );
+            } else {
+                diffValue( fileValue[ key ], storedValue[ key ], childPath, entries );
+            }
+        }
+        return;
+    }
+
+    // A list of codes is a set, not a sequence: report which members moved, and treat a pure reorder as no change.
+    // This is what turns "role-family-competencies changed" into the far more useful "QE +27 codes".
+    // <br/>
+    // Set semantics also mean MULTIPLICITY is ignored — `[ "A", "A" ]` and `[ "A" ]` compare as in-sync even though
+    // applying would replace one with the other. That is deliberate for a list of codes, where a repeated member is
+    // a data error rather than a meaningful difference, and it is unreachable for the documents shipped here: the
+    // array-valued competence schemas all declare `uniqueItems`, so a duplicate cannot pass validation on save. A
+    // consumer whose arrays are genuinely multisets should not model them as primitive arrays for this diff.
+    if ( isPrimitiveArray( fileValue ) && isPrimitiveArray( storedValue ) ) {
+        const storedMembers = new Set( storedValue );
+        const fileMembers = new Set( fileValue );
+        const addedMembers = fileValue.filter( ( item ) => !storedMembers.has( item ) ).length;
+        const removedMembers = storedValue.filter( ( item ) => !fileMembers.has( item ) ).length;
+        if ( addedMembers > 0 || removedMembers > 0 ) {
+            entries.push( { path: path, kind: KIND_CHANGED, addedMembers: addedMembers, removedMembers: removedMembers } );
+        }
+        return;
+    }
+
+    if ( !isDeepStrictEqual( fileValue, storedValue ) ) {
+        entries.push( { path: path, kind: KIND_CHANGED } );
+    }
+}
+
+/**
+ * Diffs a document's registered file default against its stored value.
+ *
+ * @method
+ * @param {*} fileDefault The value registered with {@link ConfigRegistry#register}; `undefined` when none was.
+ * @param {*} storedValue The value currently in the store; `null`/`undefined` when never written.
+ * @returns {{status: string, entries: ConfigDriftEntry[], counts: {added: number, removed: number, changed: number}}}
+ * @public
+ */
+module.exports.diffDocument = ( fileDefault, storedValue ) => {
+    if ( fileDefault === undefined ) {
+        return { status: STATUS_NO_DEFAULT, entries: [], counts: { added: 0, removed: 0, changed: 0 } };
+    }
+    if ( storedValue === undefined || storedValue === null ) {
+        return { status: STATUS_ABSENT, entries: [], counts: { added: 0, removed: 0, changed: 0 } };
+    }
+
+    const entries = [];
+    diffValue( fileDefault, storedValue, "", entries );
+
+    const counts = { added: 0, removed: 0, changed: 0 };
+    for ( const entry of entries ) {
+        counts[ entry.kind ] += 1;
+    }
+    return { status: ( entries.length > 0 ) ? STATUS_DRIFTED : STATUS_IN_SYNC, entries: entries, counts: counts };
+};

package/components/config-registry.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const Ajv = require( "ajv" );

package/components/config-service.js

@@ -1,12 +1,22 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const exceptions = require( "@ti-engine/core/exceptions" );
+const configDrift = require( "#config-drift" );
 
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
@@ -307,6 +317,102 @@ class ConfigService {
         } ) );
     }
 
+    /* Public interface — drift against file defaults */
+
+    /**
+     * Compares a document's registered file default against the value currently in the store. This is how a
+     * configuration change shipped in a release becomes visible on a deployment that was seeded before it — the
+     * store seeds only once, so a later file change is otherwise invisible.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<{configKey: string, status: string, counts: Object, entries: Array, storedVersion: number, editable: boolean, label: string}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    getDrift( configKey ) {
+        if ( !this.#registry.has( configKey ) ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } ) );
+        }
+        const metadata = this.#registry.metadataFor( configKey ) || {};
+        return this.#store.getCurrent( configKey ).then( ( current ) => {
+            const diff = configDrift.diffDocument( this.#registry.getDefault( configKey ), current ? current.value : null );
+            return {
+                configKey: configKey,
+                status: diff.status,
+                counts: diff.counts,
+                entries: diff.entries,
+                storedVersion: current ? current.version : 0,
+                editable: metadata.editable !== false,
+                label: metadata.label || configKey
+            };
+        } );
+    }
+
+    /**
+     * Drift summaries for every registered document. This still computes each document's full entry list internally
+     * (it delegates to {@link ConfigService#getDrift} per document) — the saving is in the response shape, not the
+     * computation: `entries` is omitted here to keep the payload small enough for a landing screen and a startup log,
+     * where only the counts are shown.
+     *
+     * @method
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listDrift() {
+        return Promise.all( this.#registry.list().map( ( configKey ) => {
+            return this.getDrift( configKey ).then( ( drift ) => ( {
+                configKey: drift.configKey,
+                status: drift.status,
+                counts: drift.counts,
+                storedVersion: drift.storedVersion,
+                editable: drift.editable,
+                label: drift.label
+            } ) );
+        } ) );
+    }
+
+    /**
+     * Applies the registered file defaults for the given documents, as a single validated change-set.
+     * <br/>
+     * Routing through {@link ConfigService#applyEdits} is deliberate: the application is schema- and
+     * semantically validated, versioned, correlated into one change-set, added to the audit feed, and restorable —
+     * and, because a validator sees its siblings at their *pending* value, interdependent documents applied
+     * together validate against each other rather than against the stale stored state.
+     *
+     * @method
+     * @param {string[]} configKeys
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{ok: true, changeSetID: string, versions: Object}|{ok: false, errors: Object}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On bad input, an unknown key, or a key with no default.
+     * @public
+     */
+    applyDefaults( configKeys, meta ) {
+        if ( !Array.isArray( configKeys ) || configKeys.length === 0 || !meta || !meta.adminID ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-apply-defaults-input" } ) );
+        }
+        const keys = Array.from( new Set( configKeys ) );
+        const unknown = keys.filter( ( key ) => !this.#registry.has( key ) );
+        if ( unknown.length > 0 ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKeys: unknown } ) );
+        }
+        const withoutDefault = keys.filter( ( key ) => this.#registry.getDefault( key ) === undefined );
+        if ( withoutDefault.length > 0 ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "no-default", configKeys: withoutDefault } ) );
+        }
+
+        return Promise.all( keys.map( ( key ) => this.#store.getCurrent( key ) ) ).then( ( currents ) => {
+            const edits = keys.map( ( key, index ) => ( {
+                configKey: key,
+                value: this.#registry.getDefault( key ),
+                expectedVersion: currents[ index ] ? currents[ index ].version : 0
+            } ) );
+            return this.applyEdits( edits, { adminID: meta.adminID, note: meta.note || "applied file defaults" } );
+        } );
+    }
+
     /**
      * Seeds a document's default value into the store only if it has never been written (idempotent bootstrap).
      * Used by an application to bring its file defaults into the store at startup before serving live config.

package/components/config-store.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const cache = require( "@ti-engine/core/cache" );

package/components/definitions.types.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 /** @import { TiLocalizationLanguage } from "@ti-engine/core/localization" */

package/components/local-user-directory.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const crypto = require( "node:crypto" );

package/components/session-store.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const cache = require( "@ti-engine/core/cache" );

package/components/user.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 /** @import { TiLocalizationLanguage } from "@ti-engine/core/localization" */

package/components/web-config-env.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 "use strict";

package/components/web-handlers.js

@@ -1,9 +1,18 @@
 /*
  * 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.
  * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
 */
 
 const logger = require( "@ti-engine/core/logger" );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.23.0",
+  "version": "1.24.1",
   "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
   "keywords": [
     "ti-engine",
@@ -13,8 +13,12 @@
     "csp"
   ],
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
-  "license": "GPL-3.0-or-later",
+  "license": "Apache-2.0",
   "exports": {
+    "./config-drift": {
+      "types": "./types/components/config-drift.d.ts",
+      "default": "./components/config-drift.js"
+    },
     "./config-management": {
       "types": "./types/components/config-service.d.ts",
       "default": "./components/config-service.js"
@@ -57,6 +61,10 @@
       "types": "./types/components/config-change-notifier.d.ts",
       "default": "./components/config-change-notifier.js"
     },
+    "#config-drift": {
+      "types": "./types/components/config-drift.d.ts",
+      "default": "./components/config-drift.js"
+    },
     "#config-registry": {
       "types": "./types/components/config-registry.d.ts",
       "default": "./components/config-registry.js"
@@ -108,7 +116,7 @@
     "@ti-engine/core": "*",
     "@types/express": "^5.0.6",
     "@types/express-session": "^1.18.2",
-    "@types/node": "^24.10.1",
+    "@types/node": "^26.2.0",
     "ajv": "^8.20.0",
     "cookie-parser": "^1.4.7",
     "express": "^5.2.1",

package/types/components/admin-config-handlers.d.ts

@@ -7,5 +7,8 @@ export declare var listChanges: (service: any) => (request: any, response: any,
 export declare var getChange: (service: any) => (request: any, response: any, next: any) => void;
 export declare var restoreChangeSet: (service: any) => (request: any, response: any, next: any) => void;
 export declare var exportBundle: (service: any) => (request: any, response: any, next: any) => void;
+export declare var listDrift: (service: ConfigService) => ExpressHandler;
+export declare var getDrift: (service: ConfigService) => ExpressHandler;
+export declare var applyDefaults: (service: ConfigService) => ExpressHandler;
 import type ConfigService from "#config-service";
 import type { ExpressHandler } from "#web-handlers";

package/types/components/config-drift.d.ts

@@ -0,0 +1,27 @@
+export declare var diffDocument: (fileDefault: any, storedValue: any) => {
+    status: string;
+    entries: ConfigDriftEntry[];
+    counts: {
+        added: number;
+        removed: number;
+        changed: number;
+    };
+};
+export type ConfigDriftEntry = {
+    /**
+     * Dot/bracket data path, matching the dialect used for schema validation issues.
+     */
+    path: string;
+    /**
+     * One of "added", "removed", "changed".
+     */
+    kind: string;
+    /**
+     * For a primitive array: how many members the file default adds.
+     */
+    addedMembers?: number;
+    /**
+     * For a primitive array: how many members the file default drops.
+     */
+    removedMembers?: number;
+};

package/types/components/config-service.d.ts

@@ -191,6 +191,65 @@ declare class ConfigService {
             value: Object;
         }>;
     }>;
+    /**
+     * Compares a document's registered file default against the value currently in the store. This is how a
+     * configuration change shipped in a release becomes visible on a deployment that was seeded before it — the
+     * store seeds only once, so a later file change is otherwise invisible.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<{configKey: string, status: string, counts: Object, entries: Array, storedVersion: number, editable: boolean, label: string}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    getDrift(configKey: string): Promise<{
+        configKey: string;
+        status: string;
+        counts: Object;
+        entries: any[];
+        storedVersion: number;
+        editable: boolean;
+        label: string;
+    }>;
+    /**
+     * Drift summaries for every registered document. This still computes each document's full entry list internally
+     * (it delegates to {@link ConfigService#getDrift} per document) — the saving is in the response shape, not the
+     * computation: `entries` is omitted here to keep the payload small enough for a landing screen and a startup log,
+     * where only the counts are shown.
+     *
+     * @method
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listDrift(): Promise<Array<Object>>;
+    /**
+     * Applies the registered file defaults for the given documents, as a single validated change-set.
+     * <br/>
+     * Routing through {@link ConfigService#applyEdits} is deliberate: the application is schema- and
+     * semantically validated, versioned, correlated into one change-set, added to the audit feed, and restorable —
+     * and, because a validator sees its siblings at their *pending* value, interdependent documents applied
+     * together validate against each other rather than against the stale stored state.
+     *
+     * @method
+     * @param {string[]} configKeys
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{ok: true, changeSetID: string, versions: Object}|{ok: false, errors: Object}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On bad input, an unknown key, or a key with no default.
+     * @public
+     */
+    applyDefaults(configKeys: string[], meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<{
+        ok: true;
+        changeSetID: string;
+        versions: Object;
+    } | {
+        ok: false;
+        errors: Object;
+    }>;
     /**
      * Seeds a document's default value into the store only if it has never been written (idempotent bootstrap).
      * Used by an application to bring its file defaults into the store at startup before serving live config.