Skip to content

Commit a20ddfa

Browse files
Copilotspearwolf
Copilot
and
spearwolf
committed
refactor: rename ShadowObjectParams to ShadowObjectCreationAPI
Co-authored-by: spearwolf <12805+spearwolf@users.noreply.github.com>
1 parent d8b8dd5 commit a20ddfa

5 files changed

Lines changed: 54 additions & 53 deletions

File tree

‎packages/shadow-objects/CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10-
- renamed `useResource()` to `createResource()` in `ShadowObjectParams` interface
10+
- renamed interface `ShadowObjectParams` to `ShadowObjectCreationAPI` for clarity and consistency with the concept of the _Shadow Object Creation API_
11+
- renamed `useResource()` to `createResource()` in `ShadowObjectCreationAPI` interface
1112

1213
## [0.23.0] - 2025-11-26
1314

‎packages/shadow-objects/README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,20 +37,20 @@ The **Registry** maps **Tokens** to **Shadow Object Constructors**.
3737

3838
### 1. Defining Shadow Objects
3939

40-
You can define a Shadow Object as a **Function** or a **Class**. Both receive a `ShadowObjectParams` object containing the API methods.
40+
You can define a Shadow Object as a **Function** or a **Class**. Both receive a `ShadowObjectCreationAPI` object containing the API methods.
4141

4242
#### Function-based (Recommended)
4343

4444
```typescript
45-
import { ShadowObjectParams } from "@spearwolf/shadow-objects";
45+
import { ShadowObjectCreationAPI } from "@spearwolf/shadow-objects";
4646

4747
export function MyShadowObject({
4848
useProperty,
4949
useContext,
5050
createEffect,
5151
on,
5252
onDestroy
53-
}: ShadowObjectParams) {
53+
}: ShadowObjectCreationAPI) {
5454

5555
// 1. Read Properties
5656
const title = useProperty("title");
@@ -75,10 +75,10 @@ export function MyShadowObject({
7575
#### Class-based
7676

7777
```typescript
78-
import { ShadowObjectParams } from "@spearwolf/shadow-objects";
78+
import { ShadowObjectCreationAPI } from "@spearwolf/shadow-objects";
7979

