@flink-app/flink 2.0.0-alpha.82 → 2.0.0-alpha.84

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.84
+
+## 2.0.0-alpha.83
+
+### Minor Changes
+
+-   Add FlinkService as optional business logic layer with auto-discovery, ctx injection, async onInit(), and mockCtx() test helper
+
 ## 2.0.0-alpha.82
 
 ## 2.0.0-alpha.81

package/cli/cli-utils.ts

@@ -116,6 +116,7 @@ export async function compile(opts: CompileOptions): Promise<void> {
     await compiler.parseTools();
     await compiler.parseAgents();
     await compiler.parseJobs();
+    await compiler.parseServices();
     await compiler.parseAllExtensionDirs();
     await compiler.parseHandlers();
     await compiler.generateStartScript(entry);

package/dist/cli/cli-utils.js

@@ -125,20 +125,23 @@ function compile(opts) {
                     return [4 /*yield*/, compiler.parseJobs()];
                 case 5:
                     _c.sent();
-                    return [4 /*yield*/, compiler.parseAllExtensionDirs()];
+                    return [4 /*yield*/, compiler.parseServices()];
                 case 6:
                     _c.sent();
-                    return [4 /*yield*/, compiler.parseHandlers()];
+                    return [4 /*yield*/, compiler.parseAllExtensionDirs()];
                 case 7:
                     _c.sent();
-                    return [4 /*yield*/, compiler.generateStartScript(entry)];
+                    return [4 /*yield*/, compiler.parseHandlers()];
                 case 8:
                     _c.sent();
-                    return [4 /*yield*/, compiler.generateAllSchemas()];
+                    return [4 /*yield*/, compiler.generateStartScript(entry)];
                 case 9:
                     _c.sent();
-                    return [4 /*yield*/, compiler.saveAllModifiedFiles()];
+                    return [4 /*yield*/, compiler.generateAllSchemas()];
                 case 10:
+                    _c.sent();
+                    return [4 /*yield*/, compiler.saveAllModifiedFiles()];
+                case 11:
                     _c.sent();
                     if (typeCheck) {
                         stepStart = Date.now();
@@ -148,14 +151,14 @@ function compile(opts) {
                         time("Type checking (getPreEmitDiagnostics)", stepStart);
                     }
                     stepStart = Date.now();
-                    if (!(process.env.FLINK_USE_TSC === "true")) return [3 /*break*/, 11];
+                    if (!(process.env.FLINK_USE_TSC === "true")) return [3 /*break*/, 12];
                     compiler.emitWithTsc();
-                    return [3 /*break*/, 13];
-                case 11: return [4 /*yield*/, compiler.emit()];
-                case 12:
-                    _c.sent();
-                    _c.label = 13;
+                    return [3 /*break*/, 14];
+                case 12: return [4 /*yield*/, compiler.emit()];
                 case 13:
+                    _c.sent();
+                    _c.label = 14;
+                case 14:
                     time("Transpilation (".concat(process.env.FLINK_USE_TSC === "true" ? "tsc" : "swc", ")"), stepStart);
                     if (timingLogs) {
                         console.log("Compilation done in ".concat(Date.now() - start, "ms"));

package/dist/src/FlinkApp.d.ts

@@ -55,6 +55,14 @@ export declare const autoRegisteredTools: FlinkToolFile[];
  * are picked up by TypeScript compiler
  */
 export declare const autoRegisteredAgents: FlinkAgentFile<any, any>[];
+/**
+ * This will be populated at compile time when the apps services
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredServices: {
+    serviceInstanceName: string;
+    Service: any;
+}[];
 export interface FlinkOptions {
     /**
      * Name of application, will only show in logs and in HTTP header.
@@ -280,6 +288,7 @@ export declare class FlinkApp<C extends FlinkContext> {
     private expressServer;
     private onError?;
     private repos;
+    private services;
     private llmAdapters;
     private tools;
     private agents;

package/dist/src/FlinkApp.js

@@ -50,7 +50,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlinkApp = exports.autoRegisteredAgents = exports.autoRegisteredTools = exports.autoRegisteredJobs = exports.autoRegisteredRepos = exports.autoRegisteredHandlers = exports.expressFn = void 0;
+exports.FlinkApp = exports.autoRegisteredServices = exports.autoRegisteredAgents = exports.autoRegisteredTools = exports.autoRegisteredJobs = exports.autoRegisteredRepos = exports.autoRegisteredHandlers = exports.expressFn = void 0;
 var ajv_1 = __importDefault(require("ajv"));
 var ajv_formats_1 = __importDefault(require("ajv-formats"));
 var body_parser_1 = __importDefault(require("body-parser"));
@@ -110,6 +110,11 @@ exports.autoRegisteredTools = [];
  * are picked up by TypeScript compiler
  */
 exports.autoRegisteredAgents = [];
+/**
+ * This will be populated at compile time when the apps services
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredServices = [];
 var FlinkApp = /** @class */ (function () {
     function FlinkApp(opts) {
         var _a;
@@ -120,6 +125,7 @@ var FlinkApp = /** @class */ (function () {
         this.routingConfigured = false;
         this.disableHttpServer = false;
         this.repos = {};
+        this.services = {};
         this.llmAdapters = new Map();
         this.tools = {};
         this.agents = {}; // FlinkAgent<C> instances
@@ -1123,37 +1129,60 @@ var FlinkApp = /** @class */ (function () {
      */
     FlinkApp.prototype.buildContext = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var _i, autoRegisteredRepos_1, _a, collectionName, repoInstanceName, Repo, repoInstance, pluginCtx, _b, _c, repo;
-            return __generator(this, function (_d) {
-                if (this.dbOpts) {
-                    for (_i = 0, autoRegisteredRepos_1 = exports.autoRegisteredRepos; _i < autoRegisteredRepos_1.length; _i++) {
-                        _a = autoRegisteredRepos_1[_i], collectionName = _a.collectionName, repoInstanceName = _a.repoInstanceName, Repo = _a.Repo;
-                        repoInstance = new Repo(collectionName, this.db, this.dbClient);
-                        this.repos[repoInstanceName] = repoInstance;
-                        initLog.info("Registered repo ".concat(repoInstanceName));
-                    }
-                }
-                else if (exports.autoRegisteredRepos.length > 0) {
-                    FlinkLog_1.log.warn("No db configured but found repo(s)");
-                }
-                pluginCtx = this.plugins.reduce(function (out, plugin) {
-                    if (out[plugin.id]) {
-                        throw new Error("Plugin ".concat(plugin.id, " is already registered"));
-                    }
-                    out[plugin.id] = plugin.ctx;
-                    return out;
-                }, {});
-                this._ctx = {
-                    repos: this.repos,
-                    plugins: pluginCtx,
-                    auth: this.auth,
-                    agents: this.agents,
-                };
-                for (_b = 0, _c = Object.values(this.repos); _b < _c.length; _b++) {
-                    repo = _c[_b];
-                    repo.ctx = this.ctx;
+            var _i, autoRegisteredRepos_1, _a, collectionName, repoInstanceName, Repo, repoInstance, pluginCtx, _b, autoRegisteredServices_1, _c, serviceInstanceName, Service, serviceInstance, _d, _e, repo, _f, _g, service, servicesWithInit;
+            return __generator(this, function (_h) {
+                switch (_h.label) {
+                    case 0:
+                        if (this.dbOpts) {
+                            for (_i = 0, autoRegisteredRepos_1 = exports.autoRegisteredRepos; _i < autoRegisteredRepos_1.length; _i++) {
+                                _a = autoRegisteredRepos_1[_i], collectionName = _a.collectionName, repoInstanceName = _a.repoInstanceName, Repo = _a.Repo;
+                                repoInstance = new Repo(collectionName, this.db, this.dbClient);
+                                this.repos[repoInstanceName] = repoInstance;
+                                initLog.info("Registered repo ".concat(repoInstanceName));
+                            }
+                        }
+                        else if (exports.autoRegisteredRepos.length > 0) {
+                            FlinkLog_1.log.warn("No db configured but found repo(s)");
+                        }
+                        pluginCtx = this.plugins.reduce(function (out, plugin) {
+                            if (out[plugin.id]) {
+                                throw new Error("Plugin ".concat(plugin.id, " is already registered"));
+                            }
+                            out[plugin.id] = plugin.ctx;
+                            return out;
+                        }, {});
+                        // Instantiate services (ctx not yet available - constructors must not access it)
+                        for (_b = 0, autoRegisteredServices_1 = exports.autoRegisteredServices; _b < autoRegisteredServices_1.length; _b++) {
+                            _c = autoRegisteredServices_1[_b], serviceInstanceName = _c.serviceInstanceName, Service = _c.Service;
+                            serviceInstance = new Service();
+                            this.services[serviceInstanceName] = serviceInstance;
+                            initLog.info("Registered service ".concat(serviceInstanceName));
+                        }
+                        this._ctx = {
+                            repos: this.repos,
+                            plugins: pluginCtx,
+                            auth: this.auth,
+                            agents: this.agents,
+                            services: this.services,
+                        };
+                        // Inject context into repos
+                        for (_d = 0, _e = Object.values(this.repos); _d < _e.length; _d++) {
+                            repo = _e[_d];
+                            repo.ctx = this.ctx;
+                        }
+                        // Inject context into services, then call onInit() in parallel
+                        for (_f = 0, _g = Object.values(this.services); _f < _g.length; _f++) {
+                            service = _g[_f];
+                            service.ctx = this.ctx;
+                        }
+                        servicesWithInit = Object.values(this.services).filter(function (s) { return typeof s.onInit === "function"; });
+                        if (!(servicesWithInit.length > 0)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, Promise.all(servicesWithInit.map(function (s) { return s.onInit(); }))];
+                    case 1:
+                        _h.sent();
+                        _h.label = 2;
+                    case 2: return [2 /*return*/];
                 }
-                return [2 /*return*/];
             });
         });
     };

package/dist/src/FlinkContext.d.ts

@@ -1,6 +1,7 @@
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkRepo } from "./FlinkRepo";
 import { FlinkAgent } from "./ai/FlinkAgent";
+import { FlinkService } from "./FlinkService";
 export interface FlinkContext<P = any> {
     repos: {
         [x: string]: FlinkRepo<any, any>;
@@ -30,4 +31,23 @@ export interface FlinkContext<P = any> {
     agents?: {
         [x: string]: FlinkAgent<any>;
     };
+    /**
+     * Optional services namespace for shared business logic.
+     *
+     * Define services directly in your context interface:
+     *
+     * @example
+     * interface AppCtx extends FlinkContext<PluginCtx> {
+     *     repos: {
+     *         carRepo: CarRepo;
+     *     };
+     *     services: {
+     *         carService: CarService;
+     *         orderService: OrderService;
+     *     };
+     * }
+     */
+    services?: {
+        [x: string]: FlinkService<any>;
+    };
 }

package/dist/src/FlinkService.d.ts

@@ -0,0 +1,38 @@
+import { FlinkContext } from "./FlinkContext";
+/**
+ * Base class for Flink services - optional business logic layer.
+ *
+ * Services provide a place for shared business logic that can be used by
+ * handlers, jobs, agents, and other services via `ctx.services`.
+ *
+ * Context (`this.ctx`) is not available in the constructor - use `onInit()`
+ * for any setup that requires context.
+ *
+ * @example
+ * ```typescript
+ * class CarService extends FlinkService<AppCtx> {
+ *     async onInit() {
+ *         // Called after all services are instantiated and ctx is fully wired
+ *     }
+ *
+ *     async getWithOwner(carId: string) {
+ *         const car = await this.ctx.repos.carRepo.getById(carId);
+ *         if (!car) throw notFound("Car not found");
+ *         return car;
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class FlinkService<C extends FlinkContext> {
+    private _ctx?;
+    set ctx(ctx: FlinkContext);
+    get ctx(): C;
+    /**
+     * Optional async initialization hook called after all services are
+     * instantiated and ctx is fully wired (repos, plugins, agents, services all available).
+     *
+     * All service onInit() methods run in parallel via Promise.all.
+     * Do not depend on another service's onInit() having completed.
+     */
+    onInit?(): Promise<void>;
+}

package/dist/src/FlinkService.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlinkService = void 0;
+/**
+ * Base class for Flink services - optional business logic layer.
+ *
+ * Services provide a place for shared business logic that can be used by
+ * handlers, jobs, agents, and other services via `ctx.services`.
+ *
+ * Context (`this.ctx`) is not available in the constructor - use `onInit()`
+ * for any setup that requires context.
+ *
+ * @example
+ * ```typescript
+ * class CarService extends FlinkService<AppCtx> {
+ *     async onInit() {
+ *         // Called after all services are instantiated and ctx is fully wired
+ *     }
+ *
+ *     async getWithOwner(carId: string) {
+ *         const car = await this.ctx.repos.carRepo.getById(carId);
+ *         if (!car) throw notFound("Car not found");
+ *         return car;
+ *     }
+ * }
+ * ```
+ */
+var FlinkService = /** @class */ (function () {
+    function FlinkService() {
+    }
+    Object.defineProperty(FlinkService.prototype, "ctx", {
+        get: function () {
+            if (!this._ctx) {
+                throw new Error("FlinkService: ctx is not available in constructor. Use onInit() for setup logic.");
+            }
+            return this._ctx;
+        },
+        set: function (ctx) {
+            this._ctx = ctx;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return FlinkService;
+}());
+exports.FlinkService = FlinkService;

package/dist/src/TypeScriptCompiler.d.ts

@@ -21,6 +21,7 @@ declare class TypeScriptCompiler {
     private toolFiles;
     private agentFiles;
     private jobFiles;
+    private serviceFiles;
     /**
      * Tool ID registry for agent validation (built during segmentation)
      */
@@ -29,6 +30,7 @@ declare class TypeScriptCompiler {
      * Compiler plugins loaded from flink.config.js
      */
     private compilerPlugins;
+    private disableServices;
     /**
      * Extension files collected during segmentation, keyed by generatedFile name
      */
@@ -215,6 +217,10 @@ declare class TypeScriptCompiler {
      * Scans project for jobs so they can be registered during start.
      */
     parseJobs(): Promise<SourceFile>;
+    /**
+     * Scans project for services so they can be registered during start.
+     */
+    parseServices(): Promise<SourceFile>;
     /**
      * Generates a .flink/generatedXxx.ts file for a single compiler plugin extension.
      * Mirrors the same namespace-import + spread pattern used by parseJobs.

package/dist/src/TypeScriptCompiler.js

@@ -95,7 +95,7 @@ var perfLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.perf");
 var initLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
 var TypeScriptCompiler = /** @class */ (function () {
     function TypeScriptCompiler(cwd) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         /**
          * Handler schemas collected during parseHandlers, to be generated later
          */
@@ -112,6 +112,7 @@ var TypeScriptCompiler = /** @class */ (function () {
         this.toolFiles = [];
         this.agentFiles = [];
         this.jobFiles = [];
+        this.serviceFiles = [];
         /**
          * Tool ID registry for agent validation (built during segmentation)
          */
@@ -120,6 +121,7 @@ var TypeScriptCompiler = /** @class */ (function () {
          * Compiler plugins loaded from flink.config.js
          */
         this.compilerPlugins = [];
+        this.disableServices = false;
         /**
          * Extension files collected during segmentation, keyed by generatedFile name
          */
@@ -198,9 +200,10 @@ var TypeScriptCompiler = /** @class */ (function () {
         var loadTime = Date.now() - loadStartTime;
         var fileCount = this.project.getSourceFiles().length;
         perfLog.debug("\u2713 All source files loaded in ".concat(loadTime, "ms (").concat(fileCount, " files)"));
-        // Load compiler plugins from flink.config.js
+        // Load config from flink.config.js
         var flinkCfg = (0, loadFlinkConfig_1.loadFlinkConfig)(this.cwd);
         this.compilerPlugins = (_c = flinkCfg === null || flinkCfg === void 0 ? void 0 : flinkCfg.compilerPlugins) !== null && _c !== void 0 ? _c : [];
+        this.disableServices = (_d = flinkCfg === null || flinkCfg === void 0 ? void 0 : flinkCfg.disableServices) !== null && _d !== void 0 ? _d : false;
         if (this.compilerPlugins.length > 0) {
             initLog.info("Compiler plugins loaded (".concat(this.compilerPlugins.length, "):"), this.compilerPlugins.map(function (p) { return "".concat(p.package, " \u2192 ").concat(p.scanDir); }).join(", "));
         }
@@ -444,7 +447,7 @@ var TypeScriptCompiler = /** @class */ (function () {
         var _a;
         var startTime = Date.now();
         var allFiles = this.project.getSourceFiles();
-        var handlerTime = 0, repoTime = 0, toolTime = 0, agentTime = 0, jobTime = 0;
+        var handlerTime = 0, repoTime = 0, toolTime = 0, agentTime = 0, jobTime = 0, serviceTime = 0;
         for (var _i = 0, allFiles_1 = allFiles; _i < allFiles_1.length; _i++) {
             var sf = allFiles_1[_i];
             var filePath = sf.getFilePath();
@@ -491,6 +494,12 @@ var TypeScriptCompiler = /** @class */ (function () {
                 jobTime += Date.now() - fileStartTime;
                 continue;
             }
+            // Services: simple path check (opt-out via flink.config.js disableServices)
+            if (!this.disableServices && filePath.includes("src/services/")) {
+                this.serviceFiles.push(sf);
+                serviceTime += Date.now() - fileStartTime;
+                continue;
+            }
             // Extension dirs from compiler plugins
             for (var _b = 0, _c = this.compilerPlugins; _b < _c.length; _b++) {
                 var ext = _c[_b];
@@ -506,7 +515,7 @@ var TypeScriptCompiler = /** @class */ (function () {
         }
         var segmentTime = Date.now() - startTime;
         perfLog.debug("\u2713 File segmentation completed in ".concat(segmentTime, "ms ") +
-            "(".concat(this.handlerFiles.length, " handlers, ").concat(this.repoFiles.length, " repos, ").concat(this.toolFiles.length, " tools, ").concat(this.agentFiles.length, " agents, ").concat(this.jobFiles.length, " jobs)"));
+            "(".concat(this.handlerFiles.length, " handlers, ").concat(this.repoFiles.length, " repos, ").concat(this.toolFiles.length, " tools, ").concat(this.agentFiles.length, " agents, ").concat(this.jobFiles.length, " jobs, ").concat(this.serviceFiles.length, " services)"));
     };
     /**
      * Detects if the project is using ESM (ECMAScript Modules)
@@ -1172,7 +1181,7 @@ var TypeScriptCompiler = /** @class */ (function () {
                         extensionImports = this.compilerPlugins
                             .map(function (ext) { return "import \"./".concat(ext.generatedFile).concat(_this.isEsm ? ".js" : "", "\";"); })
                             .join("\n");
-                        sf = this.createSourceFile(["start.ts"], "// Generated ".concat(new Date(), "\nimport \"./generatedHandlers").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedRepos").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedTools").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedAgents").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedJobs").concat(this.isEsm ? ".js" : "", "\";\n").concat(extensionImports ? extensionImports + "\n" : "", "import \"..").concat(appEntryScript.replace(/\.ts/g, "")).concat(this.isEsm ? ".js" : "", "\";\nexport default {}; // Export an empty object to make it a module\n"));
+                        sf = this.createSourceFile(["start.ts"], "// Generated ".concat(new Date(), "\nimport \"./generatedHandlers").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedRepos").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedTools").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedAgents").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedJobs").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedServices").concat(this.isEsm ? ".js" : "", "\";\n").concat(extensionImports ? extensionImports + "\n" : "", "import \"..").concat(appEntryScript.replace(/\.ts/g, "")).concat(this.isEsm ? ".js" : "", "\";\nexport default {}; // Export an empty object to make it a module\n"));
                         // Defer save until batch save at end (performance optimization)
                         return [2 /*return*/, sf];
                 }
@@ -1518,6 +1527,42 @@ var TypeScriptCompiler = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Scans project for services so they can be registered during start.
+     */
+    TypeScriptCompiler.prototype.parseServices = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var startTime, generatedFile, servicesArr, imports, serviceElements, _i, _a, sf, serviceParseTime;
+            return __generator(this, function (_b) {
+                if (this.disableServices) {
+                    initLog.info("Services disabled via flink.config.js (disableServices: true)");
+                }
+                startTime = Date.now();
+                generatedFile = this.createSourceFile(["generatedServices.ts"], "// Generated ".concat(new Date(), "\nimport { autoRegisteredServices } from \"@flink-app/flink\";\nexport const services: any[] = [];\nautoRegisteredServices.push(...services);\n    "));
+                servicesArr = generatedFile.getVariableDeclarationOrThrow("services").getFirstDescendantByKindOrThrow(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                imports = [];
+                serviceElements = [];
+                for (_i = 0, _a = this.serviceFiles; _i < _a.length; _i++) {
+                    sf = _a[_i];
+                    console.log("Detected service ".concat(sf.getBaseName()));
+                    imports.push({
+                        defaultImport: sf.getBaseNameWithoutExtension(),
+                        moduleSpecifier: this.getModuleSpecifier(generatedFile, sf),
+                    });
+                    serviceElements.push("{serviceInstanceName: \"".concat((0, utils_1.getRepoInstanceName)(sf.getBaseName()), "\", Service: ").concat(sf.getBaseNameWithoutExtension(), "}"));
+                }
+                servicesArr.addElements(serviceElements);
+                generatedFile.addImportDeclarations(imports);
+                // Cleanup: forget service file nodes to reduce memory overhead
+                this.serviceFiles.forEach(function (sf) {
+                    sf.getClasses().forEach(function (cls) { return cls.forget(); });
+                });
+                serviceParseTime = Date.now() - startTime;
+                perfLog.info("\u2713 Service parsing completed in ".concat(serviceParseTime, "ms (").concat(serviceElements.length, " services)"));
+                return [2 /*return*/, generatedFile];
+            });
+        });
+    };
     /**
      * Generates a .flink/generatedXxx.ts file for a single compiler plugin extension.
      * Mirrors the same namespace-import + spread pattern used by parseJobs.

package/dist/src/index.d.ts

@@ -10,6 +10,7 @@ export * from "./FlinkRequestContext";
 export * from "./FlinkErrors";
 export * from "./FlinkPlugin";
 export * from "./FlinkJob";
+export * from "./FlinkService";
 export { LeaderElection } from "./LeaderElection";
 export type { LeaderElectionOptions } from "./LeaderElection";
 export * from "./auth/FlinkAuthUser";

package/dist/src/index.js

@@ -27,6 +27,7 @@ __exportStar(require("./FlinkRequestContext"), exports);
 __exportStar(require("./FlinkErrors"), exports);
 __exportStar(require("./FlinkPlugin"), exports);
 __exportStar(require("./FlinkJob"), exports);
+__exportStar(require("./FlinkService"), exports);
 var LeaderElection_1 = require("./LeaderElection");
 Object.defineProperty(exports, "LeaderElection", { enumerable: true, get: function () { return LeaderElection_1.LeaderElection; } });
 __exportStar(require("./auth/FlinkAuthUser"), exports);

package/dist/src/utils/loadFlinkConfig.d.ts

@@ -26,6 +26,8 @@ export interface FlinkConfig {
     logging?: LoggingConfig;
     /** Compiler plugins that extend auto-discovery to custom directories */
     compilerPlugins?: FlinkCompilerPlugin[];
+    /** Disable auto-discovery of services from src/services/. Default: false */
+    disableServices?: boolean;
 }
 /**
  * Load Flink configuration from flink.config.js in current working directory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.82",
+  "version": "2.0.0-alpha.84",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/src/FlinkApp.ts

@@ -23,6 +23,7 @@ import { log } from "./FlinkLog";
 import { FlinkLogFactory } from "./FlinkLogFactory";
 import { FlinkPlugin } from "./FlinkPlugin";
 import { FlinkRepo } from "./FlinkRepo";
+import { FlinkService } from "./FlinkService";
 import { FlinkResponse } from "./FlinkResponse";
 import { requestContext } from "./FlinkRequestContext";
 import { StreamWriterFactory } from "./handlers/StreamWriterFactory";
@@ -88,6 +89,15 @@ export const autoRegisteredTools: FlinkToolFile[] = [];
  */
 export const autoRegisteredAgents: FlinkAgentFile<any, any>[] = [];
 
+/**
+ * This will be populated at compile time when the apps services
+ * are picked up by TypeScript compiler
+ */
+export const autoRegisteredServices: {
+    serviceInstanceName: string;
+    Service: any;
+}[] = [];
+
 export interface FlinkOptions {
     /**
      * Name of application, will only show in logs and in HTTP header.
@@ -338,6 +348,7 @@ export class FlinkApp<C extends FlinkContext> {
     private onError?: FlinkOptions["onError"];
 
     private repos: { [x: string]: FlinkRepo<C, any> } = {};
+    private services: { [x: string]: FlinkService<C> } = {};
 
     private llmAdapters: Map<string, LLMAdapter> = new Map();
     private tools: { [x: string]: ToolExecutor<C> } = {};
@@ -1443,16 +1454,35 @@ export class FlinkApp<C extends FlinkContext> {
             return out;
         }, {});
 
+        // Instantiate services (ctx not yet available - constructors must not access it)
+        for (const { serviceInstanceName, Service } of autoRegisteredServices) {
+            const serviceInstance: FlinkService<C> = new Service();
+            this.services[serviceInstanceName] = serviceInstance;
+            initLog.info(`Registered service ${serviceInstanceName}`);
+        }
+
         this._ctx = {
             repos: this.repos,
             plugins: pluginCtx,
             auth: this.auth,
             agents: this.agents,
+            services: this.services,
         } as C;
 
+        // Inject context into repos
         for (const repo of Object.values(this.repos)) {
             repo.ctx = this.ctx;
         }
+
+        // Inject context into services, then call onInit() in parallel
+        for (const service of Object.values(this.services)) {
+            service.ctx = this.ctx;
+        }
+
+        const servicesWithInit = Object.values(this.services).filter((s) => typeof s.onInit === "function");
+        if (servicesWithInit.length > 0) {
+            await Promise.all(servicesWithInit.map((s) => s.onInit!()));
+        }
     }
 
     /**

package/src/FlinkContext.ts

@@ -1,6 +1,7 @@
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkRepo } from "./FlinkRepo";
 import { FlinkAgent } from "./ai/FlinkAgent";
+import { FlinkService } from "./FlinkService";
 
 export interface FlinkContext<P = any> {
     repos: {
@@ -34,4 +35,24 @@ export interface FlinkContext<P = any> {
     agents?: {
         [x: string]: FlinkAgent<any>;
     };
+
+    /**
+     * Optional services namespace for shared business logic.
+     *
+     * Define services directly in your context interface:
+     *
+     * @example
+     * interface AppCtx extends FlinkContext<PluginCtx> {
+     *     repos: {
+     *         carRepo: CarRepo;
+     *     };
+     *     services: {
+     *         carService: CarService;
+     *         orderService: OrderService;
+     *     };
+     * }
+     */
+    services?: {
+        [x: string]: FlinkService<any>;
+    };
 }

package/src/FlinkService.ts

@@ -0,0 +1,49 @@
+import { FlinkContext } from "./FlinkContext";
+
+/**
+ * Base class for Flink services - optional business logic layer.
+ *
+ * Services provide a place for shared business logic that can be used by
+ * handlers, jobs, agents, and other services via `ctx.services`.
+ *
+ * Context (`this.ctx`) is not available in the constructor - use `onInit()`
+ * for any setup that requires context.
+ *
+ * @example
+ * ```typescript
+ * class CarService extends FlinkService<AppCtx> {
+ *     async onInit() {
+ *         // Called after all services are instantiated and ctx is fully wired
+ *     }
+ *
+ *     async getWithOwner(carId: string) {
+ *         const car = await this.ctx.repos.carRepo.getById(carId);
+ *         if (!car) throw notFound("Car not found");
+ *         return car;
+ *     }
+ * }
+ * ```
+ */
+export abstract class FlinkService<C extends FlinkContext> {
+    private _ctx?: C;
+
+    set ctx(ctx: FlinkContext) {
+        this._ctx = ctx as C;
+    }
+
+    get ctx(): C {
+        if (!this._ctx) {
+            throw new Error("FlinkService: ctx is not available in constructor. Use onInit() for setup logic.");
+        }
+        return this._ctx;
+    }
+
+    /**
+     * Optional async initialization hook called after all services are
+     * instantiated and ctx is fully wired (repos, plugins, agents, services all available).
+     *
+     * All service onInit() methods run in parallel via Promise.all.
+     * Do not depend on another service's onInit() having completed.
+     */
+    onInit?(): Promise<void>;
+}

package/src/TypeScriptCompiler.ts

@@ -45,6 +45,7 @@ class TypeScriptCompiler {
     private toolFiles: SourceFile[] = [];
     private agentFiles: SourceFile[] = [];
     private jobFiles: SourceFile[] = [];
+    private serviceFiles: SourceFile[] = [];
 
     /**
      * Tool ID registry for agent validation (built during segmentation)
@@ -55,6 +56,7 @@ class TypeScriptCompiler {
      * Compiler plugins loaded from flink.config.js
      */
     private compilerPlugins: FlinkCompilerPlugin[] = [];
+    private disableServices = false;
 
     /**
      * Extension files collected during segmentation, keyed by generatedFile name
@@ -227,9 +229,10 @@ class TypeScriptCompiler {
         const fileCount = this.project.getSourceFiles().length;
         perfLog.debug(`✓ All source files loaded in ${loadTime}ms (${fileCount} files)`);
 
-        // Load compiler plugins from flink.config.js
+        // Load config from flink.config.js
         const flinkCfg = loadFlinkConfig(this.cwd);
         this.compilerPlugins = flinkCfg?.compilerPlugins ?? [];
+        this.disableServices = flinkCfg?.disableServices ?? false;
 
         if (this.compilerPlugins.length > 0) {
             initLog.info(
@@ -429,7 +432,8 @@ class TypeScriptCompiler {
             repoTime = 0,
             toolTime = 0,
             agentTime = 0,
-            jobTime = 0;
+            jobTime = 0,
+            serviceTime = 0;
 
         for (const sf of allFiles) {
             const filePath = sf.getFilePath();
@@ -484,6 +488,13 @@ class TypeScriptCompiler {
                 continue;
             }
 
+            // Services: simple path check (opt-out via flink.config.js disableServices)
+            if (!this.disableServices && filePath.includes("src/services/")) {
+                this.serviceFiles.push(sf);
+                serviceTime += Date.now() - fileStartTime;
+                continue;
+            }
+
             // Extension dirs from compiler plugins
             for (const ext of this.compilerPlugins) {
                 if (filePath.includes(ext.scanDir)) {
@@ -500,7 +511,7 @@ class TypeScriptCompiler {
         const segmentTime = Date.now() - startTime;
         perfLog.debug(
             `✓ File segmentation completed in ${segmentTime}ms ` +
-                `(${this.handlerFiles.length} handlers, ${this.repoFiles.length} repos, ${this.toolFiles.length} tools, ${this.agentFiles.length} agents, ${this.jobFiles.length} jobs)`
+                `(${this.handlerFiles.length} handlers, ${this.repoFiles.length} repos, ${this.toolFiles.length} tools, ${this.agentFiles.length} agents, ${this.jobFiles.length} jobs, ${this.serviceFiles.length} services)`
         );
     }
 
@@ -1205,6 +1216,7 @@ import "./generatedRepos${this.isEsm ? ".js" : ""}";
 import "./generatedTools${this.isEsm ? ".js" : ""}";
 import "./generatedAgents${this.isEsm ? ".js" : ""}";
 import "./generatedJobs${this.isEsm ? ".js" : ""}";
+import "./generatedServices${this.isEsm ? ".js" : ""}";
 ${extensionImports ? extensionImports + "\n" : ""}import "..${appEntryScript.replace(/\.ts/g, "")}${this.isEsm ? ".js" : ""}";
 export default {}; // Export an empty object to make it a module
 `
@@ -1604,6 +1616,59 @@ autoRegisteredJobs.push(...jobs);
         return generatedFile;
     }
 
+    /**
+     * Scans project for services so they can be registered during start.
+     */
+    async parseServices() {
+        if (this.disableServices) {
+            initLog.info("Services disabled via flink.config.js (disableServices: true)");
+        }
+
+        const startTime = Date.now();
+
+        const generatedFile = this.createSourceFile(
+            ["generatedServices.ts"],
+            `// Generated ${new Date()}
+import { autoRegisteredServices } from "@flink-app/flink";
+export const services: any[] = [];
+autoRegisteredServices.push(...services);
+    `
+        );
+
+        const servicesArr = generatedFile.getVariableDeclarationOrThrow("services").getFirstDescendantByKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+
+        const imports: OptionalKind<ImportDeclarationStructure>[] = [];
+
+        const serviceElements: string[] = [];
+
+        for (const sf of this.serviceFiles) {
+            console.log(`Detected service ${sf.getBaseName()}`);
+
+            imports.push({
+                defaultImport: sf.getBaseNameWithoutExtension(),
+                moduleSpecifier: this.getModuleSpecifier(generatedFile, sf),
+            });
+
+            serviceElements.push(
+                `{serviceInstanceName: "${getRepoInstanceName(sf.getBaseName())}", Service: ${sf.getBaseNameWithoutExtension()}}`
+            );
+        }
+
+        servicesArr.addElements(serviceElements);
+
+        generatedFile.addImportDeclarations(imports);
+
+        // Cleanup: forget service file nodes to reduce memory overhead
+        this.serviceFiles.forEach((sf) => {
+            sf.getClasses().forEach((cls) => cls.forget());
+        });
+
+        const serviceParseTime = Date.now() - startTime;
+        perfLog.info(`✓ Service parsing completed in ${serviceParseTime}ms (${serviceElements.length} services)`);
+
+        return generatedFile;
+    }
+
     /**
      * Generates a .flink/generatedXxx.ts file for a single compiler plugin extension.
      * Mirrors the same namespace-import + spread pattern used by parseJobs.

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./FlinkRequestContext";
 export * from "./FlinkErrors";
 export * from "./FlinkPlugin";
 export * from "./FlinkJob";
+export * from "./FlinkService";
 export { LeaderElection } from "./LeaderElection";
 export type { LeaderElectionOptions } from "./LeaderElection";
 export * from "./auth/FlinkAuthUser";

package/src/utils/loadFlinkConfig.ts

@@ -30,6 +30,8 @@ export interface FlinkConfig {
     logging?: LoggingConfig;
     /** Compiler plugins that extend auto-discovery to custom directories */
     compilerPlugins?: FlinkCompilerPlugin[];
+    /** Disable auto-discovery of services from src/services/. Default: false */
+    disableServices?: boolean;
 }
 
 /**