@flighthq/easing 0.3.0-next.1315.1d4eb64 → 0.3.0-next.1392.f0bd0cc

package/dist/contract.d.ts

@@ -1,5 +1,6 @@
 export * from './createEasingSamples';
 export * from './easeBack';
+export * from './enableEasingGuards';
 export * from './easeBounce';
 export * from './easeCircular';
 export * from './easeCombinators';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dist/contract.js

@@ -1,5 +1,6 @@
 export * from './createEasingSamples';
 export * from './easeBack';
+export * from './enableEasingGuards';
 export * from './easeBounce';
 export * from './easeCircular';
 export * from './easeCombinators';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dist/enableEasingGuards.d.ts

@@ -0,0 +1,3 @@
+export declare function disableEasingGuards(): void;
+export declare function enableEasingGuards(): void;
+//# sourceMappingURL=enableEasingGuards.d.ts.map

package/dist/enableEasingGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableEasingGuards.d.ts","sourceRoot":"","sources":["../src/enableEasingGuards.ts"],"names":[],"mappings":"AAOA,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAWD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/enableEasingGuards.js

@@ -0,0 +1,25 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setEasingStepsGuard } from './easeSteps';
+// Uninstalls the guard installed by enableEasingGuards.
+export function disableEasingGuards() {
+    setEasingStepsGuard(null);
+}
+// Installs the caller-facing easing guard (opt-in, dev-only). This package has one silent footgun:
+// `easeSteps(count, 'jumpNone')` with `count < 2` leaves zero jumps, so the returned function divides by
+// zero and hands back NaN for every input. Nothing throws and nothing logs — the NaN just propagates into
+// whatever the easing drives, which is why a comment telling callers "pass count >= 2" was not enough.
+//
+// @flighthq/easing is a CORE package, and core may otherwise depend only on types/core. This module is the
+// sanctioned exception: it is separately importable and shakeable, so a build that never imports it never
+// pulls @flighthq/log, and the layer rule's actual concern — feature weight in core's always-loaded graph —
+// does not arise. `packages:check` enforces that the import appears in guard modules only. Idempotent.
+export function enableEasingGuards() {
+    setEasingStepsGuard(warnOnDegenerateSteps);
+}
+function warnOnDegenerateSteps(count, position) {
+    logOnce('easing:degenerate-steps', LogLevel.Warn, {
+        message: `easeSteps(${count}, '${position}'): '${position}' has count - 1 jumps, so it needs count >= 2. With ${count} there are no jumps, the easing divides by zero, and every input returns NaN. Pass count >= 2, or use a position that jumps at an edge ('jumpEnd', 'jumpStart', 'jumpBoth') — those are defined for count >= 1.`,
+    }, 'easing');
+}
+//# sourceMappingURL=enableEasingGuards.js.map

package/dist/enableEasingGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableEasingGuards.js","sourceRoot":"","sources":["../src/enableEasingGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,wDAAwD;AACxD,MAAM,UAAU,mBAAmB;IACjC,mBAAmB,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,mGAAmG;AACnG,yGAAyG;AACzG,0GAA0G;AAC1G,uGAAuG;AACvG,EAAE;AACF,2GAA2G;AAC3G,0GAA0G;AAC1G,4GAA4G;AAC5G,uGAAuG;AACvG,MAAM,UAAU,kBAAkB;IAChC,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa,EAAE,QAAsB;IAClE,OAAO,CACL,yBAAyB,EACzB,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EAAE,aAAa,KAAK,MAAM,QAAQ,QAAQ,QAAQ,uDAAuD,KAAK,iNAAiN;KACvU,EACD,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/easing",
-  "version": "0.3.0-next.1315.1d4eb64",
+  "version": "0.3.0-next.1392.f0bd0cc",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,7 +36,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.0-next.1315.1d4eb64"
+    "@flighthq/log": "0.3.0-next.1392.f0bd0cc",
+    "@flighthq/types": "0.3.0-next.1392.f0bd0cc"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/easeSteps.test.ts

