@wirestate/lit 0.7.0-experimental.1 → 0.7.0-experimental.2

package/cjs/development/index.js

@@ -9,13 +9,13 @@ var tslib = require('tslib');
  *
  * @group Context
  */
-var IOC_CONTAINER_KEY = Symbol("ContainerContext");
+var CONTAINER_KEY = Symbol("ContainerContext");
 /**
- * Lit context object for providing and consuming the IoC container.
+ * Lit context object for providing and consuming the container.
  *
  * @group Context
  */
-var IocContextObject = context.createContext(IOC_CONTAINER_KEY);
+var ContainerContext = context.createContext(CONTAINER_KEY);
 
 /**
  * Decorator to inject a service from the IoC container into a Lit element property.
@@ -61,9 +61,9 @@ function injection(optionsOrInjectionId) {
       nameOrContext.addInitializer(function () {
         var _this = this;
         new context.ContextConsumer(this, {
-          context: IocContextObject,
-          callback: function (it) {
-            protoOrTarget.set.call(_this, it.container.get(injectionId));
+          context: ContainerContext,
+          callback: function (container) {
+            protoOrTarget.set.call(_this, container.get(injectionId));
           },
           subscribe: !once
         });
@@ -72,9 +72,9 @@ function injection(optionsOrInjectionId) {
       // Experimental decorators branch.
       protoOrTarget.constructor.addInitializer(function (element) {
         new context.ContextConsumer(element, {
-          context: IocContextObject,
-          callback: function (it) {
-            element[nameOrContext] = it.container.get(injectionId);
+          context: ContainerContext,
+          callback: function (container) {
+            element[nameOrContext] = container.get(injectionId);
           },
           subscribe: !once
         });
@@ -83,6 +83,41 @@ function injection(optionsOrInjectionId) {
   };
 }
 
+/**
+ * Hook (consumer) to access the active container from the nearest parent context.
+ *
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
+ *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @returns An instance of {@link UseContainerValue}.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private container: UseContainerValue = useContainer(this);
+ *
+ *   public render() {
+ *     return html`<div>${this.container.value.isBound(MyService)}</div>`;
+ *   }
+ * }
+ * ```
+ */
+function useContainer(host) {
+  var current = {
+    value: null
+  };
+  new context.ContextConsumer(host, {
+    context: ContainerContext,
+    callback: function (container) {
+      current.value = container;
+    }
+  });
+  return current;
+}
+
 /**
  * Hook (controller) to inject a service from the IoC container.
  *
@@ -126,10 +161,48 @@ function useInjection(host, optionsOrInjectionId) {
     injectionId: injectionId
   };
   new context.ContextConsumer(host, {
-    context: IocContextObject,
+    context: ContainerContext,
     subscribe: !once,
-    callback: function (it) {
-      current.value = it.container.get(injectionId);
+    callback: function (container) {
+      current.value = container.get(injectionId);
+    }
+  });
+  return current;
+}
+
+/**
+ * Hook (consumer) to access the active {@link WireScope} from the nearest parent context.
+ *
+ * @remarks
+ * The returned value updates when the nearest provided container changes.
+ *
+ * @group Consumption
+ *
+ * @param host - The host element.
+ * @returns An instance of {@link UseScopeValue}.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *   private scope: UseScopeValue = useScope(this);
+ *
+ *   public connectedCallback(): void {
+ *     super.connectedCallback();
+ *     this.scope.value.emitEvent("UI_READY");
+ *   }
+ * }
+ * ```
+ */
+function useScope(host) {
+  var current = {
+    value: undefined,
+    injectionId: core.WireScope
+  };
+  new context.ContextConsumer(host, {
+    context: ContainerContext,
+    subscribe: true,
+    callback: function (container) {
+      current.value = container.get(core.WireScope);
     }
   });
   return current;
@@ -158,10 +231,10 @@ var OnCommandController = /** @class */function () {
     this.type = type;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: IocContextObject,
+      context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.CommandBus);
+      callback: function (container) {
+        _this.bus = container.get(core.CommandBus);
         if (host.isConnected) {
           _this.reregister();
         }
@@ -280,10 +353,10 @@ var OnEventController = /** @class */function () {
     this.types = types;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: IocContextObject,
+      context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.EventBus);
+      callback: function (container) {
+        _this.bus = container.get(core.EventBus);
         if (host.isConnected) {
           _this.resubscribe();
         }
@@ -442,10 +515,10 @@ var OnQueryController = /** @class */function () {
     this.type = type;
     this.handler = handler;
     new context.ContextConsumer(host, {
-      context: IocContextObject,
+      context: ContainerContext,
       subscribe: true,
-      callback: function (context) {
-        _this.bus = context.container.get(core.QueryBus);
+      callback: function (container) {
+        _this.bus = container.get(core.QueryBus);
         if (host.isConnected) {
           _this.reregister();
         }
@@ -541,116 +614,211 @@ function useOnQuery(host, _a) {
   return new OnQueryController(host, type, handler);
 }
 
+var ERROR_CODE_INVALID_ARGUMENTS = 2051;
+
 /**
- * Controller that provides an IoC container context to the host element and its children.
+ * Provider that exposes an IoC container context to the host element and its children.
  *
  * @remarks
- * It manages the lifecycle of the container and handles revision updates to notify consumers.
- * The container is created (or used from options) when the controller is instantiated.
- * Seed data is applied when the host connects.
+ * The provider supports two modes:
+ *
+ * - External mode: `container` is an existing {@link Container}. The
+ *   provider passes it through context and does not alter its lifecycle.
+ * - Managed mode: `options` is {@link CreateContainerOptions}. The provider
+ *   creates a container during construction without eager activation,
+ *   activates configured entries when the host connects, disposes the
+ *   container when the host disconnects, and recreates it on reconnect.
  *
  * @group Provision
  */
-var IocProviderController = /** @class */function () {
+var ContainerProvider = /** @class */function (_super) {
+  tslib.__extends(ContainerProvider, _super);
   /**
    * @param host - The host element.
    * @param options - Provisioning options.
-   * @param options.container - Optional existing container to use. If not provided, a new one will be created.
-   * @param options.seed - Optional seed data to apply to the container.
+   * @param options.container - External container instance to provide.
+   * @param options.options - Managed container creation options.
    */
-  function IocProviderController(host, _a) {
-    var _b = _a === void 0 ? {} : _a,
-      container = _b.container,
-      seed = _b.seed;
+  function ContainerProvider(host, options) {
     var _this = this;
-    this.host = host;
-    this.revision = 1;
-    this.host.addController(this);
-    this.container = container !== null && container !== void 0 ? container : core.createContainer();
-    this.seed = seed;
-    this.provider = new context.ContextProvider(host, {
-      context: IocContextObject,
-      initialValue: {
-        container: this.container,
-        revision: this.revision,
-        nextRevision: function () {
-          return _this.nextRevision();
+    if (!options.container && !options.options) {
+      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "ContainerProvider requires a valid container instance or creation options.");
+    } else if (options.container && options.options) {
+      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "ContainerProvider requires only container or valid options object to be provided.");
+    }
+    _this = _super.call(this, host, {
+      context: ContainerContext,
+      initialValue: options.container ? options.container : core.createContainer(tslib.__assign(tslib.__assign({}, options.options), {
+        activate: []
+      }))
+    }) || this;
+    _this.destroyed = false;
+    _this.options = options.options;
+    return _this;
+  }
+  ContainerProvider.prototype.hostConnected = function () {
+    var _a;
+    if (this.options) {
+      if (this.destroyed) {
+        this.value = core.createContainer(this.options);
+        this.destroyed = false;
+      } else {
+        if ((_a = this.options) === null || _a === void 0 ? void 0 : _a.activate) {
+          for (var _i = 0, _b = this.options.activate; _i < _b.length; _i++) {
+            var entry = _b[_i];
+            this.value.get(entry);
+          }
         }
       }
-    });
-  }
-  Object.defineProperty(IocProviderController.prototype, "value", {
-    /**
-     * @returns Current {@link IocContext} value served to child consumers.
-     */
-    get: function () {
-      return this.provider.value;
-    },
-    enumerable: false,
-    configurable: true
-  });
-  IocProviderController.prototype.hostConnected = function () {
-    if (this.seed) {
-      core.applySharedSeed(this.container, this.seed);
     }
+    _super.prototype.hostConnected.call(this);
   };
-  IocProviderController.prototype.hostDisconnected = function () {};
-  IocProviderController.prototype.nextRevision = function () {
-    var _this = this;
-    this.revision += 1;
-    this.provider.setValue({
-      container: this.container,
-      revision: this.revision,
-      nextRevision: function () {
-        return _this.nextRevision();
+  ContainerProvider.prototype.hostDisconnected = function () {
+    if (this.options) {
+      this.value.unbindAll();
+      this.destroyed = true;
+    }
+  };
+  return ContainerProvider;
+}(context.ContextProvider);
+
+/**
+ * Provider that exposes a managed child container for the host element's lifetime.
+ *
+ * @remarks
+ * The provider always owns a child container derived from the nearest parent
+ * {@link ContainerContext}. When connected, it creates a child container using
+ * the latest parent context, provides it to descendants, destroys it when the
+ * host disconnects, and replaces it whenever the parent container changes.
+ *
+ * @group Provision
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends LitElement {
+ *   private container = new SubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *       seeds: [[AuthService, { role: "admin" }]],
+ *     },
+ *   });
+ * }
+ * ```
+ */
+var SubContainerProvider = /** @class */function (_super) {
+  tslib.__extends(SubContainerProvider, _super);
+  /**
+   * @param host - The host element.
+   * @param options - Provisioning options, including child entries, eager activations, and seeds.
+   */
+  function SubContainerProvider(host, options) {
+    var _this = _super.call(this, host, {
+      context: ContainerContext
+    }) || this;
+    _this.parent = null;
+    _this.destroyed = true;
+    _this.options = options.options;
+    _this.consumer = new context.ContextConsumer(host, {
+      context: ContainerContext,
+      subscribe: true,
+      callback: function (context) {
+        var previousParent = _this.parent;
+        _this.parent = context;
+        if (host.isConnected) {
+          if (_this.destroyed || !_this.value || previousParent !== context) {
+            _this.destroyContainer();
+            _this.createContainer();
+          }
+        }
       }
     });
-    return this.revision;
+    return _this;
+  }
+  SubContainerProvider.prototype.hostConnected = function () {
+    if (this.parent && (this.destroyed || !this.value)) {
+      this.destroyContainer();
+      this.createContainer();
+    }
+    _super.prototype.hostConnected.call(this);
   };
-  return IocProviderController;
-}();
+  SubContainerProvider.prototype.hostDisconnected = function () {
+    this.destroyContainer();
+  };
+  /**
+   * Replaces the currently provided child container with a new one derived
+   * from the latest parent context.
+   */
+  SubContainerProvider.prototype.createContainer = function () {
+    var container = core.createContainer(tslib.__assign(tslib.__assign({}, this.options), {
+      parent: this.parent
+    }));
+    this.destroyed = false;
+    this.value = container;
+  };
+  /**
+   * Destroys the currently provided child container.
+   */
+  SubContainerProvider.prototype.destroyContainer = function () {
+    if (this.value && !this.destroyed) {
+      this.value.unbindAll();
+      this.destroyed = true;
+    }
+  };
+  return SubContainerProvider;
+}(context.ContextProvider);
 
 /**
  * Decorator that provides an IoC container to child components.
  *
  * @remarks
- * The container is provided via Lit context. It is created (or used from options) when the host connects.
+ * The container is provided via Lit context.
+ *
+ * - Pass `container` to expose an external container without taking
+ *   ownership.
+ * - Pass `options` to create a managed container during construction,
+ *   activate configured entries on connect, destroy it on disconnect, and
+ *   recreate it on reconnect.
  *
  * @group Provision
  *
  * @param options - Provisioning options.
- * @param options.container - Optional existing container to use, if not provided, a new one will be created.
- * @param options.seed - Optional seed data to apply to the container.
- * @returns An instance of {@link IocProviderDecorator}.
+ * @param options.container - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProviderDecorator}.
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   @containerProvide({
+ *     options: {
+ *       seed: { someData: "value" },
+ *       entries: [LoggerService],
+ *     },
+ *   })
+ *   private containerProvider!: ContainerProvider;
+ * }
+ * ```
  *
  * @example
  * ```typescript
  * class MyRootElement extends LitElement {
- *   @iocProvide({ seed: { someData: "value" } })
- *   private ioc!: IocProviderController;
+ *   @containerProvide({ container: container })
+ *   private containerProvider!: ContainerProvider;
  * }
  * ```
  */
-function iocProvide(_a) {
-  var _b = _a === void 0 ? {} : _a,
-    container = _b.container,
-    seed = _b.seed;
+function containerProvide(options) {
   return function (protoOrTarget, nameOrContext) {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        protoOrTarget.set.call(this, new IocProviderController(this, {
-          container: container,
-          seed: seed
-        }));
+        protoOrTarget.set.call(this, new ContainerProvider(this, options));
       });
     } else {
       var controller_1;
       protoOrTarget.constructor.addInitializer(function (element) {
-        controller_1 = new IocProviderController(element, {
-          container: container,
-          seed: seed
-        });
+        controller_1 = new ContainerProvider(element, options);
       });
       return {
         get: function () {
@@ -664,158 +832,49 @@ function iocProvide(_a) {
   };
 }
 
-var ERROR_CODE_INVALID_ARGUMENTS = 2051;
-
-/**
- * Controller that binds injectables to an IoC container for the host element's lifetime.
- *
- * @remarks
- * Entries are bound when the host connects and unbound when it disconnects.
- * If no `into` context is provided, it uses the nearest {@link IocProviderController}.
- * Seeds are applied before entries are bound.
- *
- * @group Provision
- *
- * @example
- * ```typescript
- * class MyComponent extends LitElement {
- *   private services = new InjectablesProviderController(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
- *     seeds: [[AuthService, { role: "admin" }]],
- *   });
- * }
- * ```
- */
-var InjectablesProviderController = /** @class */function () {
-  /**
-   * @param host - The host element.
-   * @param options - Provisioning options.
-   * @param options.entries - List of service entries to bind to the container.
-   * @param options.into - Target IoC context; if omitted, uses the nearest provider context.
-   * @param options.activate - List of service identifiers to activate immediately after binding.
-   * @param options.seeds - Seed data applied before binding.
-   */
-  function InjectablesProviderController(host, options) {
-    var _this = this;
-    var _a, _b, _c;
-    this.host = host;
-    /**
-     * Tracks the context to which entries are currently bound, for correct cleanup on disconnect.
-     */
-    this.boundContext = null;
-    this.host.addController(this);
-    this.entries = options.entries;
-    this.activate = (_a = options.activate) !== null && _a !== void 0 ? _a : null;
-    this.seeds = (_b = options.seeds) !== null && _b !== void 0 ? _b : null;
-    this.into = (_c = options.into) !== null && _c !== void 0 ? _c : null;
-    if (!this.into) {
-      // subscribe: false — binding happens once per connect, not on every revision update.
-      this.consumer = new context.ContextConsumer(host, {
-        context: IocContextObject,
-        subscribe: false,
-        callback: function (context) {
-          if (!host.isConnected) {
-            return;
-          }
-          _this.bind(context);
-        }
-      });
-    }
-  }
-  InjectablesProviderController.prototype.hostConnected = function () {
-    var _a;
-    if (!this.into) {
-      // ContextConsumer with subscribe:false only invokes the user callback once (provided flag stays true
-      // after disconnect). On reconnect we fall back to the cached consumer.value so bind() still fires.
-      if ((_a = this.consumer) === null || _a === void 0 ? void 0 : _a.value) {
-        this.bind(this.consumer.value);
-      }
-      return;
-    }
-    var context = typeof this.into === "function" ? this.into() : this.into;
-    if (!context) {
-      throw new core.WirestateError(ERROR_CODE_INVALID_ARGUMENTS, "InjectablesProviderController: the 'into' option resolved to null or undefined. " + "Ensure the value or resolver function returns a valid IocContext.");
-    }
-    this.bind(context);
-  };
-  InjectablesProviderController.prototype.hostDisconnected = function () {
-    if (!this.boundContext) {
-      return;
-    }
-    this.unbind(this.boundContext);
-  };
-  InjectablesProviderController.prototype.bind = function (context) {
-    if (this.boundContext) {
-      // Re-binding without unbinding first would leave stale entries; unbind the previous context.
-      this.unbind(this.boundContext);
-    }
-    this.boundContext = context;
-    // Seeds must be applied before binding so @Inject(SEEDS_TOKEN) resolves during activation.
-    if (this.seeds) {
-      core.applySeeds(context.container, this.seeds);
-    }
-    for (var _i = 0, _a = this.entries; _i < _a.length; _i++) {
-      var entry = _a[_i];
-      core.bindEntry(context.container, entry);
-    }
-    if (this.activate) {
-      for (var _b = 0, _c = this.activate; _b < _c.length; _b++) {
-        var token = _c[_b];
-        context.container.get(token);
-      }
-    }
-  };
-  InjectablesProviderController.prototype.unbind = function (context) {
-    for (var _i = 0, _a = this.entries; _i < _a.length; _i++) {
-      var entry = _a[_i];
-      var token = core.getEntryToken(entry);
-      if (context.container.isBound(token)) {
-        context.container.unbind(token);
-      }
-    }
-    if (this.seeds) {
-      core.unapplySeeds(context.container, this.seeds);
-    }
-    this.boundContext = null;
-  };
-  return InjectablesProviderController;
-}();
-
 /**
- * Decorator that binds a set of injectables to the nearest IoC container for the host element's lifetime.
+ * Decorator that provides a managed child container derived from the nearest
+ * parent container context.
  *
  * @remarks
- * Entries are bound when the host connects and unbound when it disconnects.
+ * The child container is created from the current parent context when the host
+ * connects, destroyed when it disconnects, and recreated when the parent
+ * container changes.
  *
  * @group Provision
  *
  * @param options - Provisioning options.
- * @returns An instance of {@link InjectablesProviderDecorator}.
+ * @param options.options - Child-container creation options.
+ * @returns An instance of {@link SubContainerProviderDecorator}.
  *
  * @example
  * ```typescript
  * class MyComponent extends LitElement {
- *   @injectablesProvide({ entries: [AuthService, UserService], activate: [AuthService] })
- *   public controller!: InjectablesProviderController<MyComponent>;
+ *   @subContainerProvide({
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *       activate: [AuthService],
+ *     },
+ *   })
+ *   public containerProvider!: SubContainerProvider<MyComponent>;
  * }
  * ```
  */
-function injectablesProvide(options) {
+function subContainerProvide(options) {
   return function (protoOrTarget, nameOrContext) {
     if (typeof nameOrContext === "object") {
       // Standard decorators:
       nameOrContext.addInitializer(function () {
-        protoOrTarget.set.call(this, new InjectablesProviderController(this, options));
+        protoOrTarget.set.call(this, new SubContainerProvider(this, options));
       });
     } else {
-      var controller_1;
+      var provider_1;
       protoOrTarget.constructor.addInitializer(function (element) {
-        controller_1 = new InjectablesProviderController(element, options);
+        provider_1 = new SubContainerProvider(element, options);
       });
       return {
         get: function () {
-          return controller_1;
+          return provider_1;
         },
         set: function () {},
         configurable: true,
@@ -826,67 +885,93 @@ function injectablesProvide(options) {
 }
 
 /**
- * Hook that binds injectables to the nearest IoC container for the host element's lifetime.
+ * Hook that provides a container to the host element and its children.
+ *
+ * @remarks
+ * Pass `container` to expose an external `Container` without taking
+ * ownership. Pass `options` to create a managed container during
+ * construction, activate configured entries on connect, destroy it on
+ * disconnect, and recreate it on reconnect.
  *
  * @group Provision
  *
  * @param host - The host element.
  * @param options - Provisioning options.
- * @returns An instance of {@link InjectablesProviderController}.
+ * @param options.container - External container instance to provide.
+ * @param options.options - Managed container creation options.
+ * @returns An instance of {@link ContainerProvider}.
  *
  * @example
  * ```typescript
- * class MyComponent extends LitElement {
- *   private services = useInjectablesProvider(this, {
- *     entries: [AuthService, UserService],
- *     activate: [AuthService],
+ * class MyRootElement extends LitElement {
+ *   private containerProvider: ContainerProvider = useContainerProvision(this, {
+ *     options: {
+ *       entries: [LoggerService],
+ *       activate: [LoggerService],
+ *     },
  *   });
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * class MyRootElement extends LitElement {
+ *   private containerProvider: ContainerProvider = useContainerProvision(this, { container: container });
+ * }
+ * ```
  */
-function useInjectablesProvider(host, options) {
-  return new InjectablesProviderController(host, options);
+function useContainerProvision(host, options) {
+  return new ContainerProvider(host, options);
 }
 
 /**
- * Hook that provides an IoC container to the host element and its children.
+ * Hook that provides a managed child container for the host element's lifetime.
+ *
+ * @remarks
+ * The child container is derived from the current parent
+ * {@link ContainerContext}, recreated when that parent context changes, and
+ * destroyed when the host disconnects.
  *
  * @group Provision
  *
  * @param host - The host element.
  * @param options - Provisioning options.
- * @returns An instance of {@link IocProviderController}.
+ * @param options.options - Child-container creation options.
+ * @returns An instance of {@link SubContainerProvider}.
  *
  * @example
  * ```typescript
- * class MyRootElement extends LitElement {
- *   private ioc = useIocProvision(this, { seed: { initialData: "..." } });
+ * class MyComponent extends LitElement {
+ *   private containerProvider: SubContainerProvider = useSubContainerProvider(this, {
+ *     options: {
+ *       entries: [AuthService, UserService],
+ *     },
+ *   });
  * }
  * ```
  */
-function useIocProvision(host, options) {
-  if (options === void 0) {
-    options = {};
-  }
-  return new IocProviderController(host, options);
+function useSubContainerProvider(host, options) {
+  return new SubContainerProvider(host, options);
 }
 
-exports.InjectablesProviderController = InjectablesProviderController;
-exports.IocContextObject = IocContextObject;
-exports.IocProviderController = IocProviderController;
+exports.ContainerContext = ContainerContext;
+exports.ContainerProvider = ContainerProvider;
 exports.OnCommandController = OnCommandController;
 exports.OnEventController = OnEventController;
 exports.OnQueryController = OnQueryController;
-exports.injectablesProvide = injectablesProvide;
+exports.SubContainerProvider = SubContainerProvider;
+exports.containerProvide = containerProvide;
 exports.injection = injection;
-exports.iocProvide = iocProvide;
 exports.onCommand = onCommand;
 exports.onEvent = onEvent;
 exports.onQuery = onQuery;
-exports.useInjectablesProvider = useInjectablesProvider;
+exports.subContainerProvide = subContainerProvide;
+exports.useContainer = useContainer;
+exports.useContainerProvision = useContainerProvision;
 exports.useInjection = useInjection;
-exports.useIocProvision = useIocProvision;
 exports.useOnCommand = useOnCommand;
 exports.useOnEvents = useOnEvents;
 exports.useOnQuery = useOnQuery;
+exports.useScope = useScope;
+exports.useSubContainerProvider = useSubContainerProvider;
 //# sourceMappingURL=index.js.map