` | `ish` (manager routing) |
**Scope perimeter:** Queries respect itemscope boundaries — `[itemprop="name"]` inside a nested `[itemscope]` won't be matched from the outer scope (donut-hole scoping).
**Pass `true` to infer all source keys:**
```TypeScript
infer: { byItemprop: true }
```
For full details, see [docs/inferred-assignments.md](docs/inferred-assignments.md).
## Bulk Enhancement with `enhance` and `enhanceAll`
Apply enhancements in bulk to matching elements using EMC (Element Mount Configuration) JSON files that enhancement packages already publish. No manual registration step needed — enhancements are auto-loaded and registered on demand.
```TypeScript
import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js';
await assignFromAsync(shadowRoot, { /* normal assignments */ }, {
from: vm,
enhance: [
{ emc: 'be-bound/emc.json', matching: '[name]' },
{ emc: 'be-observant/emc.json', matching: '[itemprop]' },
]
});
```
**How it works:**
1. Dynamically imports each EMC JSON file
2. Extracts the `enhConfig` (spawn path, enhKey)
3. Finds matching elements via `querySelectorAll` (using `matching` override, or the EMC's own selector)
4. Registers the enhancement in the element's `enhancementRegistry` if not already present
5. Spawns the enhancement on each matched element via `element.enh.get(registryItem)`
**Standalone usage (without `assignFrom`):**
```TypeScript
import { enhanceAll } from 'assign-gingerly/enhanceAll.js';
await enhanceAll(shadowRoot, [
{ emc: 'be-bound/emc.json', matching: '[name]' },
]);
```
**With `assignGingerly` (fire-and-forget):**
```TypeScript
assignGingerly(shadowRoot, {
'?.someProperty': 'value'
}, {
enhance: [{ emc: 'be-bound/emc.json', matching: '[name]' }]
});
// Enhancements apply asynchronously in the background
```
**Configuration:**
| Field | Type | Description |
|-------|------|-------------|
| `emc` | `string` | Path to EMC JSON file (dynamically imported) |
| `matching` | `string?` | CSS selector override (defaults to EMC's own selector) |
| `parse` | `boolean?` | Parse attributes via withAttrs (default: `false`, Phase II) |
**Notes:**
- No scope perimeter is applied — the selector does all filtering. For reactive observation of new elements, use [mount-observer](https://github.com/bahrus/mount-observer) instead.
- Requires JSON module import support (`import ... with { type: 'json' }`).
- Enhancement modules are loaded lazily — zero cost until `enhance` is used.
## Custom Assignment with `static assignTo` Protocol
As [introduced earlier](#example-3b---class-instances-are-normally-replaced), classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic. This section covers the full API, method signature, and advanced use cases.
```JavaScript
class ReactiveModel {
#data = {};
#listeners = [];
static assignTo(instance, rhs, parent, key) {
// Custom merge: trigger reactive notifications
for (const [k, v] of Object.entries(rhs)) {
instance.#data[k] = v;
instance.#listeners.forEach(fn => fn(k, v));
}
}
get(prop) { return this.#data[prop]; }
onChange(fn) { this.#listeners.push(fn); }
}
```
### How it works
When `assignGingerly` is about to assign a value to a property, it checks if the property's current value is an object whose constructor defines `static assignTo`. If so, it calls `assignTo` instead of the default behavior:
```JavaScript
const obj = { model: new ReactiveModel() };
assignGingerly(obj, { model: { name: 'Alice', age: 30 } });
// Instead of replacing or merging, calls:
// ReactiveModel.assignTo(obj.model, { name: 'Alice', age: 30 }, obj, 'model')
```
### Parameters
```TypeScript
class MyClass {
static assignTo(
instance: MyClass, // The current value (instance of this class)
rhs: any, // The value being assigned (from the RHS of assignGingerly)
parent: any, // The parent object containing the property
key: string|symbol // The property key being assigned to
) { ... }
}
```
The `parent` and `key` parameters allow `assignTo` to replace the instance entirely if needed (e.g., for immutable patterns):
```JavaScript
class ImmutableState {
#data;
constructor(data) { this.#data = Object.freeze({ ...data }); }
static assignTo(instance, rhs, parent, key) {
// Replace with a new immutable instance
parent[key] = new ImmutableState({ ...instance.#data, ...rhs });
}
}
```
### Use case: Iterable classes with private lists
A class that is iterable over a private list can use `assignTo` to handle array assignment (replacing the list) vs object assignment (merging properties):
```JavaScript
class TodoList {
#items = [];
*[Symbol.iterator]() { yield* this.#items; }
static assignTo(instance, rhs) {
if (Array.isArray(rhs)) {
// Replace the private list
instance.#items = [...rhs];
} else if (typeof rhs === 'object' && rhs !== null) {
// Merge properties normally
Object.assign(instance, rhs);
}
}
}
const app = { todos: new TodoList() };
// Assign an array — replaces the internal list
assignGingerly(app, { todos: ['Buy milk', 'Walk dog'] });
console.log([...app.todos]); // ['Buy milk', 'Walk dog']
// Assign an object — merges properties
assignGingerly(app, { todos: { title: 'My Todos' } });
console.log(app.todos.title); // 'My Todos'
console.log([...app.todos]); // ['Buy milk', 'Walk dog'] (list unchanged)
```
This pattern seems useful and reusable enough that this package provides a DX utility mixin to add this functionality to any class definition:
```JS
import {IterableMixin} from 'assign-gingerly/DX/IterableMixin.js';
class PlainList extends IterableMixin
()(class {}) {}
class MyIterableCustomElement extends IterableMixin()(HTMLElement) {}
class Combined extends OtherMixin()(IterableMixin()(HTMLElement)) {}
```
### Use case: Validation on assignment
```JavaScript
class TypedRecord {
static schema = { name: 'string', age: 'number' };
static assignTo(instance, rhs) {
for (const [k, v] of Object.entries(rhs)) {
const expected = TypedRecord.schema[k];
if (expected && typeof v !== expected) {
throw new TypeError(`${k} must be ${expected}, got ${typeof v}`);
}
instance[k] = v;
}
}
}
```
### Private field access
Because `assignTo` is a static method defined in the class body, it has full access to `#private` fields:
```JavaScript
class SecureStore {
#secrets = {};
static assignTo(instance, rhs) {
// Can read/write private fields
for (const [k, v] of Object.entries(rhs)) {
instance.#secrets[k] = encrypt(v);
}
}
}
```
### Safety
Only classes that explicitly define their own `assignTo` are affected. The check uses `Object.hasOwn(constructor, 'assignTo')` to prevent accidental inheritance — plain objects, arrays, and classes without `assignTo` use the default assignGingerly behavior.
## Property Forwarding with `installForwarding`
`installForwarding` installs getter/setter pairs on a class prototype that delegate to nested paths on the instance. This is useful for exposing deeply nested properties at the top level of an object — particularly for custom elements that delegate behavior to compositional feature classes.
```JavaScript
import { installForwarding } from 'assign-gingerly/DX/installForwarding.js';
```
### Basic usage
```JavaScript
class ClubMember extends HTMLElement {
static propLinks = {
'command': '?.behaviors?.commandBehavior?.command',
'commandForElement': '?.behaviors?.commandBehavior?.commandForElement'
};
}
installForwarding(ClubMember);
const el = document.createElement('club-member');
el.command = 'toggle';
// Equivalent to: assignGingerly(el, { '?.behaviors?.commandBehavior?.command': 'toggle' })
console.log(el.command);
// Equivalent to: resolveValue('?.behaviors?.commandBehavior?.command', el)
```
### How it works
1. Reads `static propLinks` from the constructor — a map of top-level property names to `?.`-delimited path strings.
2. For each entry, installs a getter/setter pair on the prototype:
- **Getter**: uses `resolveValue` to walk the path with optional chaining semantics. Returns `undefined` if any segment is nullish.
- **Setter**: uses `assignGingerly` to assign the value at the path, creating intermediate objects as needed.
3. Validates that forwarded property names don't already exist on the prototype (throws if they do).
### With methods and aliases
Because the getter uses `resolveValue` and the setter uses `assignGingerly`, you get full access to `withMethods` and `aka` via the options parameter:
```JavaScript
class MyComponent extends HTMLElement {
static propLinks = {
'username': '?.q?.#user-input?.value'
};
}
installForwarding(MyComponent, {
withMethods: ['querySelector'],
aka: { 'q': 'querySelector' }
});
// el.username now resolves:
// el.querySelector('#user-input').value
```
### Use with Custom Element Features
A common pattern is forwarding top-level properties to feature instances:
```JavaScript
class CustomButton extends HTMLElement {
static supportedFeatures = {
commandBehavior: { fallbackSpawn: CommandFeatureImpl }
};
static propLinks = {
'command': '?.commandBehavior?.command',
'commandForElement': '?.commandBehavior?.commandForElement'
};
}
customElements.assignFeatures(CustomButton, {
commandBehavior: { spawn: CommandFeatureImpl }
});
installForwarding(CustomButton);
// Now el.command delegates to el.commandBehavior.command
// The feature getter triggers lazy instantiation automatically
```
### Error conditions
| Condition | Error |
|-----------|-------|
| Property already exists on prototype | `"already exists on Constructor.prototype"` |
| Path doesn't start with `?.` | `"path must start with '?.'"` |
### Performance
- Paths are cached after first parse — repeated getter/setter calls don't re-split strings.
- The getter uses `resolveValue` (a lightweight single-path resolver with caching).
- The setter uses `assignGingerly` which also benefits from path caching.
## Itemscope Managers (Chrome 146+)
Itemscope Managers provide a way to manage DOM fragments and their associated data/view models for elements with the `itemscope` attribute. This feature enables frameworks and libraries to manage light children of web components, DOM fragments from looping constructs, and scenarios where custom element wrapping is not feasible.
> [!NOTE]
> This feature requires Chrome 146+ with scoped custom element registry support. It follows the same browser support requirements as the Enhancement Registry integration.
>
> For more information about scoped custom element registries, see [Chrome's announcement and guide](https://developer.chrome.com/blog/scoped-registries).
### Why Itemscope Managers?
The `itemscope` attribute (from the Microdata specification) provides a semantic way to mark elements that represent distinct data items. ItemScope Managers build on this by allowing us to:
- **Manage light children**: Attach behavior to light DOM children of web components without wrapping them in custom elements
- **Handle template loops**: Manage repeated DOM fragments generated by template systems
- **Avoid custom element overhead**: Enhance elements where custom element registration isn't appropriate or possible
- **Separate concerns**: Keep data/view model logic separate from the DOM structure
### Basic Usage
```html
```
```TypeScript
import 'assign-gingerly/object-extension.js';
// Define a manager class
class UserCardManager {
element;
name = '';
email = '';
constructor(element, initVals) {
this.element = element;
if (initVals) {
Object.assign(this, initVals);
this.render();
}
}
render() {
this.element.querySelector('[itemprop="name"]').textContent = this.name;
this.element.querySelector('[itemprop="email"]').textContent = this.email;
}
}
// Register the manager
customElements.itemscopeRegistry.define('user-card', {
manager: UserCardManager
});
// Use assignGingerly with the 'ish' property
const element = document.querySelector('[itemscope="user-card"]');
element.assignGingerly({
ish: {
name: 'Alice',
email: 'alice@example.com'
}
});
// Wait for async setup to complete
await customElements.itemscopeRegistry.whenDefined('user-card');
// Access the manager instance
console.log(element.ish instanceof UserCardManager); // true
console.log(element.ish.name); // 'Alice'
```
### The 'ish' Property
The `ish` property (short for "itemscope host") is the key to ItemScope Managers:
- **Special behavior for HTMLElements**: When you assign an `ish` property to an HTMLElement with an `itemscope` attribute, it triggers manager instantiation
- **Normal property for other objects**: For non-HTMLElement objects, `ish` is just a regular property with no special behavior
- **Asynchronous setup**: The manager is instantiated asynchronously, so use `whenDefined()` to wait for completion
```TypeScript
// HTMLElement with itemscope - special behavior
const div = document.createElement('div');
div.setAttribute('itemscope', 'my-manager');
div.assignGingerly({ ish: { prop: 'value' } });
// Manager will be instantiated asynchronously
// Plain object - normal property
const obj = {};
obj.assignGingerly({ ish: { prop: 'value' } });
console.log(obj.ish.prop); // 'value' - just a regular property
```
### ItemscopeRegistry
The `ItemscopeRegistry` class manages manager configurations and extends `EventTarget` to support lazy registration:
```TypeScript
// Access the global registry
const registry = customElements.itemscopeRegistry;
// Define a manager
registry.define('manager-name', {
manager: ManagerClass,
lifecycleKeys: {
dispose: 'cleanup',
resolved: 'isReady'
}
});
// Get a manager configuration
const config = registry.get('manager-name');
// Wait for a manager to be defined and all setups to complete
await registry.whenDefined('manager-name');
```
**Methods:**
- `define(name, config)` - Register a manager configuration
- Throws `Error: Already registered` if name already exists
- Dispatches an event with the manager name when successful
- `get(name)` - Retrieve a manager configuration
- Returns the configuration or `undefined` if not found
- `whenDefined(name)` - Wait for manager definition and setup completion
- Returns a Promise that resolves when:
1. The manager is defined (waits for definition if not yet registered)
2. All pending `ish` property setups for this manager are complete
- This is the recommended way to wait for async manager instantiation
### Manager Configuration
Manager configurations follow this interface:
```TypeScript
interface ItemscopeManagerConfig {
manager: {
new (element: HTMLElement, initVals?: Partial): T;
};
lifecycleKeys?: {
dispose?: string | symbol;
resolved?: string | symbol;
};
}
```
**Properties:**
- `manager` (required): Constructor function that receives:
- `element`: The HTMLElement with the itemscope attribute
- `initVals`: Merged values from all queued `ish` assignments
- `lifecycleKeys` (optional): Lifecycle method names
- `dispose`: Method to call when cleaning up
- `resolved`: Property/event name for async initialization
### Lazy Registration
Managers can be registered after elements are already using them. The system queues values and instantiates the manager when it's registered:
```TypeScript
const element = document.createElement('div');
element.setAttribute('itemscope', 'lazy-manager');
// Assign before manager is registered - values are queued
element.assignGingerly({ ish: { prop1: 'value1' } });
element.assignGingerly({ ish: { prop2: 'value2' } });
// Register the manager later
setTimeout(() => {
customElements.itemscopeRegistry.define('lazy-manager', {
manager: class LazyManager {
constructor(element, initVals) {
this.element = element;
Object.assign(this, initVals);
// initVals contains both prop1 and prop2
}
}
});
}, 100);
// Wait for registration and setup
await customElements.itemscopeRegistry.whenDefined('lazy-manager');
console.log(element.ish.prop1); // 'value1'
console.log(element.ish.prop2); // 'value2'
```
### Instance Caching
Manager instances are cached per element. Subsequent `ish` assignments merge values into the existing instance:
```TypeScript
const element = document.createElement('div');
element.setAttribute('itemscope', 'my-manager');
// First assignment - creates instance
element.assignGingerly({ ish: { prop1: 'value1' } });
await customElements.itemscopeRegistry.whenDefined('my-manager');
const firstInstance = element.ish;
// Second assignment - reuses instance
element.assignGingerly({ ish: { prop2: 'value2' } });
await customElements.itemscopeRegistry.whenDefined('my-manager');
console.log(element.ish === firstInstance); // true - same instance
console.log(element.ish.prop1); // 'value1'
console.log(element.ish.prop2); // 'value2'
```
### Validation and Error Handling
The system validates `ish` property assignments and throws descriptive errors:
```TypeScript
// Error: Element must have itemscope attribute
const div1 = document.createElement('div');
div1.assignGingerly({ ish: { prop: 'value' } });
// Throws asynchronously
// Error: itemscope must be non-empty string
const div2 = document.createElement('div');
div2.setAttribute('itemscope', '');
div2.assignGingerly({ ish: { prop: 'value' } });
// Throws asynchronously
// Error: ish value must be an object
const div3 = document.createElement('div');
div3.setAttribute('itemscope', 'my-manager');
div3.assignGingerly({ ish: 'string' });
// Throws asynchronously
```
**Note**: Errors are thrown asynchronously since the `ish` property setup happens in the background. They will appear in the console but won't be catchable with try/catch around the `assignGingerly` call.
### Scoped Registries
ItemScope Managers integrate with scoped custom element registries. Each element can have its own registry:
```TypeScript
// Create a scoped registry
const scopedRegistry = new CustomElementRegistry();
// Define a manager in the scoped registry
scopedRegistry.itemscopeRegistry.define('scoped-manager', {
manager: ScopedManager
});
// Attach the registry to an element
const element = document.createElement('div');
element.customElementRegistry = scopedRegistry;
element.setAttribute('itemscope', 'scoped-manager');
// The element uses its scoped registry
element.assignGingerly({ ish: { prop: 'value' } });
await scopedRegistry.itemscopeRegistry.whenDefined('scoped-manager');
```
If an element doesn't have a `customElementRegistry` property, it falls back to the global `customElements.itemscopeRegistry`.
### Complete Example
```html
Todo List
```
### Testing with whenDefined
When writing tests for code that uses ItemScope Managers, use `whenDefined()` to wait for async setup:
```TypeScript
// Test example
test('should initialize manager with values', async () => {
const element = document.createElement('div');
element.setAttribute('itemscope', 'test-manager');
// Register manager
customElements.itemscopeRegistry.define('test-manager', {
manager: class TestManager {
constructor(element, initVals) {
this.element = element;
Object.assign(this, initVals);
}
}
});
// Assign values
element.assignGingerly({ ish: { prop: 'value' } });
// Wait for setup to complete
await customElements.itemscopeRegistry.whenDefined('test-manager');
// Now we can assert
expect(element.ish.prop).toBe('value');
expect(element.ish.element).toBe(element);
});
```
### Design Rationale
ItemScope Managers follow these design principles:
1. **Synchronous API**: `assignGingerly` remains synchronous and returns immediately
2. **Async setup**: Manager instantiation happens asynchronously in the background
3. **Explicit waiting**: Use `whenDefined()` when you need to wait for setup completion
4. **Dual behavior**: The `ish` property has special meaning only for HTMLElements with `itemscope` attributes
5. **Registry-based**: Follows the same pattern as `EnhancementRegistry` for consistency
6. **Event-driven**: Uses EventTarget for lazy registration support
This design ensures backward compatibility while providing powerful new capabilities for managing DOM fragments.
## Custom Element Features
Custom Element Features provide dependency injection for custom elements (and other objects). A custom element author declares which feature "slots" their class supports, and consumers inject implementations into those slots. Features are lazily instantiated on first property access.
To use features, import the module directly — it is independent of `object-extension.js`:
```JavaScript
import 'assign-gingerly/assignFeatures.js';
```
This self-installs `featuresRegistry` and `assignFeatures()` on `CustomElementRegistry.prototype`. It does not require or pull in the enhancement/itemscope registries.
This is useful for:
- **Decomposing large components** into smaller, testable units (e.g., a photo-taking feature, a badge-making feature).
- **Mocking in tests** — swap real implementations for test doubles without subclassing.
- **Reusing behaviors** across different custom elements without mixins.
- **Lazy loading** — feature code isn't executed until the property is actually accessed.
### How it works
1. The custom element declares `static supportedFeatures` — an opt-in map of feature keys and their configuration.
2. A consumer calls `customElements.assignFeatures(Constructor, injections)` to register implementations.
3. Lazy getter-only properties are installed on the constructor's prototype.
4. On first access, the getter spawns the feature instance, validates it (optionally), caches it, and returns it.
5. Because the property is getter-only (no setter), `assignGingerly` automatically merges into the spawned instance when assigning object values to that property.
### Features at Registration Time
Features can also be bundled directly into enhancement and itemscope manager registration configs — no separate `assignFeatures` call needed:
```TypeScript
// Enhancement with features
enhancementRegistry.push({
spawn: MyEnhancement,
enhKey: 'myEnh',
features: {
photoTaker: { spawn: PhotoTakerImpl },
badgeMaker: { spawn: BadgeMakerImpl },
}
});
// Itemscope manager with features
customElements.itemscopeRegistry.define('my-manager', {
manager: MyManagerClass,
lifecycleKeys: { dispose: 'cleanup', resolved: 'isReady' },
features: {
roundabout: { customData: { /* ... */ } },
}
});
```
This calls `assignFeatures` automatically under the hood using the shared `customElements.featuresRegistry`. The standalone `assignFeatures` call remains available for cases where you need to associate features with a class you don't own or after initial registration.
### Basic example
```JavaScript
import 'assign-gingerly/assignFeatures.js';
// 1. Define a feature implementation
class PhotoTakerImpl {
constructor(hostElement) {
this.host = hostElement;
}
takePicture() {
return `📸 taken by ${this.host.localName}`;
}
someProp = 'default';
}
// 2. Define the custom element with supported feature slots
class ClubMember extends HTMLElement {
static supportedFeatures = {
photoTaker: {
// Used if no spawn is provided in assignFeatures
fallbackSpawn: PhotoTakerImpl,
// Optional runtime check on the spawned instance
validateShape(instance) {
return typeof instance.takePicture === 'function';
}
}
}
}
// 3. Inject features before define (getters must be on prototype before instances exist)
customElements.assignFeatures(ClubMember, {
photoTaker: {
spawn: PhotoTakerImpl
}
});
customElements.define('club-member', ClubMember);
// 4. Use it — lazy instantiation on first access
const el = document.createElement('club-member');
console.log(el.photoTaker.takePicture()); // '📸 taken by club-member'
// 5. assignGingerly merges into the feature instance automatically
el.assignGingerly({
photoTaker: { someProp: 'hello' }
});
console.log(el.photoTaker.someProp); // 'hello'
```
### Using fallbackSpawn (no explicit injection needed)
If `fallbackSpawn` is provided in `supportedFeatures`, you can call `assignFeatures` with an empty spawn — or even just `{}` — and the fallback will be used:
```JavaScript
class ClubMember extends HTMLElement {
static supportedFeatures = {
photoTaker: {
fallbackSpawn: PhotoTakerImpl
}
}
}
customElements.assignFeatures(ClubMember, {
photoTaker: {}
});
customElements.define('club-member', ClubMember);
const el = document.createElement('club-member');
console.log(el.photoTaker.takePicture()); // works via fallbackSpawn
```
### Testing with mocks
```JavaScript
class PhotoTakerMock {
constructor(hostElement) {
this.host = hostElement;
this.calls = [];
}
takePicture() {
this.calls.push('takePicture');
return 'mock click';
}
}
// In test setup:
customElements.assignFeatures(ClubMember, {
photoTaker: { spawn: PhotoTakerMock }
});
const el = document.createElement('club-member');
el.photoTaker.takePicture();
console.log(el.photoTaker.calls); // ['takePicture']
```
### Multiple features
```JavaScript
class BadgeMakerImpl {
constructor(hostElement) {
this.host = hostElement;
}
makeBadge(name) {
return `🎫 ${name}`;
}
}
class ClubMember extends HTMLElement {
static supportedFeatures = {
photoTaker: { fallbackSpawn: PhotoTakerImpl },
badgeMaker: { fallbackSpawn: BadgeMakerImpl }
}
}
// Can assign all at once
customElements.assignFeatures(ClubMember, {
photoTaker: { spawn: PhotoTakerImpl },
badgeMaker: { spawn: BadgeMakerImpl }
});
customElements.define('club-member', ClubMember);
// Or incrementally (different keys each call)
// customElements.assignFeatures(ClubMember, { photoTaker: { spawn: PhotoTakerImpl } });
// customElements.assignFeatures(ClubMember, { badgeMaker: { spawn: BadgeMakerImpl } });
```
### Validation
The `validateShape` callback runs after instantiation. If it returns `false`, an error is thrown:
```JavaScript
class ClubMember extends HTMLElement {
static supportedFeatures = {
photoTaker: {
fallbackSpawn: PhotoTakerImpl,
validateShape(instance) {
if (typeof instance.takePicture !== 'function') return false;
if (typeof instance.someProp !== 'string') return false;
return true;
}
}
}
}
```
### Error conditions
`assignFeatures` throws in these cases:
| Condition | Error |
|-----------|-------|
| Constructor has no `static supportedFeatures` | `"does not define static supportedFeatures"` |
| Key not declared in `supportedFeatures` | `"is not declared in Constructor.supportedFeatures"` |
| Property already exists on prototype | `"already exists on Constructor.prototype"` |
| Same key assigned twice for same constructor | `"has already been assigned for Constructor"` |
| No `spawn` provided and no `fallbackSpawn` | `"no spawn implementation found"` (at access time) |
| `validateShape` returns false | `"failed shape validation"` (at access time) |
### Integration with assignGingerly
Because `assignFeatures` installs **getter-only** properties (no setter), assignGingerly's existing readonly property detection kicks in automatically:
```JavaScript
// assignGingerly detects photoTaker is getter-only
// → reads the getter (spawning the instance if needed)
// → recursively merges the RHS object into the instance
el.assignGingerly({
photoTaker: { someProp: 'updated' }
});
```
This means no special handling is needed in assignGingerly for features — it "just works."
### Scoped registry support
The lazy getter uses `(this.customElementRegistry || customElements)` to resolve the features registry. This means:
- On Chrome 146+ (and future browsers with scoped registries), the element's scoped `customElementRegistry` is used.
- On older browsers, it falls back to the global `customElements`.
### Not limited to custom elements
While designed with custom elements in mind, `assignFeatures` works with any constructor whose instances will have a `customElementRegistry` property (or where the global `customElements` fallback is acceptable). This includes element enhancement classes that set `this.customElementRegistry` from the element they enhance.
### API reference
```TypeScript
// On CustomElementRegistry.prototype:
customElements.assignFeatures(
ctr: Function, // The class constructor
features: FeatureConfigsMap // Map of feature keys to FeatureConfig
): Promise | undefined;
// FeatureConfig — passed to assignFeatures for each feature key:
interface FeatureConfig {
// Synchronous constructor, async function returning one, or import-path string
spawn?:
| { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
| (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>)
| string; // import path or builtIns.* alias
// Attribute patterns for parsing element attributes into initVals
withAttrs?: AttrPatterns;
// Pass-through field for custom configuration (accessible via ctx.injection.customData)
customData?: any;
}
// SupportedFeatureConfig — declared on the class via static supportedFeatures:
interface SupportedFeatureConfig {
fallbackSpawn?: /* same type as FeatureConfig.spawn */;
validateShape?: (instance: any) => boolean;
getSharedContext?: (instance: any) => any;
}
// Context passed to feature constructors:
interface FeatureSpawnContext {
key: string; // The feature key (e.g., 'photoTaker')
optIn: SupportedFeatureConfig; // The config from static supportedFeatures
injection: FeatureConfig; // The config from assignFeatures()
featuresRegistry: FeaturesRegistry; // The registry reference
shared?: any; // From getSharedContext (if defined)
}
```
### Constructor signature
Feature classes receive three arguments:
```JavaScript
class MyFeature {
constructor(hostElement, ctx, initVals) {
// hostElement: the element instance that owns this feature
// ctx: { key, optIn, injection, featuresRegistry, shared }
// initVals: any pre-set value captured before the feature was spawned (or undefined)
if (initVals) {
Object.assign(this, initVals);
}
// Access shared context (e.g., ElementInternals)
if (ctx.shared) {
this.internals = ctx.shared.internals;
}
// Access custom data from the FeatureConfig
if (ctx.injection.customData) {
this.config = ctx.injection.customData;
}
}
}
```
### Pre-upgrade property capture with `captureFeatureInitVals`
When a custom element exists in the DOM before `customElements.define()` is called, properties may be set on it directly (e.g., by a framework or server-rendered HTML hydration). After the element upgrades, these own-properties shadow the prototype getters installed by `assignFeatures`, preventing the lazy spawn mechanism from working.
`captureFeatureInitVals` solves this by capturing and deleting those own-properties in the constructor, storing them so the getter can pass them as `initVals` when the feature is first accessed.
**Usage:**
```JavaScript
import { captureFeatureInitVals } from 'assign-gingerly/assignFeatures.js';
class ClubMember extends HTMLElement {
static supportedFeatures = {
photoTaker: { fallbackSpawn: PhotoTakerImpl }
}
constructor() {
super();
captureFeatureInitVals(this);
}
}
```
**What it does:**
1. Iterates over the keys in `static supportedFeatures`.
2. For each key, checks if the instance has an own-property with that name (`Object.hasOwn`).
3. If found: captures the value, deletes the own-property, and stores the value internally so the getter can retrieve it as `initVals` when the feature is first accessed.
**When to use it:**
- Always include it in the constructor if your element might exist in the DOM before `define()` is called (which is common with server-rendered HTML or lazy-loaded component definitions).
- It's safe to call even when no own-properties exist — it simply does nothing.
- It's a one-liner with no performance cost when there are no pre-set properties.
**The full pre-upgrade flow:**
```JavaScript
// 1. Element exists in DOM before define (unknown element)
const el = document.createElement('club-member');
document.body.appendChild(el);
// 2. Framework or hydration sets properties
el.photoTaker = { someProp: 'hello', count: 42 };
// 3. Later, the component definition loads
customElements.assignFeatures(ClubMember, {
photoTaker: { spawn: PhotoTakerImpl }
});
customElements.define('club-member', ClubMember);
// → constructor runs, captureFeatureInitVals captures el.photoTaker value
// 4. First access spawns with initVals
console.log(el.photoTaker.someProp); // 'hello'
console.log(el.photoTaker.count); // 42
```
**Important ordering:** Call `assignFeatures` before `customElements.define()`. The getters must be on the prototype before any instances are created or upgraded.
### Async spawn (lazy-loading features)
Feature implementations can be loaded asynchronously by providing an async function or an import-path string as `spawn`. The spawn is resolved before the feature getter is installed, so `assignFeatures` returns a Promise when any configured spawn is async:
```JavaScript
customElements.assignFeatures(ClubMember, {
photoTaker: {
spawn: () => import('./photo-taker.js').then(m => m.PhotoTakerImpl)
}
});
// Or use an import path string:
customElements.assignFeatures(ClubMember, {
photoTaker: {
spawn: './photo-taker.js'
}
});
```
Because the real class is resolved before the getter is installed, the first access returns the actual instance rather than a placeholder. If an async spawn fails, the `assignFeatures` Promise rejects with the original error.
### Attribute parsing with `withAttrs`
Features can declare attribute patterns that are parsed from the host element into `initVals`. Unlike enhancements, feature attributes are always read unprefixed. Programmatic `initVals` take precedence over parsed values.
See [docs/withAttrs.md](docs/withAttrs.md#attribute-patterns-for-custom-element-features) for the full guide and examples.
### Shared context with `getSharedContext`
Features often need access to private data from the host element (e.g., `ElementInternals`). The `getSharedContext` callback on `supportedFeatures` provides this:
```JavaScript
class MyButton extends HTMLElement {
#internals;
#privateState = { clickCount: 0 };
static supportedFeatures = {
commandBehavior: {
fallbackSpawn: CommandFeatureImpl,
getSharedContext(instance) {
// This callback is in the class scope — it can access #private fields
return {
internals: instance.#internals,
state: instance.#privateState
};
}
}
}
constructor() {
super();
this.#internals = this.attachInternals();
}
}
class CommandFeatureImpl {
constructor(host, ctx, initVals) {
// ctx.shared contains what getSharedContext returned
this.internals = ctx.shared.internals;
this.state = ctx.shared.state;
}
}
```
**Key points:**
- `getSharedContext` is called at spawn time (both sync and async paths).
- It's per-feature — different features can receive different slices of private state.
- It's opt-in — if not defined, `ctx.shared` is `undefined`.
- Because it's defined in the class body, it has access to `#private` fields of instances of that class.
### Custom data
The `customData` field on `FeatureConfig` is a pass-through for arbitrary configuration:
```JavaScript
customElements.assignFeatures(ClubMember, {
photoTaker: {
spawn: PhotoTakerImpl,
customData: {
maxResolution: '8k',
allowedFormats: ['png', 'jpg', 'webp']
}
}
});
class PhotoTakerImpl {
constructor(host, ctx, initVals) {
// Access custom data
const { maxResolution, allowedFormats } = ctx.injection.customData;
}
}
```
### `withAsyncMethods` in assignGingerly
assignGingerly supports async method calls in path expressions via the `withAsyncMethods` option. When a path segment matches a name in `withAsyncMethods`, the method is called and its return value is awaited before continuing the chain.
```JavaScript
import assignGingerly from 'assign-gingerly/assignGingerly.js';
class ViewModel {
async fetchValue() {
await someAsyncWork();
return this;
}
}
assignGingerly(el, {
'?.fetchValue?.someProp': 'hello'
}, { withAsyncMethods: ['fetchValue'] });
// Equivalent to: (await el.fetchValue()).someProp = 'hello'
```
**How it works:**
- `assignGingerly` remains synchronous — async paths are **fire-and-forget**.
- When a path segment matches a name in `withAsyncMethods`, the method is called and its return value is awaited before continuing the chain.
- The async path evaluator (`evaluatePathWithAsyncMethods`) is dynamically imported only when needed, so there's no cost to the synchronous path.
- `withAsyncMethods` works together with `withMethods` — you can mix sync and async methods in the same path.
```JavaScript
assignGingerly(el, {
'?.fetchValue?.classList?.add': 'active'
}, {
withAsyncMethods: ['fetchValue'],
withMethods: ['add']
});
// (await el.fetchValue()).classList.add('active')
```
**Note:** Interaction with `@each` and `@eachTime` is not yet supported for async methods.
### Nested features with `PropertyBag`
`PropertyBag` is a base class for creating nested feature containers. It groups related features under a single namespace property, enabling hierarchical composition:
```JavaScript
import { PropertyBag, assignFeatures } from 'assign-gingerly/assignFeatures.js';
import { installForwarding } from 'assign-gingerly/DX/installForwarding.js';
// 1. Define a feature container by subclassing PropertyBag
class ClubMemberBehaviors extends PropertyBag {
static supportedFeatures = {
commandBehavior: { fallbackSpawn: CommandFeatureImpl },
ariaBehavior: { fallbackSpawn: AriaFeatureImpl }
}
}
// 2. Define the custom element with the container as a feature
class ClubMember extends HTMLElement {
static supportedFeatures = {
behaviors: { fallbackSpawn: ClubMemberBehaviors }
}
// Forward nested properties to the top level
static propLinks = {
'command': '?.behaviors?.commandBehavior?.command',
'commandForElement': '?.behaviors?.commandBehavior?.commandForElement'
}
}
// 3. Register features at both levels
customElements.assignFeatures(ClubMember, {
behaviors: { spawn: ClubMemberBehaviors }
});
customElements.assignFeatures(ClubMemberBehaviors, {
commandBehavior: { spawn: CommandFeatureImpl },
ariaBehavior: { spawn: AriaFeatureImpl }
});
installForwarding(ClubMember);
customElements.define('club-member', ClubMember);
// 4. Use it
const el = document.createElement('club-member');
el.command = 'toggle'; // forwards to el.behaviors.commandBehavior.command
el.behaviors.ariaBehavior.setRole('button'); // access nested features directly
```
**How `PropertyBag` works:**
- Carries `customElementRegistry` from the host element so nested features can resolve their registries.
- Applies `initVals` via `Object.assign` (supports pre-upgrade property capture).
- Must be subclassed — direct instantiation throws an error.
- Subclasses must define `static supportedFeatures` (enforced by `assignFeatures` validation).
**Why subclass instead of using `PropertyBag` directly?**
Each subclass declares its own `static supportedFeatures`, which:
- Provides opt-in safety (only declared feature keys are allowed).
- Enables TypeScript type checking on the feature slots.
- Documents the expected shape of the container.
```JavaScript
// This throws — PropertyBag has no supportedFeatures
customElements.assignFeatures(PropertyBag, { anything: {} }); // Error!
// This works — subclass declares what's allowed
class MyBehaviors extends PropertyBag {
static supportedFeatures = { anything: { fallbackSpawn: AnythingImpl } }
}
customElements.assignFeatures(MyBehaviors, { anything: { spawn: AnythingImpl } }); // ✓
```
### Lifecycle callback forwarding with `callbackForwarding`
Features can receive custom element lifecycle callbacks by declaring `callbackForwarding` in their config. This can be specified by the feature author (in `static supportedFeatures`) and/or by the consumer (in `assignFeatures`). Both are merged — the author declares what the feature intrinsically needs, the consumer can add more:
```JavaScript
// Author declares what the feature needs
class MyElement extends HTMLElement {
static supportedFeatures = {
reflector: {
fallbackSpawn: Reflector,
callbackForwarding: ['connectedCallback', 'disconnectedCallback']
}
}
}
// Consumer can add more (but not remove author's)
customElements.assignFeatures(MyElement, {
reflector: {
spawn: Reflector,
callbackForwarding: ['adoptedCallback'] // merged with author's
}
});
```
When the custom element's `connectedCallback` fires, the feature's `connectedCallback` is called automatically. This eliminates boilerplate forwarding code and handles feature activation timing naturally.
**How it works:**
1. `assignFeatures` patches the custom element's lifecycle callback on the prototype (once per callback type).
2. The original callback runs first, then all registered features are forwarded.
3. On first `connectedCallback`, the getter is triggered — spawning the feature lazily at the correct lifecycle moment (when the element is in the DOM and computed styles are available).
4. For async features, forwarding is skipped until the real instance is available.
**Supported callbacks:**
| Callback | Use case |
|----------|----------|
| `connectedCallback` | Feature needs DOM context (computed styles, layout, etc.) |
| `disconnectedCallback` | Feature needs cleanup (remove listeners, abort fetches) |
| `attributeChangedCallback` | Feature reacts to attribute changes (limited to element's `observedAttributes`) |
| `adoptedCallback` | Feature reacts to document adoption |
| `formDisabledCallback` | Feature reacts to disabled state changes (form-associated elements) |
| `formResetCallback` | Feature reacts to form reset (form-associated elements) |
| `formStateRestoreCallback` | Feature restores state after navigation/session restore (form-associated elements) |
**Example: Feature that reads computed styles on connect**
```JavaScript
class Reflector {
constructor(host, ctx) {
this.host = host;
this.internals = ctx.shared.internals;
}
connectedCallback() {
// Safe to call getComputedStyle here — element is in the DOM
const styles = getComputedStyle(this.host);
const exports = styles.getPropertyValue('--custom-state-exports');
// ... process exports
}
disconnectedCallback() {
// Cleanup
}
}
class MyElement extends HTMLElement {
#internals;
static supportedFeatures = {
reflector: {
fallbackSpawn: Reflector,
getSharedContext(instance) {
return { internals: instance.#internals };
}
}
}
constructor() {
super();
this.#internals = this.attachInternals();
}
}
customElements.assignFeatures(MyElement, {
reflector: {
spawn: Reflector,
callbackForwarding: ['connectedCallback', 'disconnectedCallback']
}
});
customElements.define('my-element', MyElement);
```
No manual getter access or `connectedCallback` boilerplate needed — the feature activates at the right time automatically.
**Multiple features with callbacks:**
```JavaScript
customElements.assignFeatures(MyElement, {
reflector: {
spawn: Reflector,
callbackForwarding: ['connectedCallback']
},
logger: {
spawn: Logger,
callbackForwarding: ['connectedCallback', 'disconnectedCallback']
}
});
// Both features receive connectedCallback; only logger receives disconnectedCallback
```
**Note on `attributeChangedCallback`:** The feature only receives callbacks for attributes listed in the element's `static observedAttributes`. Features cannot add to this list after `define()` is called.
### Class-level setup with `static onAssigned`
Some features need one-time class-level setup before any instances are created — for example, installing prototype getter/setters or pre-loading modules. The `static onAssigned` method on the spawn class is called by `assignFeatures` immediately after registration:
```JavaScript
class RoundaboutFeature {
// Called once when assignFeatures processes this feature
static async onAssigned(ctr, featureConfig) {
// One-time class-level setup: install prototype getter/setters, pre-load modules
await makeRoundaboutReady(ctr, featureConfig.customData);
}
constructor(host, ctx, initVals) {
// Instance-level setup (runs on first getter access)
const [vm, propagator] = roundaboutSync({
vm: host,
...ctx.injection.customData,
});
this._vm = vm;
this._propagator = propagator;
}
}
```
**Usage:**
```JavaScript
// await is safe — returns undefined if no async onAssigned hooks exist
await customElements.assignFeatures(MyElement, {
roundabout: {
spawn: RoundaboutFeature,
customData: raConfig
}
});
// Now define — class is fully set up, connectedCallback will be synchronous
customElements.define('my-element', MyElement);
```
**How it works:**
- `assignFeatures` checks if the spawn class defines `static onAssigned` (via `Object.hasOwn`).
- If found, calls `SpawnClass.onAssigned(ctr, featureConfig, key)` after installing the getter.
- If `onAssigned` returns a Promise, it is **awaited sequentially** before processing the next feature. This guarantees that features declared earlier complete their setup before later features run.
- This sequential ordering enables inter-feature communication: Feature A can post configuration (via `suggestFeatureInfo`) that Feature B reads in its own `onAssigned`.
- If no features have `onAssigned`, `assignFeatures` runs synchronously and returns `undefined` (backward compatible).
- Only applies to synchronous spawners (the class must be available at registration time). Async spawners can't define `onAssigned` since the class isn't loaded yet.
**Sequential ordering guarantee:**
```JavaScript
await customElements.assignFeatures(MyElement, {
featureA: { spawn: FeatureA }, // FeatureA.onAssigned runs first, completes
featureB: { spawn: FeatureB } // FeatureB.onAssigned runs second, can read A's output
});
```
Features are processed in declaration order. If Feature A's `onAssigned` is async, it fully completes before Feature B's `onAssigned` starts. This makes it safe for features to communicate via `suggestFeatureInfo` / `getFeatureInfoSuggestions`.
For full documentation on inter-feature communication, see [docs/inter-feature-communication.md](docs/inter-feature-communication.md).
**`await` is always safe:**
```JavaScript
// These are equivalent for sync features (no onAssigned or sync onAssigned):
customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature } });
await customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature } });
// Both work — await on undefined is a no-op
```
### Declarative element definition with `defineWithFeatures`
`defineWithFeatures` enables defining custom elements from JSON-serializable configuration — no class authoring needed for derived elements:
```JavaScript
import { defineWithFeatures } from 'assign-gingerly/defineWithFeatures.js';
await defineWithFeatures('time-ticker', 'el-maker', {
assignFeatures: {
roundabout: {
customData: { template: myTemplate },
withAttrs: { base: 'ra', mode: '${base}-mode' },
callbackForwarding: ['connectedCallback']
},
truthSourcer: {
callbackForwarding: ['connectedCallback', 'attributeChangedCallback']
}
}
});
```
It resolves async `fallbackSpawn` implementations from the base class, creates a subclass, wires up features, and defines the element. Designed for use with [mount-observer cede scripts](https://github.com/bahrus/mount-observer#custom-element-definition-cede-scripts) but works standalone.
For full documentation, see [docs/defineWithFeatures.md](docs/defineWithFeatures.md).
### Resolving async spawns with `resolveAndAssignFeatures`
When defining a custom element via a traditional JS module (rather than declaratively via cede scripts), `resolveAndAssignFeatures` handles the boilerplate of resolving async `fallbackSpawn` implementations before calling `assignFeatures`:
```JavaScript
import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
export async function wireFeatures(ElementClass, cfg) {
const { roundabout } = cfg.features;
const { customData, withAttrs } = roundabout;
await resolveAndAssignFeatures(ElementClass, {
timeTicker: { spawn: TimeTicker }, // explicit spawn — used as-is
faceUp: { // no spawn — resolved from fallbackSpawn
callbackForwarding: ['connectedCallback', 'disconnectedCallback']
},
roundabout: { // no spawn — resolved from fallbackSpawn
customData,
withAttrs,
callbackForwarding: ['connectedCallback']
}
});
}
```
**What it does:**
For each feature in the config that doesn't have an explicit `spawn`, it resolves the async `fallbackSpawn` from the class's `static supportedFeatures`, sets it as the spawn, then calls `assignFeatures`. Features with an explicit `spawn` are left untouched.
**When to use it:**
- Defining custom elements via JS modules (the traditional `import` + `define` pattern)
- When the base class uses async `fallbackSpawn` for lazy loading but you want synchronous feature access after registration
- As a reusable `wireFeatures` function that multiple element definitions can share
See [time-ticker/wireFeatures.js](https://github.com/bahrus/time-ticker/blob/baseline/wireFeatures.js) for a real-world example.
Catalog of Published Custom Element Features
| Package | Description | Source |
|---------|-------------|--------|
| [truth-sourcer](https://www.npmjs.com/package/truth-sourcer) | Attribute/property binding and truth-sourcing for custom elements | [GitHub](https://github.com/bahrus/truth-sourcer) |
| [be-reflective](https://www.npmjs.com/package/be-reflective) | CSS custom state reflection from computed styles | [GitHub](https://github.com/bahrus/be-reflective) |
| [face-up](https://www.npmjs.com/package/face-up) | Form Associated Custom Element behavior via ElementInternals | [GitHub](https://github.com/bahrus/face-up) |
| [roundabout](https://www.npmjs.com/package/roundabout) | Reactive view-model binding with template rendering and computed property orchestration | [GitHub](https://github.com/bahrus/roundabout#using-roundaboutfeature-with-assignfeatures) |
| [time-ticker](https://www.npmjs.com/package/time-ticker) | Web component that fires events periodically (example of a feature-based component with no code in the class) | [GitHub](https://github.com/bahrus/time-ticker) |
| [templ-maker](https://www.npmjs.com/package/templ-maker) | Extracts a DOM fragment into a reusable template and clones it per instance (works with cede scripts) | [GitHub](https://github.com/bahrus/templ-maker) |
### Roadmap (future phases)
- **Nested features**: Support `?.path?.notation` keys directly in `assignFeatures` (without requiring `PropertyBag`).
- **`@each` + async interaction**: Combine async methods with iteration.
## Viewing Locally
Any web server that serves static files with server-side includes will do but...
1. Install git
2. Fork/clone this repo
3. Install node.js
4. Open command window to folder where you cloned this repo
5. > git submodule add https://github.com/bahrus/types.git types
6. > git submodule add https://github.com/bahrus/inferencer.git inferencer
7. > git submodule update --init --recursive
8. > npm install
9. > npm run serve
10. Open http://localhost:8000/demo/ in a modern browser
---
_Source: https://npm.io/package/assign-gingerly · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
## Introduction
This package starts out innocently enough -- it provides the ability to carefully merge one object into another. This is a primitive sorely lacking in the web, and this package is a polyfill for what we (me with a lot of help from AI) would like to see built into the platform. We make no apologies about adding these features directly to the underlying API's, as it is part of a proposal which is sitting there gathering dust, with no apparent alternatives under consideration. In particular the reference:
```JavaScript
import 'assign-gingerly/object-extension.js';
```
has the "side effect" of enhancing the platform API in a way that this proposal can only hope the platform chooses to adopt in the future (or some variation).
One can achieve the same functionality with a little more work, and "playing nicer" with the platform by importing assign-gingerly.js, assign-tentatively.js, and/or assignFrom.js, which has no such side effects.
For `assignFrom` method chaining on objects, separate extension modules are available — import only what you need:
```JavaScript
import 'assign-gingerly/assignFrom-extension.js'; // adds obj.assignFrom() — sync
import 'assign-gingerly/assignFromAsync-extension.js'; // adds obj.assignFromAsync() — async
```
This enables fluent patterns like:
```JavaScript
oElement
.assignFrom({ '?.textContent': '?.greeting' }, { from: vm1 })
.assignFrom({ '?.style Y=': { width: '?.w' } }, { from: vm2 });
```
## Object Extension Pattern
Not only does this polyfill package allow merging data properties onto objects that are expecting them, this polyfill also provides the ability to merge *augmented behavior* onto run-time objects without sub classing all such objects of the same type. This includes the ability to spawn an instance of a class and "merge" it into the API of the original object in an elegant way that is easy to wrap one's brain around, without ever blocking access to the original object or breaking it.
So we are providing a form of the ["Decorator Pattern"](https://en.wikipedia.org/wiki/Decorator_pattern) or perhaps more accurately the [Extension Object Pattern](https://swiftorial.com/swiftlessons/design-patterns/structural-patterns/extension-object-pattern) as tailored for the quirks of the web.
## Custom Registries
On top of that, this polyfill package builds on the newly minted Custom Element Registry, adding additional sub-registries:
1. [enhancementRegistry](#enhancement-registry-addendum-to-the-custom-element-registry) object on top of the customElementRegistry object associated with all elements, to be able to lazy load object extensions on demand while avoiding namespace conflicts, and, importantly, as a basis for defining custom attributes associated with the enhancements.
2. [itemscopeRegistry for Itemscope Managers](#itemscoperegistry) to automatically associate a function prototype or class instance with the itemscope attribute of an HTMLElement.
3. [featuresRegistry for Custom Element Features](#custom-element-features) to support dependency injection of composable feature classes or function prototypes onto custom element prototypes via lazy getters.
So in our view this package helps fill the void left by not supporting the "is" attribute for built-in elements (but is not a complete solution, just a critical building block). Mount-observer and custom enhancements builds on top of the critical role that assign-gingerly plays.
Anyway, let's start out detailing the more innocent features of this package / polyfill.
Because the same declarative input can come from sources that aren't fully trusted — HTML attributes, user JSON, remote config — the package also provides an **opt-in permission layer** to block or redirect dangerous property assignments. See [docs/assign-permissions.md](docs/assign-permissions.md) for how to construct and pass a `PermissionProcessor`.
The three utility functions are:
## assignGingerly
assignGingerly builds on Object.assign. Like Object.assign, the object getting assigned can often be a JSON stringified object. Some of the unusual syntax we see with assignGingerly is there to continue to support JSON deserialized objects as a viable argument to be passed.
assign-gingerly adds support for:
1. Carefully merging in nested properties.
2. Dependency injection based on a mapping protocol.
The second fundamental utility function is:
## assignTentatively
assignTentatively provides a far more limited subset of functionality compared to assignGingerly. The tradeoff is that assignTentatively can do something important assignGingerly cannot do -- be "reversed". This can be quite useful for some scenarios. Think of how css "turns on" visual effects while conditions are met, then reverts to how things were before the conditions were met when the conditions are no longer met, as if nothing happened. Another example is allowing user edits to be rolled back as they repeatedly hit "ctrl+z".
The third fundamental utility function is:
## assignFrom (and assignFromAsync)
`assignFrom` builds on assignGingerly by adding a resolution step: RHS values that are `?.`-prefixed path strings are resolved against a source object before assignment. This enables a declarative, data-driven pattern where a view model (or any source) feeds values into a target through path expressions — replacing imperative property lookups with a single configuration object.
**`assignFrom` is synchronous** — it resolves paths, expands substitutions, handles spreads, processes `#[x]` refs, and runs inferred assignments all without yielding to the event loop. Handler commands (` =>`), `beVigilant`, and `enhance` are fire-and-forget (kicked off asynchronously in the background).
**`assignFromAsync`** is the awaitable variant for when you need to:
- Use async protocol handlers (e.g., `fetch`-based resolution — protocols are introduced just below, and covered in full in [Protocol Resolution](#protocol-resolution-in-getvalues-and-assignfrom) later in this doc)
- `await` handler completion before proceeding
- Wait for `enhance` (EMC JSON imports) to finish
```TypeScript
import { assignFrom } from 'assign-gingerly/assignFrom.js'; // sync (default)
import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js'; // async when needed
```
For most use cases — including `manageTemplateList`, reactive merge cycles, and DOM binding — the sync `assignFrom` is the right choice. It delivers near-vanilla-JS performance by avoiding microtask overhead.
assignFrom adds support for:
1. Resolving RHS path strings against a source object (`from`).
2. Target-relative root references via `$0` so paths can resolve from the first argument passed to `assignFrom`/`assignFromAsync` (the target object) instead of the `from` object.
3. Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols) — don't worry if this is unfamiliar yet, it's explained in full in [Protocol Resolution in `getValues` and `assignFrom`](#protocol-resolution-in-getvalues-and-assignfrom) later in this doc.
4. Handler plugins via the ` =>` operator for custom logic (fire-and-forget in sync mode, awaitable in async mode).
5. Looped substitution with `where_x_in` / `where_y_in` / `where_z_in` for expanding template patterns into multiple concrete assignments.
6. Dynamic substitutions via the `substitutions` option for injecting runtime string values into path segments. See [docs/substitutions.md](docs/substitutions.md).
7. Spread merging via the `"..."` key.
8. Boolean coercion / negation of a resolved value via a leading `!` marker: `'!!?.isOpen'` resolves `?.isOpen` then coerces to a real boolean, `'!?.isOpen'` negates it (`!!!` negates, and so on). Only honored in front of a `?.` path, `$0` reference, or protocol — a plain literal like `'!important'` is left untouched. Nullish coerces to `false`, which makes `!!` the safe way to feed an optional source value into a boolean sink (`hidden`, `disabled`, `classList.toggle`'s force argument, …).
9. Multiple invocations of one `withMethods` method via the ` =*` operator — see [docs/multi-invoke.md](docs/multi-invoke.md).
Example:
```TypeScript
const target = { value: 'target-value' };
const source = { value: 'from-value' };
assignFrom(target, {
resolved: '$0?.value'
}, { from: source });
console.log(target.resolved); // 'target-value'
```
All of assignGingerly's features (nested paths, `withMethods`, `aka`, `@each`, `@eachTime`, registry, etc.) are inherited.
## Example 1 - assignGingerly as a "superset" of Object.assign:
```TypeScript
const sourceObj = {hello: 'world'};
sourceObj.assignGingerly({hello: 'Venus', foo: 'bar'});
// Because none of the keys of the second parameter start with "?.",
// nor includes any symbols keys,
// assign gingerly produces identical results
// as Object.assign, and is synchronous:
console.log(sourceObj);
//{hello: 'Venus', foo: 'bar'}
```
## Example 2 Merging into an existing sub object
```html
```
```TypeScript
const oInput = document.querySelector('#myInput');
oInput.assignGingerly({'?.style?.height': '15px'});
console.log(oInput.style.height);
// 15px
```
This can go many levels deep.
## Example 3 Deeply nested
```TypeScript
const obj = {};
assignGingerly(obj, {
'?.style?.height': '15px',
'?.a?.b?.c': {
d: 'hello',
e: 'world'
}
});
console.log(obj);
// {
// a: {b: c: {d: 'hello', e: 'world'}},
// style: {height: '15px'}
// }
```
When the right hand side of an expression is an object, assignGingerly behavior depends on the context:
- For **nested paths** (starting with `?.`): recursively merges into nested objects, creating them if needed
- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly, an accessor, or the current value's class defines [`static assignTo`](#custom-assignment-with-static-assignto-protocol) (see Examples 3a, 3b, and the assignTo section below)
Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package.
## Example 3-plain - Plain Key Object Assignment
For plain keys (without `?.` prefix), assignGingerly performs simple assignment, just like `Object.assign`:
```TypeScript
const obj = {};
const template = document.createElement('template');
template.innerHTML = '