@@ -1,3 +1,5 @@
+import type { StepPosition } from '@flighthq/types/contract';
+
 import { easeSteps, setEasingStepsGuard } from './easeSteps';
 
 describe('easeSteps', () => {
@@ -65,34 +67,31 @@ describe('easeSteps', () => {
 });
 
 describe('setEasingStepsGuard', () => {
-  it('invokes the installed guard for the degenerate jumpNone, count<2 call', () => {
-    const calls: unknown[] = [];
-    setEasingStepsGuard((count, position) => calls.push([count, position]));
+  it('reports the degenerate jumpNone call that silently returns NaN', () => {
+    const seen: [number, StepPosition][] = [];
+    setEasingStepsGuard((count, position) => seen.push([count, position]));
     try {
-      easeSteps(1, 'jumpNone');
-      expect(calls).toEqual([[1, 'jumpNone']]);
+      // The failure being reported: one step with no edge jump leaves zero jumps to divide by.
+      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
     } finally {
       setEasingStepsGuard(null);
     }
+    expect(seen).toEqual([[1, 'jumpNone']]);
   });
 
-  it('does not invoke the guard for well-defined calls', () => {
-    const calls: unknown[] = [];
-    setEasingStepsGuard((count, position) => calls.push([count, position]));
+  it('stays silent for well-defined calls, and once uninstalled', () => {
+    const seen: number[] = [];
+    setEasingStepsGuard((count) => seen.push(count));
     try {
-      easeSteps(4, 'jumpNone');
-      easeSteps(1, 'jumpEnd');
-      expect(calls).toEqual([]);
+      easeSteps(2, 'jumpNone')(0.5); // count >= 2 is the documented minimum for jumpNone
+      easeSteps(1, 'jumpEnd')(0.5); // edge-jumping positions are defined for count >= 1
+      easeSteps(1, 'jumpBoth')(0.5);
     } finally {
       setEasingStepsGuard(null);
     }
-  });
-
-  it('stops invoking a previously installed guard once set back to null', () => {
-    const calls: unknown[] = [];
-    setEasingStepsGuard((count, position) => calls.push([count, position]));
-    setEasingStepsGuard(null);
-    easeSteps(1, 'jumpNone');
-    expect(calls).toEqual([]);
+    expect(seen).toEqual([]);
+    // Uninstalled: the degenerate call still returns NaN, but nothing is reported.
+    easeSteps(1, 'jumpNone')(0.5);
+    expect(seen).toEqual([]);
   });
 });

package/src/enableEasingGuards.test.ts

@@ -0,0 +1,70 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { easeSteps } from './easeSteps';
+import { disableEasingGuards, enableEasingGuards } from './enableEasingGuards';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function messageOf(entry: Readonly<LogEntry>): string {
+  const data = entry.data;
+  return typeof data === 'string' ? data : String(data.message);
+}
+
+describe('disableEasingGuards', () => {
+  it('uninstalls the guard, returning the degenerate call to silence', () => {
+    const entries = captureLog(() => {
+      enableEasingGuards();
+      disableEasingGuards();
+      // Still NaN — disabling removes the reporting, not the sharp edge.
+      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+    });
+    expect(entries.length).toBe(0);
+  });
+});
+
+describe('enableEasingGuards', () => {
+  it('WARNS on the degenerate jumpNone step count that silently returns NaN', () => {
+    const entries = captureLog(() => {
+      enableEasingGuards();
+      try {
+        expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+      } finally {
+        disableEasingGuards();
+      }
+    });
+    expect(entries.length).toBe(1);
+    expect(messageOf(entries[0])).toContain('count >= 2');
+  });
+
+  it('stays SILENT for well-defined calls, and without the guard at all', () => {
+    const guarded = captureLog(() => {
+      enableEasingGuards();
+      try {
+        easeSteps(2, 'jumpNone')(0.5);
+        easeSteps(1, 'jumpEnd')(0.5);
+        easeSteps(1, 'jumpStart')(0.5);
+        easeSteps(1, 'jumpBoth')(0.5);
+      } finally {
+        disableEasingGuards();
+      }
+    });
+    expect(guarded.length).toBe(0);
+
+    // Production default: still NaN, but nothing is logged — the guard is opt-in.
+    const unguarded = captureLog(() => {
+      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
+    });
+    expect(unguarded.length).toBe(0);
+  });
+});

package/src/easeStepsGuard.test.ts

@@ -1,34 +0,0 @@
-import type { StepPosition } from '@flighthq/types/contract';
-import { describe, expect, it } from 'vitest';
-
-import { easeSteps, setEasingStepsGuard } from './easeSteps';
-
-describe('setEasingStepsGuard', () => {
-  it('reports the degenerate jumpNone call that silently returns NaN', () => {
-    const seen: [number, StepPosition][] = [];
-    setEasingStepsGuard((count, position) => seen.push([count, position]));
-    try {
-      // The failure being reported: one step with no edge jump leaves zero jumps to divide by.
-      expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
-    } finally {
-      setEasingStepsGuard(null);
-    }
-    expect(seen).toEqual([[1, 'jumpNone']]);
-  });
-
-  it('stays silent for well-defined calls, and when no guard is installed', () => {
-    const seen: number[] = [];
-    setEasingStepsGuard((count) => seen.push(count));
-    try {
-      easeSteps(2, 'jumpNone')(0.5); // count >= 2 is the documented minimum for jumpNone
-      easeSteps(1, 'jumpEnd')(0.5); // every edge-jumping position is defined for count >= 1
-      easeSteps(1, 'jumpStart')(0.5);
-      easeSteps(1, 'jumpBoth')(0.5);
-    } finally {
-      setEasingStepsGuard(null);
-    }
-    expect(seen).toEqual([]);
-    // Production default: still NaN, but nothing is reported.
-    expect(Number.isNaN(easeSteps(1, 'jumpNone')(0.5))).toBe(true);
-  });
-});