alepha 0.14.1 → 0.14.3

package/src/api/parameters/controllers/{ConfigController.ts → AdminConfigController.ts}

@@ -1,35 +1,24 @@
 import { $inject, t } from "alepha";
 import { $action } from "alepha/server";
 import type { ParameterStatus } from "../entities/parameters.ts";
+import {
+  activateConfigBodySchema,
+  checkScheduledResponseSchema,
+  configCurrentResponseSchema,
+  configHistoryResponseSchema,
+  configNameParamSchema,
+  configNamesResponseSchema,
+  configsByStatusResponseSchema,
+  configTreeNodeSchema,
+  configVersionParamSchema,
+  configVersionResponseSchema,
+  createConfigVersionBodySchema,
+  parameterResponseSchema,
+  rollbackConfigBodySchema,
+  statusParamSchema,
+} from "../schemas/index.ts";
 import { ConfigStore } from "../services/ConfigStore.ts";
 
-// Define response schemas inline to avoid complex entity schema issues
-const parameterResponseSchema = t.object({
-  id: t.uuid(),
-  createdAt: t.datetime(),
-  updatedAt: t.datetime(),
-  name: t.text(),
-  content: t.json(),
-  schemaHash: t.text(),
-  status: t.enum(["expired", "current", "next", "future"]),
-  activationDate: t.datetime(),
-  expiredAt: t.optional(t.datetime()),
-  version: t.integer(),
-  changeDescription: t.optional(t.text()),
-  tags: t.optional(t.array(t.text())),
-  creatorId: t.optional(t.uuid()),
-  creatorName: t.optional(t.text()),
-  previousContent: t.optional(t.json()),
-  migrationLog: t.optional(t.text()),
-});
-
-const treeNodeSchema: any = t.object({
-  name: t.text(),
-  path: t.text(),
-  isLeaf: t.boolean(),
-  children: t.array(t.any()),
-});
-
 /**
  * REST API controller for versioned configuration management.
  *
@@ -41,7 +30,9 @@ const treeNodeSchema: any = t.object({
  * - Rolling back to previous versions
  * - Activating scheduled versions immediately
  */
