@maestro-js/service-registry 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,286 @@
+# Service Registry
+
+The foundation of the maestro-js provider pattern. Provides a generic service locator with deferred resolution via Proxy, allowing consumers to obtain a reference to a service before it has been registered.
+
+## The Provider Pattern
+
+Every major maestro-js package follows the same five-part provider pattern built on `@maestro-js/service-registry`:
+
+1. **`create(config)`** -- Factory that instantiates a service with a driver.
+2. **`Provider.register(name, service)`** -- Registers the instance in a named registry.
+3. **`provider(key)`** -- Resolves a named instance (deferred via Proxy, so resolution can happen before registration).
+4. **Facade** -- The exported const spreads `provider('default')` so methods can be called directly (e.g., `Cache.get(key)` instead of `Cache.provider('default').get(key)`).
+5. **`drivers`** -- Factory functions for pluggable implementations (e.g., `Cache.drivers.redis(...)`, `Cache.drivers.mockRedis(...)`).
+
+Registration order does not matter as long as registration happens before the first method call on a resolved proxy. The Proxy intercepts property access and defers the actual lookup until invocation time.
+
+## API Reference
+
+### `ServiceRegistry.createRegistry(proxy)`
+
+Create a typed registry that stores services by name and resolves them through a caller-supplied proxy function.
+
+```ts
+function createRegistry<Name extends string, Item>(
+  proxy: (getItem: () => Item) => Item
+): Registry<Name, Item>
+```
+
+The `proxy` parameter receives a lazy getter (`getItem`) so that the actual service lookup is deferred until the returned reference is used. Returns an object with four methods:
+
+- **`register(name, item)`** -- Store a service under the given name.
+- **`resolve(name)`** -- Return a proxied reference to the named service. Throws if the service is not registered at call time (i.e., when a method on the proxy is actually invoked).
+- **`has(name)`** -- Check whether a service has been registered under the given name.
+- **`list()`** -- Return all registered service names.
+
+Error behavior on resolve: if a method is called on the proxy before registration, throws `No service registered for "<name>". Available: <registered names>`.
+
+### `ServiceRegistry.proxyFunctionsForObject(getItem)`
+
+Default proxy function for services whose members are all functions.
+
+```ts
+function proxyFunctionsForObject<Item extends Record<keyof Item, (...args: any) => unknown>>(
+  getItem: () => Item
+): Item
+```
+
+Returns a `Proxy` that intercepts property access and wraps each property in a function that defers to the real service at call time. The Proxy also implements `has`, `ownKeys`, and `getOwnPropertyDescriptor` traps for full introspection support.
+
+Use this for any service whose public interface is entirely methods. Most packages use it directly:
+
+```ts
+const registry = ServiceRegistry.createRegistry<Cache.Provider.Key, Cache.CacheService>(
+  ServiceRegistry.proxyFunctionsForObject
+)
+```
+
+### Custom Proxy Functions
+
+When a service has non-function members or needs special delegation logic, supply a custom proxy instead of `proxyFunctionsForObject`. The Events package does this to handle its `create` method (which returns a typed event handle rather than delegating directly):
+
+```ts
+const registry = ServiceRegistry.createRegistry<Events.Provider.Key, Events.EventsService>((getItem) => {
+  return new Proxy(
+    {},
+    {
+      get(target, property: keyof Events.EventsService) {
+        if (property === 'create') {
+          return getCreateEventFn(() => getItem())
+        } else {
+          return (...args: any) => {
+            const item = getItem()
+            const func = item[property] as (...args: any) => unknown
+            return func(...args)
+          }
+        }
+      }
+    }
+  ) as Events.EventsService
+})
+```
+
+## How to Create a New Package Using ServiceRegistry
+
+Follow this step-by-step pattern to build a new provider-based package.
+
+### Step 1: Define the service interface
+
+Declare a namespace with the service interface and provider types:
+
+```ts
+type KeysWithFallback = keyof MyPkg.Provider.Keys extends never ? { default: unknown } : MyPkg.Provider.Keys
+
+export declare namespace MyPkg {
+  export interface MyPkgService {
+    doSomething(input: string): Promise<string>
+    doOther(id: number): Promise<void>
+  }
+
+  namespace Provider {
+    export interface MyPkgServiceConfig {
+      driver: MyPkgDriver
+    }
+
+    type Key = keyof KeysWithFallback
+    export interface Keys {}
+  }
+}
+```
+
+The `KeysWithFallback` type ensures `Key` resolves to `'default'` when consumers have not augmented the `Keys` interface.
+
+### Step 2: Write the create factory
+
+```ts
+function create(config: MyPkg.Provider.MyPkgServiceConfig): MyPkg.MyPkgService {
+  const driver = config.driver
+
+  async function doSomething(input: string): Promise<string> {
+    return driver.process(input)
+  }
+
+  async function doOther(id: number): Promise<void> {
+    await driver.execute(id)
+  }
+
+  return { doSomething, doOther }
+}
+```
+
+### Step 3: Create the registry and wire up Provider/provider/facade
+
+```ts
+import { ServiceRegistry } from '@maestro-js/service-registry'
+
+const registry = ServiceRegistry.createRegistry<MyPkg.Provider.Key, MyPkg.MyPkgService>(
+  ServiceRegistry.proxyFunctionsForObject
+)
+
+const Provider = {
+  create,
+  register: registry.register
+}
+
+function provider(key: MyPkg.Provider.Key) {
+  return registry.resolve(key)
+}
+
+const facade = provider('default')
+
+export const MyPkg = {
+  Provider,
+  provider,
+  doSomething: facade.doSomething,
+  doOther: facade.doOther,
+  drivers: {
+    myDriver: myDriverFactory
+  }
+}
+```
+
+### Step 4: Consumer registration and usage
+
+```ts
+import { MyPkg } from '@maestro-js/my-pkg'
+
+// Registration (typically at app startup)
+MyPkg.Provider.register('default', MyPkg.Provider.create({
+  driver: MyPkg.drivers.myDriver({ /* config */ })
+}))
+
+// Usage (can import and reference before registration)
+await MyPkg.doSomething('hello')
+```
+
+## Common Patterns
+
+### Standard usage (Cache, Db)
+
+Most packages pass `proxyFunctionsForObject` directly and spread the resolved proxy into the facade:
+
+```ts
+// From packages/cache/src/index.ts
+const registry = ServiceRegistry.createRegistry<Cache.Provider.Key, Cache.CacheService>(
+  ServiceRegistry.proxyFunctionsForObject
+)
+
+const Provider = {
+  create,
+  register: registry.register
+}
+
+function provider(key: Cache.Provider.Key) {
+  const service = registry.resolve(key)
+  return {
+    has: service.has,
+    get: service.get,
+    set: service.set,
+    del: service.del,
+    flush: service.flush,
+    remember: service.remember,
+    item: service.item,
+    lock: service.lock
+  }
+}
+
+export const Cache = {
+  Provider,
+  ...provider('default'),
+  provider,
+  drivers: {
+    redis: redisCacheDriver,
+    mockRedis: mockRedisCacheDriver
+  }
+}
+```
+
+### Direct resolve (Db, Events)
+
+Some packages resolve directly without destructuring in the provider function:
+
+```ts
+// From packages/events/src/index.ts
+function provider(key: Events.Provider.Key) {
+  return registry.resolve(key)
+}
+
+const facade = provider('default')
+
+export const Events = {
+  provider,
+  Provider,
+  addListener: facade.addListener,
+  removeListener: facade.removeListener,
+  emit: facade.emit,
+  create: facade.create,
+  removeAllListeners: facade.removeAllListeners,
+  drivers: { /* ... */ }
+}
+```
+
+### Multiple named providers
+
+Register additional named instances for multi-tenant or multi-backend scenarios:
+
+```ts
+Db.Provider.register('default', Db.Provider.create({
+  driver: Db.drivers.mysql({ host: 'primary-db', database: 'app' })
+}))
+
+Db.Provider.register('analytics', Db.Provider.create({
+  driver: Db.drivers.mysql({ host: 'analytics-db', database: 'analytics' })
+}))
+
+// Use a named provider
+const analytics = Db.provider('analytics')
+await analytics.select('SELECT * FROM events WHERE date > ?', ['2024-01-01'])
+```
+
+## Cross-Package Integration
+
+ServiceRegistry is the foundation layer. The dependency graph flows as:
+
+- **ServiceRegistry** -- depended on by Cache, CacheControl, Context, Crypt, Db, Events, Exceptions, Hash, Mail, Metrics, Queue, RecurringJobs, Broadcast
+- No runtime dependencies of its own
+- Packages that do NOT use ServiceRegistry: Log (uses a simpler singleton), Helpers, Sql (pure utilities)
+
+When building or debugging any provider-based package, the resolution flow is:
+
+1. Import triggers `ServiceRegistry.createRegistry(...)`, creating the internal `Map`.
+2. `provider('default')` is called immediately to build the facade, returning a Proxy.
+3. At app startup, `Provider.register('default', Provider.create({...}))` populates the Map.
+4. First actual method call on the facade hits the Proxy, which calls `getItem()`, which resolves from the Map.
+
+If a method is invoked before registration, step 4 throws with the descriptive error listing available registrations.
+
+## Internal Implementation
+
+The registry stores services in a `Map<Name, Item>`. The `resolve` method does not look up the service immediately. Instead it calls the `proxy` function, passing a lazy `getItem` closure. That closure performs the Map lookup (and throws if missing) only when the proxy is actually used.
+
+The `proxyFunctionsForObject` proxy creates an empty object wrapped in a `Proxy` with these traps:
+
+- **`get`** -- Returns a function that calls `getItem()` at invocation time and delegates to the real method.
+- **`has`** -- Checks property existence on the resolved item.
+- **`ownKeys`** -- Returns keys of the resolved item.
+- **`getOwnPropertyDescriptor`** -- Returns descriptors from the resolved item (all marked `configurable` and `enumerable`).

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Service Registry — a generic service locator with deferred resolution.
+ *
+ * Services are registered by name and resolved lazily through a proxy, allowing
+ * consumers to obtain a reference to a service before it has been registered.
+ * Method calls on the proxy are forwarded to the real implementation at invocation
+ * time, so registration order doesn't matter as long as it happens before first use.
+ */
+interface Registry<Name extends string, Item> {
+    register(name: Name, item: Item): void;
+    resolve(name: Name): Item;
+    has(name: Name): boolean;
+    list(): Name[];
+}
+/**
+ * Creates a typed registry that stores services by name and resolves them through
+ * a caller-supplied proxy function. The proxy receives a lazy getter so that the
+ * actual service lookup is deferred until the returned reference is used.
+ *
+ * @param proxy - A function that wraps a deferred getter into a proxy object.
+ *                Use `proxyFunctionsForObject` for services whose members are all functions.
+ *                Supply a custom proxy when you need special handling (e.g. partial delegation).
+ */
+declare function createRegistry<Name extends string, Item>(proxy: (getItem: () => Item) => Item): Registry<Name, Item>;
+/**
+ * Default proxy function for services whose members are all functions.
+ *
+ * Returns a Proxy that intercepts property access and wraps each property in a
+ * function that defers to the real service at call time. This means `resolve()`
+ * can return a usable reference immediately — the actual service only needs to
+ * be registered before the first method call.
+ */
+declare function proxyFunctionsForObject<Item extends Record<keyof Item, (...args: any) => unknown>>(getItem: () => Item): Item;
+declare const ServiceRegistry: {
+    createRegistry: typeof createRegistry;
+    proxyFunctionsForObject: typeof proxyFunctionsForObject;
+};
+
+export { ServiceRegistry };