8080
export class MyShadowObject {
81-
constructor({ useProperty, createEffect, onDestroy }: ShadowObjectParams) {
81+
constructor({ useProperty, createEffect, onDestroy }: ShadowObjectCreationAPI) {
8282
const title = useProperty("title");
8383

8484
createEffect(() => {
@@ -94,9 +94,9 @@ export class MyShadowObject {
9494
}
9595
```
9696

97-
### 2. The `ShadowObjectParams` API
97+
### 2. The Shadow Object Creation API
9898

99-
The `ShadowObjectParams` object provides all necessary tools to interact with the Entity, the View, and the Context system.
99+
The `ShadowObjectCreationAPI` object provides all necessary tools to interact with the Entity, the View, and the Context system.
100100

101101
| Method | Description |
102102
| :--- | :--- |

‎packages/shadow-objects/src/in-the-dark/Kernel.spec.ts‎

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import {emit, on} from '@spearwolf/eventize';
22
import {createSignal, type Signal, type SignalReader, value} from '@spearwolf/signalize';
33
import {afterEach, describe, expect, it, vi} from 'vitest';
44
import {MessageToView} from '../constants.js';
5-
import type {ShadowObjectParams} from '../types.js';
5+
import type {ShadowObjectCreationAPI} from '../types.js';
66
import {generateUUID} from '../utils/generateUUID.js';
77
import {onCreate, onDestroy} from './events.js';
88
import {Kernel, type MessageToViewEvent} from './Kernel.js';
@@ -246,17 +246,17 @@ describe('Kernel', () => {
246246
});
247247
});
248248

249-
describe('ShadowObjectParams API', () => {
249+
describe('Shadow Object Creation API', () => {
250250
describe('useProperty', () => {
251251
it('should return a signal reader for entity property', () => {
252252
const registry = new Registry();
253253
const kernel = new Kernel(registry);
254254

255-
let capturedPropertyReader: ReturnType<ShadowObjectParams['useProperty']> | undefined;
255+
let capturedPropertyReader: ReturnType<ShadowObjectCreationAPI['useProperty']> | undefined;
256256

257257
@ShadowObject({registry, token: 'testUseProperty'})
258258
class TestUseProperty {
259-
constructor({useProperty}: ShadowObjectParams) {
259+
constructor({useProperty}: ShadowObjectCreationAPI) {
260260
capturedPropertyReader = useProperty('testProp');
261261
}
262262
}
@@ -278,12 +278,12 @@ describe('Kernel', () => {
278278
const registry = new Registry();
279279
const kernel = new Kernel(registry);
280280

281-
let reader1: ReturnType<ShadowObjectParams['useProperty']> | undefined;
282-
let reader2: ReturnType<ShadowObjectParams['useProperty']> | undefined;
281+
let reader1: ReturnType<ShadowObjectCreationAPI['useProperty']> | undefined;
282+
let reader2: ReturnType<ShadowObjectCreationAPI['useProperty']> | undefined;
283283

284284
@ShadowObject({registry, token: 'testUsePropertyCache'})
285285
class TestUsePropertyCache {
286-
constructor({useProperty}: ShadowObjectParams) {
286+
constructor({useProperty}: ShadowObjectCreationAPI) {
287287
reader1 = useProperty('testProp');
288288
reader2 = useProperty('testProp');
289289
}
@@ -304,11 +304,11 @@ describe('Kernel', () => {
304304
const registry = new Registry();
305305
const kernel = new Kernel(registry);
306306

307-
let capturedProps: Record<string, ReturnType<ShadowObjectParams['useProperty']>> | undefined;
307+
let capturedProps: Record<string, ReturnType<ShadowObjectCreationAPI['useProperty']>> | undefined;
308308

309309
@ShadowObject({registry, token: 'testUseProperties'})
310310
class TestUseProperties {
311-
constructor({useProperties}: ShadowObjectParams) {
311+
constructor({useProperties}: ShadowObjectCreationAPI) {
312312
capturedProps = useProperties({foo: 'propA', bar: 'propB'});
313313
}
314314
}
@@ -334,19 +334,19 @@ describe('Kernel', () => {
334334
const kernel = new Kernel(registry);
335335

336336
const contextName = Symbol('testContext');
337-
let capturedContext: ReturnType<ShadowObjectParams['useContext']> | undefined;
337+
let capturedContext: ReturnType<ShadowObjectCreationAPI['useContext']> | undefined;
338338

339339
@ShadowObject({registry, token: 'parentProvider'})
340340
class ParentProvider {
341-
constructor({provideContext}: ShadowObjectParams) {
341+
constructor({provideContext}: ShadowObjectCreationAPI) {
342342
provideContext(contextName, 'contextValue');
343343
}
344344
}
345345
expect(ParentProvider).toBeDefined();
346346

347347
@ShadowObject({registry, token: 'childConsumer'})
348348
class ChildConsumer {
349-
constructor({useContext}: ShadowObjectParams) {
349+
constructor({useContext}: ShadowObjectCreationAPI) {
350350
capturedContext = useContext(contextName);
351351
}
352352
}
@@ -373,19 +373,19 @@ describe('Kernel', () => {
373373

374374
const contextName = 'signalContext';
375375
const sourceSignal = createSignal('initial');
376-
let capturedContext: ReturnType<ShadowObjectParams['useContext']> | undefined;
376+
let capturedContext: ReturnType<ShadowObjectCreationAPI['useContext']> | undefined;
377377

378378
@ShadowObject({registry, token: 'signalProvider'})
379379
class SignalProvider {
380-
constructor({provideContext}: ShadowObjectParams) {
380+
constructor({provideContext}: ShadowObjectCreationAPI) {
381381
provideContext(contextName, sourceSignal.get);
382382
}
383383
}
384384
expect(SignalProvider).toBeDefined();
385385

386386
@ShadowObject({registry, token: 'signalConsumer'})
387387
class SignalConsumer {
388-
constructor({useContext}: ShadowObjectParams) {
388+
constructor({useContext}: ShadowObjectCreationAPI) {
389389
capturedContext = useContext(contextName);
390390
}
391391
}
@@ -411,12 +411,12 @@ describe('Kernel', () => {
411411
const registry = new Registry();
412412
const kernel = new Kernel(registry);
413413

414-
let ctx1: ReturnType<ShadowObjectParams['useContext']> | undefined;
415-
let ctx2: ReturnType<ShadowObjectParams['useContext']> | undefined;
414+
let ctx1: ReturnType<ShadowObjectCreationAPI['useContext']> | undefined;
415+
let ctx2: ReturnType<ShadowObjectCreationAPI['useContext']> | undefined;
416416

417417
@ShadowObject({registry, token: 'testContextCache'})
418418
class TestContextCache {
419-
constructor({useContext}: ShadowObjectParams) {
419+
constructor({useContext}: ShadowObjectCreationAPI) {
420420
ctx1 = useContext('myContext');
421421
ctx2 = useContext('myContext');
422422
}
@@ -438,19 +438,19 @@ describe('Kernel', () => {
438438
const kernel = new Kernel(registry);
439439

440440
const contextName = 'parentOnlyContext';
441-
let capturedParentContext: ReturnType<ShadowObjectParams['useParentContext']> | undefined;
441+
let capturedParentContext: ReturnType<ShadowObjectCreationAPI['useParentContext']> | undefined;
442442

443443
@ShadowObject({registry, token: 'parentCtxProvider'})
444444
class ParentCtxProvider {
445-
constructor({provideContext}: ShadowObjectParams) {
445+
constructor({provideContext}: ShadowObjectCreationAPI) {
446446
provideContext(contextName, 'parentValue');
447447
}
448448
}
449449
expect(ParentCtxProvider).toBeDefined();
450450

451451
@ShadowObject({registry, token: 'childCtxConsumer'})
452452
class ChildCtxConsumer {
453-
constructor({useParentContext}: ShadowObjectParams) {
453+
constructor({useParentContext}: ShadowObjectCreationAPI) {
454454
capturedParentContext = useParentContext(contextName);
455455
}
456456
}
@@ -475,19 +475,19 @@ describe('Kernel', () => {
475475
const kernel = new Kernel(registry);
476476

477477
const globalCtxName = 'globalContext';
478-
let capturedGlobalCtx: ReturnType<ShadowObjectParams['useContext']> | undefined;
478+
let capturedGlobalCtx: ReturnType<ShadowObjectCreationAPI['useContext']> | undefined;
479479

480480
@ShadowObject({registry, token: 'globalProvider'})
481481
class GlobalProvider {
482-
constructor({provideGlobalContext}: ShadowObjectParams) {
482+
constructor({provideGlobalContext}: ShadowObjectCreationAPI) {
483483
provideGlobalContext(globalCtxName, 'globalValue');
484484
}
485485
}
486486
expect(GlobalProvider).toBeDefined();
487487

488488
@ShadowObject({registry, token: 'globalConsumer'})
489489
class GlobalConsumer {
490-
constructor({useContext}: ShadowObjectParams) {
490+
constructor({useContext}: ShadowObjectCreationAPI) {
491491
capturedGlobalCtx = useContext(globalCtxName);
492492
}
493493
}
@@ -512,19 +512,19 @@ describe('Kernel', () => {
512512

513513
const globalCtxName = 'globalSignalContext';
514514
const sourceSignal = createSignal('globalInitial');
515-
let capturedGlobalCtx: ReturnType<ShadowObjectParams['useContext']> | undefined;
515+
let capturedGlobalCtx: ReturnType<ShadowObjectCreationAPI['useContext']> | undefined;
516516

517517
@ShadowObject({registry, token: 'globalSignalProvider'})
518518
class GlobalSignalProvider {
519-
constructor({provideGlobalContext}: ShadowObjectParams) {
519+
constructor({provideGlobalContext}: ShadowObjectCreationAPI) {
520520
provideGlobalContext(globalCtxName, sourceSignal.get);
521521
}
522522
}
523523
expect(GlobalSignalProvider).toBeDefined();
524524

525525
@ShadowObject({registry, token: 'globalSignalConsumer'})
526526
class GlobalSignalConsumer {
527-
constructor({useContext}: ShadowObjectParams) {
527+
constructor({useContext}: ShadowObjectCreationAPI) {
528528
capturedGlobalCtx = useContext(globalCtxName);
529529
}
530530
}
@@ -559,7 +559,7 @@ describe('Kernel', () => {
559559

560560
@ShadowObject({registry, token: 'testResource'})
561561
class TestResource {
562-
constructor({createResource}: ShadowObjectParams) {
562+
constructor({createResource}: ShadowObjectCreationAPI) {
563563
resourceSignal = createResource(createFn, cleanupFn);
564564
}
565565
}
@@ -587,7 +587,7 @@ describe('Kernel', () => {
587587

588588
@ShadowObject({registry, token: 'testUndefinedResource'})
589589
class TestUndefinedResource {
590-
constructor({createResource}: ShadowObjectParams) {
590+
constructor({createResource}: ShadowObjectCreationAPI) {
591591
createResource(createFn, cleanupFn);
592592
}
593593
}
@@ -611,7 +611,7 @@ describe('Kernel', () => {
611611

612612
@ShadowObject({registry, token: 'testEffect'})
613613
class TestEffect {
614-
constructor({createEffect}: ShadowObjectParams) {
614+
constructor({createEffect}: ShadowObjectCreationAPI) {
615615
createEffect(() => {
616616
effectFn(testSignal.get());
617617
});
@@ -639,7 +639,7 @@ describe('Kernel', () => {
639639

640640
@ShadowObject({registry, token: 'testEffectDestroy'})
641641
class TestEffectDestroy {
642-
constructor({createEffect}: ShadowObjectParams) {
642+
constructor({createEffect}: ShadowObjectCreationAPI) {
643643
createEffect(() => {
644644
effectFn(testSignal.get());
645645
});
@@ -669,7 +669,7 @@ describe('Kernel', () => {
669669

670670
@ShadowObject({registry, token: 'testCreateSignal'})
671671
class TestCreateSignal {
672-
constructor({createSignal: cs}: ShadowObjectParams) {
672+
constructor({createSignal: cs}: ShadowObjectCreationAPI) {
673673
createdSignal = cs<string>('initial');
674674
}
675675
}
@@ -695,7 +695,7 @@ describe('Kernel', () => {
695695

696696
@ShadowObject({registry, token: 'testSignalDestroy'})
697697
class TestSignalDestroy {
698-
constructor({createSignal: cs}: ShadowObjectParams) {
698+
constructor({createSignal: cs}: ShadowObjectCreationAPI) {
699699
createdSignal = cs<string>('test');
700700
}
701701
}
@@ -724,7 +724,7 @@ describe('Kernel', () => {
724724

725725
@ShadowObject({registry, token: 'testMemo'})
726726
class TestMemo {
727-
constructor({createMemo}: ShadowObjectParams) {
727+
constructor({createMemo}: ShadowObjectCreationAPI) {
728728
memoReader = createMemo<number>(() => sourceSignal.get() * 2);
729729
}
730730
}
@@ -753,7 +753,7 @@ describe('Kernel', () => {
753753

754754
@ShadowObject({registry, token: 'testOn'})
755755
class TestOn {
756-
constructor({on: subscribe}: ShadowObjectParams) {
756+
constructor({on: subscribe}: ShadowObjectCreationAPI) {
757757
subscribe(emitter, 'testEvent', eventHandler);
758758
}
759759
}
@@ -783,7 +783,7 @@ describe('Kernel', () => {
783783

784784
@ShadowObject({registry, token: 'testOnce'})
785785
class TestOnce {
786-
constructor({once: subscribeOnce}: ShadowObjectParams) {
786+
constructor({once: subscribeOnce}: ShadowObjectCreationAPI) {
787787
subscribeOnce(emitter, 'singleEvent', eventHandler);
788788
}
789789
}
@@ -812,7 +812,7 @@ describe('Kernel', () => {
812812

813813
@ShadowObject({registry, token: 'testOnceNoFire'})
814814
class TestOnceNoFire {
815-
constructor({once: subscribeOnce}: ShadowObjectParams) {
815+
constructor({once: subscribeOnce}: ShadowObjectCreationAPI) {
816816
subscribeOnce(emitter, 'neverFiredEvent', eventHandler);
817817
}
818818
}
@@ -837,7 +837,7 @@ describe('Kernel', () => {
837837

838838
@ShadowObject({registry, token: 'testOnDestroy'})
839839
class TestOnDestroy {
840-
constructor({onDestroy: registerDestroy}: ShadowObjectParams) {
840+
constructor({onDestroy: registerDestroy}: ShadowObjectCreationAPI) {
841841
registerDestroy(destroyCallback);
842842
}
843843
}
@@ -861,7 +861,7 @@ describe('Kernel', () => {
861861

862862
@ShadowObject({registry, token: 'testMultipleOnDestroy'})
863863
class TestMultipleOnDestroy {
864-
constructor({onDestroy: registerDestroy}: ShadowObjectParams) {
864+
constructor({onDestroy: registerDestroy}: ShadowObjectCreationAPI) {
865865
registerDestroy(() => callOrder.push(1));
866866
registerDestroy(() => callOrder.push(2));
867867
registerDestroy(() => callOrder.push(3));

‎packages/shadow-objects/src/types.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ export type EntityApi = Pick<
9393
traverse(callback: (entity: EntityApi) => any): void;
9494
};
9595

96-
export interface ShadowObjectParams {
96+
export interface ShadowObjectCreationAPI {
9797
entity: EntityApi;
9898

9999
provideContext<T = unknown>(
@@ -125,12 +125,12 @@ export interface ShadowObjectParams {
125125
}
126126

127127
export interface ShadowObjectConstructor {
128-
new (params: ShadowObjectParams): {};
128+
new (params: ShadowObjectCreationAPI): {};
129129
displayName?: string;
130130
}
131131

132132
export interface ShadowObjectConstructorFunc {
133-
(params: ShadowObjectParams): object | undefined | void;
133+
(params: ShadowObjectCreationAPI): object | undefined | void;
134134
displayName?: string;
135135
}
136136

0 commit comments

Comments
 (0)