@veap/settings 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Miller
+
+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

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+[![CI](https://github.com/veapjs/veap-settings/actions/workflows/CI.yml/badge.svg)](https://github.com/veapjs/veap-settings/actions/workflows/CI.yml)
+[![Release](https://github.com/veapjs/veap-settings/actions/workflows/RELEASE.yml/badge.svg)](https://github.com/veapjs/veap-settings/actions/workflows/RELEASE.yml)
+[![Version](https://img.shields.io/npm/v/@veap/settings?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@veap/settings)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @veap/settings
+
+Key-value application settings management, caching, and persistence engine
+for Veap applications.
+
+## Overview
+
+`@veap/settings` provides a dynamic configuration and settings system for
+applications needing runtime-tunable options (site title, maintenance mode,
+features flags, integrations). It bridges database persistence powered by
+`@veap/database` with in-memory caching to minimize database query overhead.
+
+## Features
+
+- **Typed key-value storage**: Store strings, numbers, booleans, and complex
+  JSON structures under unique keys.
+- **In-memory cache layer**: Fast cached reads with automated cache
+  invalidation on update or delete operations.
+- **Active Record persistence**: Backed by the `Setting` model with automatic
+  schema migrations.
+- **Clean Architecture & IoC**: Follows repository pattern with
+  `SETTINGS_REPOSITORY` and integrates cleanly via `SettingsServiceProvider`.
+- **Default values & fallback**: Specify fallback values when keys have not yet
+  been configured in the database.
+
+## Installation
+
+```bash
+# Using bun
+bun add @veap/settings @veap/kernel @veap/database
+
+# Using pnpm
+pnpm add @veap/settings @veap/kernel @veap/database
+
+# Using npm
+npm install @veap/settings @veap/kernel @veap/database
+```
+
+## Usage
+
+### Register in Application Builder
+
+Include `SettingsServiceProvider` in your application composition root:
+
+```ts
+import { Application } from "@veap/kernel";
+import { DatabaseServiceProvider } from "@veap/database";
+import { SettingsServiceProvider } from "@veap/settings";
+
+export const app = Application.configure()
+  .use(DatabaseServiceProvider)
+  .use(
+    new SettingsServiceProvider(undefined, {
+      autoMigrate: true, // Automatically applies settings table migrations
+    }),
+  )
+  .create();
+```
+
+### Accessing Settings via IoC
+
+Resolve `SettingsService` from the container in your services or server actions:
+
+```ts
+import { app } from "@veap/kernel";
+import { SettingsService } from "@veap/settings";
+
+// Read a setting with a typed fallback
+const settings = await app(SettingsService);
+const siteName = await settings.get("site.name", "Default Site Name");
+const maintenance = await settings.get<boolean>("system.maintenance", false);
+
+// Save or update a setting
+await settings.set("site.name", "My Enterprise Portal");
+await settings.set("features.comments_enabled", true);
+
+// Delete a setting
+await settings.delete("obsolete_key");
+```
+
+### Direct Model Access
+
+Interact directly with the Active Record model from `@veap/settings/models`:
+
+```ts
+import { Setting } from "@veap/settings/models";
+
+// Query all public settings
+const allSettings = await Setting.query().orderBy("key", "asc").get();
+```
+
+## Subpath Exports
+
+| Export Path                 | Content                                                                 |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `@veap/settings`            | `SettingsService`, `SettingsServiceProvider`, and repository interfaces |
+| `@veap/settings/models`     | Active Record `Setting` model                                           |
+| `@veap/settings/migrations` | Knex migrations for the settings schema                                 |
+
+## Documentation
+
+For full guides and settings caching options, visit:
+
+- **Official Website**: [https://veap.pl](https://veap.pl)
+- **Documentation**: [https://veap.pl/docs](https://veap.pl/docs)
+- **GitHub Repository**: [https://github.com/veapjs/veap-settings](https://github.com/veapjs/veap-settings)
+
+## License
+
+MIT

package/dist/composition.d.ts

@@ -0,0 +1,15 @@
+import { type SettingsConfig } from "./providers/settings.provider.js";
+declare module "@veap/kernel" {
+    interface ApplicationBuilder {
+        /**
+         * Registers the SettingsServiceProvider into the application.
+         */
+        withSettings(config?: SettingsConfig): this;
+    }
+    interface VeapConfig {
+        /**
+         * Configuration options for @veap/settings.
+         */
+        settings?: SettingsConfig;
+    }
+}

package/dist/composition.js

@@ -0,0 +1,5 @@
+import { ApplicationBuilder } from "@veap/kernel";
+import { SettingsServiceProvider, } from "./providers/settings.provider.js";
+ApplicationBuilder.prototype.withSettings = function (config) {
+    return this.use((c) => new SettingsServiceProvider(c, config));
+};

package/dist/contracts/index.d.ts

@@ -0,0 +1 @@
+export { type ISettingsRepository, type ISettingsService, SETTINGS_REPOSITORY, SETTINGS_SERVICE, } from "./settings.repository.js";

package/dist/contracts/index.js

@@ -0,0 +1 @@
+export { SETTINGS_REPOSITORY, SETTINGS_SERVICE, } from "./settings.repository.js";

package/dist/contracts/settings.repository.d.ts

@@ -0,0 +1,30 @@
+import type { Token } from "@veap/kernel";
+/**
+ * Settings persistence port.
+ */
+export interface ISettingsRepository {
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    all?(): Promise<Record<string, unknown>>;
+}
+/**
+ * Injection token for the settings repository port.
+ */
+export declare const SETTINGS_REPOSITORY: Token<ISettingsRepository>;
+/**
+ * Forward type reference for SettingsService in IoC tokens.
+ */
+export interface ISettingsService {
+    get<T>(key: string, defaultValue?: T | null): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    all(): Promise<Record<string, unknown>>;
+}
+/**
+ * Injection token for the settings application service.
+ */
+export declare const SETTINGS_SERVICE: Token<ISettingsService>;

package/dist/contracts/settings.repository.js

@@ -0,0 +1,8 @@
+/**
+ * Injection token for the settings repository port.
+ */
+export const SETTINGS_REPOSITORY = Symbol.for("veap:settings:repository");
+/**
+ * Injection token for the settings application service.
+ */
+export const SETTINGS_SERVICE = Symbol.for("veap:settings:service");

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./composition.js";
+export * from "./contracts/index.js";
+export * from "./migrations/index.js";
+export * from "./models/index.js";
+export * from "./providers/index.js";
+export * from "./repositories/index.js";
+export * from "./services/index.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./composition.js";
+export * from "./contracts/index.js";
+export * from "./migrations/index.js";
+export * from "./models/index.js";
+export * from "./providers/index.js";
+export * from "./repositories/index.js";
+export * from "./services/index.js";

package/dist/migrations/0001_create_settings_table.d.ts

@@ -0,0 +1,4 @@
+import type { Schema } from "@veap/database";
+export declare const name = "0001_create_settings_table";
+export declare function up(_db: any, schema: Schema): Promise<void>;
+export declare function down(_db: any, schema: Schema): Promise<void>;

package/dist/migrations/0001_create_settings_table.js

@@ -0,0 +1,12 @@
+export const name = "0001_create_settings_table";
+export async function up(_db, schema) {
+    await schema.createTable("settings", (table) => {
+        table.text("id").primaryKey();
+        table.text("key").notNull().unique();
+        table.json("value").notNull();
+        table.timestamp("updated_at").defaultNow();
+    });
+}
+export async function down(_db, schema) {
+    await schema.dropTableIfExists("settings");
+}

package/dist/migrations/index.d.ts

@@ -0,0 +1,4 @@
+import * as m0001 from "./0001_create_settings_table.js";
+export declare const settingsMigrations: (typeof m0001)[];
+export declare function runSettingsMigrations(): Promise<void>;
+export default settingsMigrations;

package/dist/migrations/index.js

@@ -0,0 +1,7 @@
+import { runMigrations } from "@veap/database";
+import * as m0001 from "./0001_create_settings_table.js";
+export const settingsMigrations = [m0001];
+export async function runSettingsMigrations() {
+    await runMigrations("settings", settingsMigrations);
+}
+export default settingsMigrations;

package/dist/models/Setting.d.ts

@@ -0,0 +1,22 @@
+import { type CastType, Model } from "@veap/database";
+export interface SettingAttributes {
+    id?: string;
+    key: string;
+    value: any;
+    updatedAt?: Date | null;
+    updated_at?: Date | null;
+}
+export declare class Setting extends Model<SettingAttributes> {
+    static table: string;
+    static autoUuid: boolean;
+    static timestamps: boolean | string[];
+    static casts: Record<string, CastType>;
+    /**
+     * Helper to quickly get a setting by key.
+     */
+    static getValue<T = any>(key: string, defaultValue?: T | null): Promise<T | null>;
+    /**
+     * Helper to quickly set/update a setting by key.
+     */
+    static setValue(key: string, value: any): Promise<Setting>;
+}

package/dist/models/Setting.js

@@ -0,0 +1,32 @@
+import { Model } from "@veap/database";
+export class Setting extends Model {
+    static table = "settings";
+    static autoUuid = true;
+    static timestamps = ["updated_at"];
+    static casts = {
+        value: "json",
+        updatedAt: "datetime",
+        updated_at: "datetime",
+    };
+    /**
+     * Helper to quickly get a setting by key.
+     */
+    static async getValue(key, defaultValue = null) {
+        const setting = await this.where("key", key).first();
+        return setting ? setting.getAttribute("value") : defaultValue;
+    }
+    /**
+     * Helper to quickly set/update a setting by key.
+     */
+    static async setValue(key, value) {
+        let setting = await this.where("key", key).first();
+        if (setting) {
+            setting.setAttribute("value", value);
+            await setting.save();
+        }
+        else {
+            setting = await this.create({ key, value });
+        }
+        return setting;
+    }
+}

package/dist/models/index.d.ts

@@ -0,0 +1 @@
+export { Setting, type SettingAttributes, } from "./Setting.js";

package/dist/models/index.js

@@ -0,0 +1 @@
+export { Setting, } from "./Setting.js";

package/dist/models.d.ts

@@ -0,0 +1 @@
+export * from "./models/index.js";

package/dist/models.js

@@ -0,0 +1 @@
+export * from "./models/index.js";

package/dist/providers/index.d.ts

@@ -0,0 +1 @@
+export { type SettingsConfig, SettingsServiceProvider, } from "./settings.provider.js";

package/dist/providers/index.js

@@ -0,0 +1 @@
+export { SettingsServiceProvider, } from "./settings.provider.js";

package/dist/providers/settings.provider.d.ts

@@ -0,0 +1,14 @@
+import { type Container, ServiceProvider } from "@veap/kernel";
+export interface SettingsConfig {
+    /**
+     * Whether to automatically run settings database migrations during SettingsServiceProvider.boot().
+     * Defaults to `true` when database connection is initialized.
+     */
+    autoMigrate?: boolean;
+}
+export declare class SettingsServiceProvider extends ServiceProvider {
+    private config?;
+    constructor(container: Container, config?: SettingsConfig);
+    register(): void;
+    boot(): Promise<void>;
+}

package/dist/providers/settings.provider.js

@@ -0,0 +1,52 @@
+import { isDatabaseInitialized } from "@veap/database";
+import { ConfigService, logger, ServiceProvider, } from "@veap/kernel";
+import { SETTINGS_REPOSITORY, SETTINGS_SERVICE, } from "../contracts/settings.repository.js";
+import { runSettingsMigrations } from "../migrations/index.js";
+import { ActiveRecordSettingsRepository } from "../repositories/setting.repository.js";
+import { SettingsService } from "../services/settings.service.js";
+export class SettingsServiceProvider extends ServiceProvider {
+    config;
+    constructor(container, config) {
+        super(container);
+        this.config = config;
+    }
+    register() {
+        this.container.register({
+            token: SETTINGS_REPOSITORY,
+            useClass: ActiveRecordSettingsRepository,
+            singleton: true,
+        });
+        this.container.register({
+            token: SettingsService,
+            useClass: SettingsService,
+            singleton: true,
+        });
+        this.container.register({
+            token: SETTINGS_SERVICE,
+            useFactory: (service) => service,
+            inject: [SettingsService],
+            singleton: true,
+        });
+    }
+    async boot() {
+        const configService = this.container.has(ConfigService)
+            ? await this.container.resolve(ConfigService)
+            : undefined;
+        const envAutoMigrate = configService?.get("SETTINGS_AUTO_MIGRATE") ??
+            (typeof process !== "undefined"
+                ? process.env.SETTINGS_AUTO_MIGRATE
+                : undefined);
+        const shouldAutoMigrate = this.config?.autoMigrate ??
+            (envAutoMigrate !== undefined
+                ? envAutoMigrate === "true" || envAutoMigrate === "1"
+                : true);
+        if (shouldAutoMigrate !== false && isDatabaseInitialized()) {
+            try {
+                await runSettingsMigrations();
+            }
+            catch (error) {
+                logger.warn("veap:settings", "Automatic settings migration failed or deferred:", error?.message || error);
+            }
+        }
+    }
+}

package/dist/repositories/index.d.ts

@@ -0,0 +1 @@
+export { ActiveRecordSettingsRepository } from "./setting.repository.js";

package/dist/repositories/index.js

@@ -0,0 +1 @@
+export { ActiveRecordSettingsRepository } from "./setting.repository.js";

package/dist/repositories/setting.repository.d.ts

@@ -0,0 +1,11 @@
+import type { ISettingsRepository } from "../contracts/settings.repository.js";
+/**
+ * `ISettingsRepository` adapter backed by the `Setting` ActiveRecord model.
+ */
+export declare class ActiveRecordSettingsRepository implements ISettingsRepository {
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    all(): Promise<Record<string, unknown>>;
+}

package/dist/repositories/setting.repository.js

@@ -0,0 +1,29 @@
+import { Setting } from "../models/Setting.js";
+/**
+ * `ISettingsRepository` adapter backed by the `Setting` ActiveRecord model.
+ */
+export class ActiveRecordSettingsRepository {
+    async get(key) {
+        return Setting.getValue(key, null);
+    }
+    async set(key, value) {
+        await Setting.setValue(key, value);
+    }
+    async delete(key) {
+        await Setting.where("key", key).delete();
+    }
+    async clear() {
+        await Setting.query().delete();
+    }
+    async all() {
+        const settings = await Setting.all();
+        const result = {};
+        for (const s of settings) {
+            const k = s.getAttribute("key");
+            if (k) {
+                result[k] = s.getAttribute("value");
+            }
+        }
+        return result;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/server.js

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/services/index.d.ts

@@ -0,0 +1 @@
+export { SettingsService } from "./settings.service.js";

package/dist/services/index.js

@@ -0,0 +1 @@
+export { SettingsService } from "./settings.service.js";

package/dist/services/settings.service.d.ts

@@ -0,0 +1,44 @@
+import { type ICacheProvider } from "@veap/kernel";
+import { type ISettingsRepository, type ISettingsService } from "../contracts/settings.repository.js";
+/**
+ * Application service for reading and writing settings.
+ *
+ * It depends exclusively on ports (ICacheProvider, ISettingsRepository)
+ * that are injected through the constructor.
+ */
+export declare class SettingsService implements ISettingsService {
+    private cache;
+    private repository;
+    constructor(cache: ICacheProvider, repository: ISettingsRepository);
+    /**
+     * Get a setting value by key.
+     * @param key Setting key (e.g., "system:page")
+     * @param defaultValue Optional fallback value if the key does not exist
+     * @returns Value as T or defaultValue / null
+     */
+    get<T>(key: string, defaultValue?: T | null): Promise<T | null>;
+    /**
+     * Check if a setting exists.
+     * @param key Setting key
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Set a setting value.
+     * @param key Setting key
+     * @param value JSON value
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Remove a setting by key.
+     * @param key Setting key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clear all settings.
+     */
+    clear(): Promise<void>;
+    /**
+     * Retrieve all settings as a key-value map.
+     */
+    all(): Promise<Record<string, unknown>>;
+}

package/dist/services/settings.service.js

@@ -0,0 +1,93 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { CACHE_PROVIDER, Inject, Injectable, } from "@veap/kernel";
+import { SETTINGS_REPOSITORY, } from "../contracts/settings.repository.js";
+/**
+ * Application service for reading and writing settings.
+ *
+ * It depends exclusively on ports (ICacheProvider, ISettingsRepository)
+ * that are injected through the constructor.
+ */
+let SettingsService = class SettingsService {
+    cache;
+    repository;
+    constructor(cache, repository) {
+        this.cache = cache;
+        this.repository = repository;
+    }
+    /**
+     * Get a setting value by key.
+     * @param key Setting key (e.g., "system:page")
+     * @param defaultValue Optional fallback value if the key does not exist
+     * @returns Value as T or defaultValue / null
+     */
+    async get(key, defaultValue = null) {
+        const cacheKey = `settings:${key}`;
+        const cached = await this.cache.get(cacheKey);
+        if (cached !== null)
+            return cached;
+        const value = await this.repository.get(key);
+        if (value !== null) {
+            await this.cache.set(cacheKey, value);
+            return value;
+        }
+        return defaultValue;
+    }
+    /**
+     * Check if a setting exists.
+     * @param key Setting key
+     */
+    async has(key) {
+        return (await this.get(key)) !== null;
+    }
+    /**
+     * Set a setting value.
+     * @param key Setting key
+     * @param value JSON value
+     */
+    async set(key, value) {
+        await this.repository.set(key, value);
+        await this.cache.set(`settings:${key}`, value);
+    }
+    /**
+     * Remove a setting by key.
+     * @param key Setting key
+     */
+    async remove(key) {
+        await this.repository.delete(key);
+        await this.cache.delete(`settings:${key}`);
+    }
+    /**
+     * Clear all settings.
+     */
+    async clear() {
+        await this.repository.clear();
+        await this.cache.clear();
+    }
+    /**
+     * Retrieve all settings as a key-value map.
+     */
+    async all() {
+        if (this.repository.all) {
+            return this.repository.all();
+        }
+        return {};
+    }
+};
+SettingsService = __decorate([
+    Injectable(),
+    __param(0, Inject(CACHE_PROVIDER)),
+    __param(1, Inject(SETTINGS_REPOSITORY)),
+    __metadata("design:paramtypes", [Object, Object])
+], SettingsService);
+export { SettingsService };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@veap/settings",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Application settings management, caching, and persistence for Veap",
+  "bugs": "https://github.com/veapjs/veap-settings/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/veapjs/veap-settings.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./models": {
+      "types": "./dist/models.d.ts",
+      "default": "./dist/models.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "rimraf dist && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@veap/database": "0.1.1",
+    "@veap/kernel": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "better-sqlite3": "^13.0.3",
+    "knex": "^3.1.0",
+    "rimraf": "^6.1.3",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.0"
+  }
+}