Refine useProperties typing and docs

Co-authored-by: spearwolf <12805+spearwolf@users.noreply.github.com>

Author: Copilot

packages/shadow-objects/CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## unreleased
 
 - sharpen the `EntityApi` type definitions
+- improve `useProperties()` type inference with key-to-type maps
 - **Documentation:** Comprehensive update to the documentation structure and content.
     - Added dedicated documentation for Web Components (`<shae-worker>`, `<shae-ent>`, `<shae-prop>`) at `docs/03-api/04-web-components.md`.
     - Clarified the usage of Component Contexts, Namespacing (`ns` attribute), and decoupled placement of View Components.

packages/shadow-objects/docs/02-guides/02-creating-shadow-objects.md

@@ -9,13 +9,15 @@ The recommended way to define a Shadow Object is a simple function. This functio
 ```typescript
 import { ShadowObjectCreationAPI } from "@spearwolf/shadow-objects";
 
-export function UserProfileLogic({ 
-  useProperty, 
-  createEffect 
+export function UserProfileLogic({
+  useProperties,
+  createEffect,
 }: ShadowObjectCreationAPI) {
 
   // 1. Setup Phase: Define your reactive graph here
-  const userId = useProperty('userId');
+  const { userId } = useProperties<{userId: string}>({
+    userId: 'userId',
+  });
 
   createEffect(() => {
     // 2. Runtime Phase: This runs whenever userId changes

packages/shadow-objects/docs/03-api/01-shadow-object-api.md

@@ -39,12 +39,16 @@ createEffect(() => {
 
 A convenience helper to create multiple property signals at once.
 
-*   **Signature:** `useProperties(map: Record<string, any>): Record<string, () => any>`
+*   **Signature:** `useProperties<T>(map: { [K in keyof T]: string }): { [K in keyof T]: () => T[K] | undefined }`
 *   **Returns:** An object where keys match the input map, and values are signal readers.
 
 ```typescript
-const { x, y } = useProperties({ x: 0, y: 0 });
-// x() and y() are now signals
+const { foo, bar } = useProperties<{ foo: number; bar: string }>({
+  foo: 'prop.name.foo',
+  bar: 'prop.bar',
+});
+// foo(): number | undefined
+// bar(): string | undefined
 ```
 
 ---

packages/shadow-objects/docs/03-api/03-view-components.md

@@ -118,16 +118,15 @@ class GameEntity {
         });
 
         // Sync position to Shadow World
-        this.viewComponent.setProperties({
-            x: this.x,
-            y: this.y
-        });
+        this.viewComponent.setProperty('x', this.x);
+        this.viewComponent.setProperty('y', this.y);
     }
 
     update() {
         // Send updates every frame (or optimally, only on change)
         if (this.moved) {
-            this.viewComponent.setProperties({ x: this.x, y: this.y });
+            this.viewComponent.setProperty('x', this.x);
+            this.viewComponent.setProperty('y', this.y);
         }
     }
 

packages/shadow-objects/docs/04-patterns/best-practices.md

@@ -127,10 +127,10 @@ const myMeshResource = createResource(
 If you need multiple properties, avoid calling `useProperty` multiple times. Use `useProperties` to get a structured object of signals.
 
 ```typescript