package/dist/index.js

@@ -0,0 +1,50 @@
+// src/index.ts
+function createRegistry(proxy) {
+  const map = /* @__PURE__ */ new Map();
+  function register(name, item) {
+    map.set(name, item);
+  }
+  function resolve(name) {
+    return proxy(() => {
+      if (!map.has(name)) {
+        const available = [...map.keys()].join(", ");
+        throw new Error(`No service registered for "${name}". Available: ${available}`);
+      }
+      return map.get(name);
+    });
+  }
+  function has(name) {
+    return map.has(name);
+  }
+  return { register, resolve, has, list: () => [...map.keys()] };
+}
+function proxyFunctionsForObject(getItem) {
+  return new Proxy(
+    {},
+    {
+      get(_, property) {
+        return (...args) => {
+          const item = getItem();
+          const func = item[property];
+          return func.apply(item, args);
+        };
+      },
+      has(_, property) {
+        return property in getItem();
+      },
+      ownKeys() {
+        return Reflect.ownKeys(getItem());
+      },
+      getOwnPropertyDescriptor(_, property) {
+        return { configurable: true, enumerable: true, value: getItem()[property] };
+      }
+    }
+  );
+}
+var ServiceRegistry = {
+  createRegistry,
+  proxyFunctionsForObject
+};
+export {
+  ServiceRegistry
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@maestro-js/service-registry",
+  "description": "Use when working with @maestro-js/service-registry. The foundational service locator package that provides deferred resolution via Proxy. Covers createRegistry, proxyFunctionsForObject, register/resolve pattern, custom proxy functions, and the standard Provider pattern used by nearly every other maestro-js package (Cache, Db, Events, Mail, Queue, etc.). Trigger when creating new provider-based packages, debugging service resolution, understanding deferred proxies, or wiring up named service instances.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'No tests yet'",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}