@flighthq/entity 0.5.1-next.693.478551c → 0.5.1-next.729.2aeb707

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/entity`. The `@fligh
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/entity@0.5.1-next.693.478551c](https://github.com/flighthq/flight/tree/478551cf7887f05c42c11f75e59034c715c8495f/packages/entity)
-- [License](https://github.com/flighthq/flight/blob/478551cf7887f05c42c11f75e59034c715c8495f/LICENSE.md)
+- [Source for @flighthq/entity@0.5.1-next.729.2aeb707](https://github.com/flighthq/flight/tree/2aeb707259007d61c5aaf2e31fe47447a260fe2a/packages/entity)
+- [License](https://github.com/flighthq/flight/blob/2aeb707259007d61c5aaf2e31fe47447a260fe2a/LICENSE.md)

package/dist/binding.d.ts

@@ -1,4 +1,7 @@
 import type { Entity } from '@flighthq/types/contract';
 export declare function attachEntityBinding(entity: Entity, binding: object): void;
-export declare function getEntityBinding(source: Entity): object | null;
+export declare function detachEntityBinding(entity: Entity): void;
+export declare function getEntityBinding(source: Readonly<Entity>): object | null;
+export declare function getEntityBindingAs<Type>(source: Readonly<Entity>): Type | null;
+export declare function hasEntityBinding(source: Readonly<Entity>): boolean;
 //# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAKvD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKzE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAKvD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKzE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGxD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAExE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAE9E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAElE"}

package/dist/binding.js

@@ -1,13 +1,23 @@
 import { EntityRuntimeKey } from '@flighthq/types/contract';
-import { createEntityRuntime, getEntityRuntime } from './runtime';
+import { createEntityRuntime } from './runtime';
 export function attachEntityBinding(entity, binding) {
     if (entity[EntityRuntimeKey] === undefined) {
         entity[EntityRuntimeKey] = createEntityRuntime();
     }
     entity[EntityRuntimeKey].binding = binding;
 }
+export function detachEntityBinding(entity) {
+    const runtime = entity[EntityRuntimeKey];
+    if (runtime !== undefined)
+        runtime.binding = null;
+}
 export function getEntityBinding(source) {
-    const runtime = getEntityRuntime(source);
-    return runtime?.binding ?? null;
+    return source[EntityRuntimeKey]?.binding ?? null;
+}
+export function getEntityBindingAs(source) {
+    return getEntityBinding(source);
+}
+export function hasEntityBinding(source) {
+    return getEntityBinding(source) !== null;
 }
 //# sourceMappingURL=binding.js.map

package/dist/binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElE,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAAe;IACjE,IAAI,MAAM,CAAC,gBAAgB,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,gBAAgB,CAAC,GAAG,mBAAmB,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,CAAC,gBAAgB,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;AAClC,CAAC"}
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAAe;IACjE,IAAI,MAAM,CAAC,gBAAgB,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,gBAAgB,CAAC,GAAG,mBAAmB,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,CAAC,gBAAgB,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACzC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,OAAO,MAAM,CAAC,gBAAgB,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAO,MAAwB;IAC/D,OAAO,gBAAgB,CAAC,MAAM,CAAgB,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,OAAO,gBAAgB,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;AAC3C,CAAC"}

package/dist/guards.js

@@ -4,7 +4,7 @@ export function areEntityRuntimeGuardsEnabled() {
     return _guardsEnabled;
 }
 // Creates a guarded entity that warns when the runtime slot is written directly rather
-// than through ensureEntityRuntime or attachEntityBinding. Only active when guards are
+// than through a public helper such as attachEntityBinding. Only active when guards are
 // enabled via enableEntityRuntimeGuards.
 export function createGuardedEntity(entity) {
     if (!_guardsEnabled || typeof Proxy === 'undefined')
@@ -13,9 +13,9 @@ export function createGuardedEntity(entity) {
         set(target, prop, value) {
             if (prop === EntityRuntimeKey && _guardsEnabled) {
                 // The write is reported and then ALLOWED: the stack cannot be inspected reliably across
-                // environments, so trusted callers (ensureEntityRuntime, attachEntityBinding) cannot be told apart
-                // from a raw poke. Reporting goes through the seam rather than the console so it uses the standard
-                // sink — see enableEntityRuntimeGuards.
+                // environments, so trusted callers such as attachEntityBinding cannot be told apart from a raw
+                // poke. Reporting goes through the seam rather than the console so it uses the standard sink — see
+                // enableEntityRuntimeGuards.
                 _writeGuard?.('runtime-slot');
             }
             target[prop] = value;

package/dist/guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,yFAAyF;AACzF,MAAM,UAAU,6BAA6B;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,uFAAuF;AACvF,uFAAuF;AACvF,yCAAyC;AACzC,MAAM,UAAU,mBAAmB,CAAsB,MAAqB;IAC5E,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACnE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACvB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,gBAAgB,IAAI,cAAc,EAAE,CAAC;gBAChD,wFAAwF;gBACxF,mGAAmG;gBACnG,mGAAmG;gBACnG,wCAAwC;gBACxC,WAAW,EAAE,CAAC,cAAc,CAAC,CAAC;YAChC,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,0FAA0F;AAC1F,2FAA2F;AAC3F,eAAe;AACf,MAAM,UAAU,0BAA0B,CAAC,OAAsB;IAC/D,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACpE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE;QACxB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,EAAE,CAAC;gBACzC,WAAW,EAAE,CAAC,cAAc,CAAC,CAAC;YAChC,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,wGAAwG;AACxG,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,IAAI,OAAO,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO;IACpD,cAAc,GAAG,OAAO,CAAC;AAC3B,CAAC;AAED,wGAAwG;AACxG,0GAA0G;AAC1G,MAAM,UAAU,0BAA0B,CAAC,KAAqC;IAC9E,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC;AAED,IAAI,cAAc,GAAG,KAAK,CAAC;AAC3B,IAAI,WAAW,GAAmC,IAAI,CAAC"}
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,yFAAyF;AACzF,MAAM,UAAU,6BAA6B;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,uFAAuF;AACvF,wFAAwF;AACxF,yCAAyC;AACzC,MAAM,UAAU,mBAAmB,CAAsB,MAAqB;IAC5E,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACnE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACvB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,gBAAgB,IAAI,cAAc,EAAE,CAAC;gBAChD,wFAAwF;gBACxF,+FAA+F;gBAC/F,mGAAmG;gBACnG,6BAA6B;gBAC7B,WAAW,EAAE,CAAC,cAAc,CAAC,CAAC;YAChC,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,0FAA0F;AAC1F,2FAA2F;AAC3F,eAAe;AACf,MAAM,UAAU,0BAA0B,CAAC,OAAsB;IAC/D,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACpE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE;QACxB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,EAAE,CAAC;gBACzC,WAAW,EAAE,CAAC,cAAc,CAAC,CAAC;YAChC,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,wGAAwG;AACxG,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,IAAI,OAAO,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO;IACpD,cAAc,GAAG,OAAO,CAAC;AAC3B,CAAC;AAED,wGAAwG;AACxG,0GAA0G;AAC1G,MAAM,UAAU,0BAA0B,CAAC,KAAqC;IAC9E,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC;AAED,IAAI,cAAc,GAAG,KAAK,CAAC;AAC3B,IAAI,WAAW,GAAmC,IAAI,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/entity",
-  "version": "0.5.1-next.693.478551c",
+  "version": "0.5.1-next.729.2aeb707",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/log": "0.5.1-next.693.478551c",
-    "@flighthq/types": "0.5.1-next.693.478551c"
+    "@flighthq/log": "0.5.1-next.729.2aeb707",
+    "@flighthq/types": "0.5.1-next.729.2aeb707"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/binding.test.ts

@@ -1,6 +1,12 @@
 import { EntityRuntimeKey } from '@flighthq/types/contract';
 
-import { attachEntityBinding, getEntityBinding } from './binding';
+import {
+  attachEntityBinding,
+  detachEntityBinding,
+  getEntityBinding,
+  getEntityBindingAs,
+  hasEntityBinding,
+} from './binding';
 import { createEntity } from './entity';
 import { createEntityRuntime, getEntityRuntime } from './runtime';
 
@@ -32,6 +38,28 @@ describe('attachEntityBinding', () => {
   });
 });
 
+describe('detachEntityBinding', () => {
+  it('clears the binding while preserving the runtime', () => {
+    const entity = createEntity();
+    const runtime = createEntityRuntime();
+    runtime.binding = {};
+    entity[EntityRuntimeKey] = runtime;
+
+    detachEntityBinding(entity);
+
+    expect(entity[EntityRuntimeKey]).toBe(runtime);
+    expect(runtime.binding).toBeNull();
+  });
+
+  it('does not allocate a runtime when no binding exists', () => {
+    const entity = createEntity();
+
+    detachEntityBinding(entity);
+
+    expect(entity[EntityRuntimeKey]).toBeUndefined();
+  });
+});
+
 describe('getEntityBinding', () => {
   it('returns null if the entity has no runtime', () => {
     const entity = createEntity();
@@ -51,4 +79,46 @@ describe('getEntityBinding', () => {
     entity[EntityRuntimeKey] = runtime;
     expect(getEntityBinding(entity)).toStrictEqual(runtime.binding);
   });
+
+  it('accepts a readonly entity', () => {
+    const entity: Readonly<ReturnType<typeof createEntity>> = createEntity();
+    expect(getEntityBinding(entity)).toBeNull();
+  });
+});
+
+describe('getEntityBindingAs', () => {
+  it('returns the binding with the caller-owned type', () => {
+    const entity = createEntity();
+    const binding = { name: 'wrapper' };
+    attachEntityBinding(entity, binding);
+
+    const result = getEntityBindingAs<{ name: string }>(entity);
+
+    expectTypeOf(result).toEqualTypeOf<{ name: string } | null>();
+    expect(result).toBe(binding);
+  });
+
+  it('returns null if no binding exists', () => {
+    const entity: Readonly<ReturnType<typeof createEntity>> = createEntity();
+    expect(getEntityBindingAs<{ name: string }>(entity)).toBeNull();
+  });
+});
+
+describe('hasEntityBinding', () => {
+  it('returns false if the entity has no runtime', () => {
+    const entity: Readonly<ReturnType<typeof createEntity>> = createEntity();
+    expect(hasEntityBinding(entity)).toBe(false);
+  });
+
+  it('returns false if the binding slot is empty', () => {
+    const entity = createEntity();
+    entity[EntityRuntimeKey] = createEntityRuntime();
+    expect(hasEntityBinding(entity)).toBe(false);
+  });
+
+  it('returns true if a binding exists', () => {
+    const entity = createEntity();
+    attachEntityBinding(entity, {});
+    expect(hasEntityBinding(entity)).toBe(true);
+  });
 });

package/src/enableEntityRuntimeGuards.test.ts

@@ -46,8 +46,7 @@ describe('enableEntityRuntimeGuards', () => {
       }
     });
     expect(entries.length).toBe(1);
-    // Names a function that actually exists: the point of the warning is that the caller can act on it,
-    // and this guard spent its life directing readers to `ensureEntityRuntime`, which never existed.
+    // Names a function that actually exists: the point of the warning is that the caller can act on it.
     expect(messageOf(entries[0])).toContain('attachEntityBinding');
   });
 
@@ -62,6 +61,7 @@ describe('enableEntityRuntimeGuards', () => {
     });
     expect(entries.length).toBe(1);
     expect(messageOf(entries[0])).toContain('attachEntityBinding');
+    expect(messageOf(entries[0])).toContain('detachEntityBinding');
   });
 
   it('stays SILENT without the guard — the production default', () => {