-const { x, y, visible } = useProperties({
+const { x, y, visible } = useProperties<{ x: number; y: number; visible: boolean }>({
   x: "position-x",
   y: "position-y",
-  visible: "is-visible"
+  visible: "is-visible",
 });
 ```
 

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

@@ -338,6 +338,42 @@ describe('Kernel', () => {
 
         kernel.destroy();
       });
+
+      it('should support typed property maps', () => {
+        const registry = new Registry();
+        const kernel = new Kernel(registry);
+
+        let capturedProps:
+          | {
+              foo: SignalReader<number | undefined>;
+              bar: SignalReader<string | undefined>;
+            }
+          | undefined;
+
+        @ShadowObject({registry, token: 'testTypedUseProperties'})
+        class TestTypedUseProperties {
+          constructor({useProperties}: ShadowObjectCreationAPI) {
+            const props = useProperties<{foo: number; bar: string}>({
+              foo: 'propA',
+              bar: 'propB',
+            });
+            capturedProps = props;
+          }
+        }
+        expect(TestTypedUseProperties).toBeDefined();
+
+        const uuid = generateUUID();
+        kernel.createEntity(uuid, 'testTypedUseProperties', undefined, 0, [
+          ['propA', 123],
+          ['propB', 'valueB'],
+        ]);
+
+        expect(capturedProps).toBeDefined();
+        expect(value(capturedProps!.foo)).toBe(123);
+        expect(value(capturedProps!.bar)).toBe('valueB');
+
+        kernel.destroy();
+      });
     });
 
     describe('provideContext and useContext', () => {

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

@@ -360,12 +360,12 @@ export class Kernel {
     const contextProviders = new Map<string | symbol, Signal<any>>();
     const contextRootProviders = new Map<string | symbol, Signal<any>>();
 
-    const propertyReaders = new Map<string, SignalReader<any>>();
+    const propertyReaders = new Map<string, SignalReader<unknown>>();
 
-    const getUseProperty = <T = any>(
+    const getUseProperty = <T = unknown>(
       name: string,
       options?: SignalValueOptions<T> | CompareFunc<T | undefined>,
-    ): SignalReader<T> => {
+    ): SignalReader<Maybe<T>> => {
       if (!usePropertyOptionsDeprecatedShown && options != null && typeof options === 'function') {
         console.warn(
           '[shadow-objects] Deprecation Warning: The "isEqual" option of "useProperty()" is now passed as {compare} argument. Please update your code accordingly.',
@@ -375,11 +375,11 @@ export class Kernel {
 
       const opts = typeof options === 'function' ? {compare: options} : options;
 
-      let propReader = propertyReaders.get(name);
+      let propReader = propertyReaders.get(name) as SignalReader<Maybe<T>> | undefined;
 
       if (propReader === undefined) {
-        propReader = createSignal<any>(undefined, opts).get;
-        propertyReaders.set(name, propReader);
+        propReader = createSignal<Maybe<T>>(undefined, opts).get;
+        propertyReaders.set(name, propReader as SignalReader<unknown>);
         const con = link(entry.entity.getPropertyReader(name), propReader);
         unsubscribeSecondary.add(con.destroy.bind(con));
       }
@@ -523,8 +523,10 @@ export class Kernel {
 
         useProperty: getUseProperty,
 
-        useProperties<K extends string>(props: Record<K, string>): Record<K, SignalReader<any>> {
-          const result = {} as Record<K, SignalReader<any>>;
+        useProperties<T extends Record<string, unknown> = Record<string, unknown>>(
+          props: {[K in keyof T]: string},
+        ): {[K in keyof T]: SignalReader<Maybe<T[K]>>} {
+          const result = {} as {[K in keyof T]: SignalReader<Maybe<T[K]>>};
           for (const key in props) {
             if (Object.hasOwn(props, key)) {
               result[key] = getUseProperty(props[key]);

packages/shadow-objects/src/types.ts

@@ -132,7 +132,9 @@ export interface ShadowObjectCreationAPI {
 
   useProperty<T = unknown>(name: string, options?: SignalValueOptions<T> | CompareFunc<T | undefined>): SignalReader<Maybe<T>>;
 
-  useProperties<K extends string>(props: Record<K, string>): Record<K, SignalReader<any>>;
+  useProperties<T extends Record<string, unknown> = Record<string, unknown>>(
+    props: {[K in keyof T]: string},
+  ): {[K in keyof T]: SignalReader<Maybe<T[K]>>};
 
   createResource<T = unknown>(factory: () => T | undefined, cleanup?: (resource: NonNullable<T>) => unknown): Signal<Maybe<T>>;