-export class ConfigController {
+export class AdminConfigController {
+  protected readonly url = "/configs";
+  protected readonly group = "admin:configs";
   protected readonly store = $inject(ConfigStore);
 
   /**
@@ -49,12 +40,13 @@ export class ConfigController {
    * Useful for admin UI navigation.
    */
   getConfigTree = $action({
+    group: this.group,
     description:
       "Get tree structure of all configuration names for navigation.",
     path: "/configs/tree",
     method: "GET",
     schema: {
-      response: t.array(treeNodeSchema),
+      response: t.array(configTreeNodeSchema),
     },
     handler: async () => {
       return this.store.getConfigTree();
@@ -65,13 +57,12 @@ export class ConfigController {
    * List all unique configuration names.
    */
   listConfigNames = $action({
+    group: this.group,
     description: "List all unique configuration names.",
     path: "/configs",
     method: "GET",
     schema: {
-      response: t.object({
-        names: t.array(t.text()),
-      }),
+      response: configNamesResponseSchema,
     },
     handler: async () => {
       const names = await this.store.getConfigNames();
@@ -83,16 +74,13 @@ export class ConfigController {
    * Get configurations by status.
    */
   getByStatus = $action({
+    group: this.group,
     description: "Get all configurations with a specific status.",
     path: "/configs/status/:status",
     method: "GET",
     schema: {
-      params: t.object({
-        status: t.enum(["expired", "current", "next", "future"]),
-      }),
-      response: t.object({
-        configs: t.array(parameterResponseSchema),
-      }),
+      params: statusParamSchema,
+      response: configsByStatusResponseSchema,
     },
     handler: async ({ params }) => {
       const configs = await this.store.getByStatus(
@@ -106,18 +94,13 @@ export class ConfigController {
    * Get version history for a specific configuration.
    */
   getHistory = $action({
+    group: this.group,
     description: "Get all versions of a specific configuration.",
     path: "/configs/:name/history",
     method: "GET",
     schema: {
-      params: t.object({
-        name: t.text({
-          description: "Configuration name (e.g., app.features.flags)",
-        }),
-      }),
-      response: t.object({
-        versions: t.array(parameterResponseSchema),
-      }),
+      params: configNameParamSchema,
+      response: configHistoryResponseSchema,
     },
     handler: async ({ params }) => {
       const versions = await this.store.getHistory(params.name);
@@ -131,22 +114,13 @@ export class ConfigController {
    * even if no versions exist in the database yet.
    */
   getCurrent = $action({
+    group: this.group,
     description: "Get current and next scheduled values for a configuration.",
     path: "/configs/:name",
     method: "GET",
     schema: {
-      params: t.object({
-        name: t.text({
-          description: "Configuration name (e.g., app.features.flags)",
-        }),
-      }),
-      response: t.object({
-        current: t.optional(parameterResponseSchema),
-        next: t.optional(parameterResponseSchema),
-        defaultValue: t.optional(t.json()),
-        currentValue: t.optional(t.json()),
-        schema: t.optional(t.json()),
-      }),
+      params: configNameParamSchema,
+      response: configCurrentResponseSchema,
     },
     handler: async ({ params }) => {
       const result = await this.store.getCurrentWithDefault(params.name);
@@ -164,17 +138,13 @@ export class ConfigController {
    * Get a specific version of a configuration.
    */
   getVersion = $action({
+    group: this.group,
     description: "Get a specific version of a configuration.",
     path: "/configs/:name/versions/:version",
     method: "GET",
     schema: {
-      params: t.object({
-        name: t.text(),
-        version: t.integer(),
-      }),
-      response: t.object({
-        config: t.optional(parameterResponseSchema),
-      }),
+      params: configVersionParamSchema,
+      response: configVersionResponseSchema,
     },
     handler: async ({ params }) => {
       const config = await this.store.getVersion(params.name, params.version);
@@ -186,31 +156,14 @@ export class ConfigController {
    * Create a new configuration version.
    */
   createVersion = $action({
+    group: this.group,
     description:
       "Create a new version of a configuration (immediate or scheduled).",
     path: "/configs/:name",
     method: "POST",
     schema: {
-      params: t.object({
-        name: t.text({
-          description: "Configuration name (e.g., app.features.flags)",
-        }),
-      }),
-      body: t.object({
-        content: t.json({ description: "New configuration content" }),
-        schemaHash: t.text({
-          description: "Hash of the schema for migration detection",
-        }),
-        activationDate: t.optional(
-          t.datetime({ description: "When to activate (default: now)" }),
-        ),
-        changeDescription: t.optional(
-          t.text({ description: "Description of changes" }),
-        ),
-        tags: t.optional(t.array(t.text())),
-        creatorId: t.optional(t.uuid()),
-        creatorName: t.optional(t.text()),
-      }),
+      params: configNameParamSchema,
+      body: createConfigVersionBodySchema,
       response: parameterResponseSchema,
     },
     handler: async ({ params, body }) => {
@@ -230,22 +183,14 @@ export class ConfigController {
    * Rollback to a previous version.
    */
   rollback = $action({
+    group: this.group,
     description:
       "Rollback a configuration to a previous version (creates new version with old content).",
     path: "/configs/:name/rollback",
     method: "POST",
     schema: {
-      params: t.object({
-        name: t.text(),
-      }),
-      body: t.object({
-        targetVersion: t.integer({
-          description: "Version number to rollback to",
-        }),
-        changeDescription: t.optional(t.text()),
-        creatorId: t.optional(t.uuid()),
-        creatorName: t.optional(t.text()),
-      }),
+      params: configNameParamSchema,
+      body: rollbackConfigBodySchema,
       response: parameterResponseSchema,
     },
     handler: async ({ params, body }) => {
@@ -261,18 +206,13 @@ export class ConfigController {
    * Activate a scheduled version immediately.
    */
   activateNow = $action({
+    group: this.group,
     description: "Activate a future/next configuration version immediately.",
     path: "/configs/:name/activate",
     method: "POST",
     schema: {
-      params: t.object({
-        name: t.text(),
-      }),
-      body: t.object({
-        version: t.integer({ description: "Version number to activate" }),
-        creatorId: t.optional(t.uuid()),
-        creatorName: t.optional(t.text()),
-      }),
+      params: configNameParamSchema,
+      body: activateConfigBodySchema,
       response: parameterResponseSchema,
     },
     handler: async ({ params, body }) => {
@@ -307,14 +247,13 @@ export class ConfigController {
    * Normally called by a scheduler, but exposed for manual triggering.
    */
   checkScheduled = $action({
+    group: this.group,
     description:
       "Manually trigger activation check for all scheduled configurations.",
     path: "/configs/activate-scheduled",
     method: "POST",
     schema: {
-      response: t.object({
-        message: t.text(),
-      }),
+      response: checkScheduledResponseSchema,
     },
     handler: async () => {
       await this.store.activateScheduledConfigs();

package/src/api/parameters/entities/parameters.ts

@@ -1,15 +1,8 @@
 import { type Static, t } from "alepha";
-import { $entity, pg } from "alepha/orm";
+import { $entity, db } from "alepha/orm";
+import { parameterStatusSchema } from "../schemas/index.ts";
 
-/**
- * Parameter status values.
- *
- * - EXPIRED: Past version, no longer active
- * - CURRENT: Currently active version
- * - NEXT: Scheduled to become active (closest future date)
- * - FUTURE: Scheduled for activation after NEXT
- */
-export type ParameterStatus = "expired" | "current" | "next" | "future";
+export type { ParameterStatus } from "../schemas/index.ts";
 
 /**
  * Configuration parameter entity for versioned configuration management.
@@ -23,9 +16,9 @@ export type ParameterStatus = "expired" | "current" | "next" | "future";
 export const parameters = $entity({
   name: "parameters",
   schema: t.object({
-    id: pg.primaryKey(t.uuid()),
-    createdAt: pg.createdAt(),
-    updatedAt: pg.updatedAt(),
+    id: db.primaryKey(t.uuid()),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
 
     /**
      * Configuration name using dot notation for tree hierarchy.
@@ -47,10 +40,7 @@ export const parameters = $entity({
     /**
      * Current status of this parameter version.
      */
-    status: pg.default(
-      t.enum(["expired", "current", "next", "future"]),
-      "future",
-    ),
+    status: db.default(parameterStatusSchema, "future"),
 
     /**
      * When this version should become active.

package/src/api/parameters/index.ts

@@ -1,12 +1,12 @@
 import { $module } from "alepha";
-import { ConfigController } from "./controllers/ConfigController.ts";
+import { AdminConfigController } from "./controllers/AdminConfigController.ts";
 import { ConfigActivationScheduler } from "./schedulers/ConfigActivationScheduler.ts";
 import { ConfigStore } from "./services/ConfigStore.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 // Controller exports
-export * from "./controllers/ConfigController.ts";
+export * from "./controllers/AdminConfigController.ts";
 // Entity exports
 export * from "./entities/parameters.ts";
 // Primitive exports
@@ -56,5 +56,5 @@ export * from "./services/ConfigStore.ts";
  */
 export const AlephaApiParameters = $module({
   name: "alepha.api.parameters",
-  services: [ConfigStore, ConfigController, ConfigActivationScheduler],
+  services: [ConfigStore, AdminConfigController, ConfigActivationScheduler],
 });

package/src/api/parameters/primitives/$config.spec.ts

@@ -0,0 +1,356 @@
+import { Alepha, t } from "alepha";
+import { describe, expect, it } from "vitest";
+import { $config, AlephaApiParameters, ConfigStore } from "../index.ts";
+
+const featureSchema = t.object({
+  enableBeta: t.boolean(),
+  maxUploadSize: t.number(),
+});
+
+describe("$config", () => {
+  it("should initialize with default value", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.flags",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    expect(config.features.current).toEqual({
+      enableBeta: false,
+      maxUploadSize: 10485760,
+    });
+  });
+
+  it("should set and persist configuration", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.flags",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    await config.features.set({
+      enableBeta: true,
+      maxUploadSize: 20971520,
+    });
+
+    expect(config.features.current).toEqual({
+      enableBeta: true,
+      maxUploadSize: 20971520,
+    });
+
+    // Verify persisted to database
+    const store = alepha.inject(ConfigStore);
+    const history = await store.getHistory("app.features.flags");
+    expect(history.length).toBe(1);
+    expect(history[0].status).toBe("current");
+    expect(history[0].content).toEqual({
+      enableBeta: true,
+      maxUploadSize: 20971520,
+    });
+  });
+
+  it("should load from database on start", async () => {
+    // Use a single Alepha instance, seed data via store before registering config
+    class AppConfig {
+      features = $config({
+        name: "app.features.load",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    // First, seed the database with a value different from default
+    const store = alepha.inject(ConfigStore);
+    await store.save(
+      "app.features.load",
+      { enableBeta: true, maxUploadSize: 5242880 },
+      "test-hash",
+    );
+
+    // Manually reload the config primitive
+    const config = alepha.inject(AppConfig);
+    await config.features.reload();
+
+    // Should have loaded from database, not default
+    expect(config.features.current).toEqual({
+      enableBeta: true,
+      maxUploadSize: 5242880,
+    });
+  });
+
+  it("should maintain version history", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.history",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    // Make multiple changes
+    await config.features.set({ enableBeta: true, maxUploadSize: 1 });
+    await config.features.set({ enableBeta: false, maxUploadSize: 2 });
+    await config.features.set({ enableBeta: true, maxUploadSize: 3 });
+
+    const history = await config.features.getHistory();
+    expect(history.length).toBe(3);
+    expect(history[0].version).toBe(3);
+    expect(history[1].version).toBe(2);
+    expect(history[2].version).toBe(1);
+  });
+
+  it("should support rollback to previous version", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.rollback",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    await config.features.set({ enableBeta: true, maxUploadSize: 100 });
+    await config.features.set({ enableBeta: false, maxUploadSize: 200 });
+    await config.features.set({ enableBeta: true, maxUploadSize: 300 });
+
+    // Rollback to version 1
+    await config.features.rollback(1);
+
+    expect(config.features.current).toEqual({
+      enableBeta: true,
+      maxUploadSize: 100,
+    });
+
+    // Should have created a new version (4)
+    const history = await config.features.getHistory();
+    expect(history.length).toBe(4);
+  });
+
+  it("should get specific field value", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.field",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    expect(config.features.get("enableBeta")).toBe(false);
+    expect(config.features.get("maxUploadSize")).toBe(10485760);
+  });
+
+  it("should support change description", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.description",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    await config.features.set(
+      { enableBeta: true, maxUploadSize: 20971520 },
+      { changeDescription: "Enable beta features for testing" },
+    );
+
+    const history = await config.features.getHistory();
+    expect(history[0].changeDescription).toBe(
+      "Enable beta features for testing",
+    );
+  });
+
+  it("should support user tracking", async () => {
+    class AppConfig {
+      features = $config({
+        name: "app.features.user",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    const userId = "550e8400-e29b-41d4-a716-446655440000";
+    await config.features.set(
+      { enableBeta: true, maxUploadSize: 20971520 },
+      {
+        user: {
+          id: userId,
+          email: "admin@example.com",
+          name: "Admin User",
+        },
+      },
+    );
+
+    const history = await config.features.getHistory();
+    expect(history[0].creatorId).toBe(userId);
+    expect(history[0].creatorName).toBe("Admin User");
+  });
+});
+
+describe("ConfigStore", () => {
+  it("should build config tree from names", async () => {
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const store = alepha.inject(ConfigStore);
+
+    await store.save("app.features.flags", { enabled: true }, "hash1");
+    await store.save("app.features.limits", { max: 100 }, "hash2");
+    await store.save("app.pricing.tiers", { basic: 10 }, "hash3");
+    await store.save("system.logging", { level: "info" }, "hash4");
+
+    const tree = await store.getConfigTree();
+
+    expect(tree.length).toBe(2); // app, system
+    expect(tree[0].name).toBe("app");
+    expect(tree[0].isLeaf).toBe(false);
+    expect(tree[0].children.length).toBe(2); // features, pricing
+
+    const features = tree[0].children.find((c) => c.name === "features");
+    expect(features?.children.length).toBe(2); // flags, limits
+  });
+
+  it("should manage status transitions correctly", async () => {
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const store = alepha.inject(ConfigStore);
+
+    // Create first version (current)
+    const v1 = await store.save("test.status.config", { value: 1 }, "hash");
+    expect(v1.status).toBe("current");
+
+    // Create second version (becomes current, first becomes expired)
+    const v2 = await store.save("test.status.config", { value: 2 }, "hash");
+    expect(v2.status).toBe("current");
+
+    const history = await store.getHistory("test.status.config");
+    const v1Updated = history.find((v) => v.version === 1);
+    expect(v1Updated?.status).toBe("expired");
+  });
+
+  it("should get configs by status", async () => {
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const store = alepha.inject(ConfigStore);
+
+    await store.save("status.a", { a: 1 }, "h1");
+    await store.save("status.b", { b: 1 }, "h2");
+    await store.save("status.a", { a: 2 }, "h1");
+
+    const current = await store.getByStatus("current");
+    const expired = await store.getByStatus("expired");
+
+    expect(current.length).toBe(2);
+    expect(expired.length).toBe(1);
+  });
+
+  it("should detect schema migration", async () => {
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const store = alepha.inject(ConfigStore);
+
+    await store.save("migration.config", { v: 1 }, "hash-v1");
+    const v2 = await store.save(
+      "migration.config",
+      { v: 2, extra: true },
+      "hash-v2",
+    );
+
+    expect(v2.migrationLog).toContain("Schema changed");
+    expect(v2.migrationLog).toContain("hash-v1");
+    expect(v2.migrationLog).toContain("hash-v2");
+  });
+
+  it("should store previous content for rollback", async () => {
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const store = alepha.inject(ConfigStore);
+
+    await store.save("previous.config", { old: true }, "hash");
+    const v2 = await store.save("previous.config", { new: true }, "hash");
+
+    expect(v2.previousContent).toEqual({ old: true });
+  });
+
+  it("should get all config names", async () => {
+    const alepha = Alepha.create();
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const store = alepha.inject(ConfigStore);
+
+    await store.save("names.alpha", { a: 1 }, "h1");
+    await store.save("names.beta", { b: 1 }, "h2");
+    await store.save("names.alpha", { a: 2 }, "h1"); // Second version
+
+    const names = await store.getConfigNames();
+
+    expect(names).toContain("names.alpha");
+    expect(names).toContain("names.beta");
+  });
+});