Narrow public node/edge types; drop docmaker allowlist (parity item #1)

Derive the public NodeCollection/EdgeCollection/NodeSingular/EdgeSingular
by omitting the documented cross-kind members from the wide internal
Collection/Element (EdgeOnlyKeys hidden from nodes, NodeOnlyKeys from
edges). The runtime prototype stays shared, so Collection/Element remain
wide internally; a new kind-agnostic SharedCollection base lets internal
helpers accept any collection without casts, and the few mixed-collection
algorithm spots are widened/cast locally.

Upgrade the docmaker surface audit to resolve effective members through
the TypeScript type checker (so it understands the Omit<>-based
projections), which also lets the Core surface resolve fully. The audit
now runs with no allowlisted cross-kind exceptions and api.test-d.ts
asserts node/edge reject each other's methods.

Closes the last of the three d.ts parity gaps (TYPESCRIPT-MIGRATION.md);
the generated .d.ts is now the source-of-truth type surface.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: maxkfranz

TYPESCRIPT-MIGRATION.md

@@ -60,19 +60,21 @@ The runtime keeps its prototype-mixin structure; the types mirror it:
   via a shared permissive `Renderer` interface; params/locals/data are
   typed honestly.
 
-## Parity with the old hand-written `index.d.ts` — remaining gap
-
-The generated d.ts (~2,100 lines) covers the **full method surface** of
-`Core`, `Collection`, and `Element` — more method coverage than the
-hand-written file, since every mixin method is typed. The public entry
-point now also re-exports the old broad node/edge alias family
-(`Singular`, `NodeSingular`, `EdgeSingular`, `NodeCollection`,
-`EdgeCollection`), and the documented search/traversal helpers return
-those aliases where appropriate. The old `index.d.ts` (6,644 lines) is
-kept in the repo as a reference and parity target. A docmaker-based audit
-(`npm run test:types:docs`) now checks that the generated `build/dts`
-surface matches the documented `cy.*` / `eles.*` / `ele.*` API and
-guards the remaining known exceptions.
+## Parity with the old hand-written `index.d.ts`
+
+The generated d.ts covers the **full method surface** of `Core`,
+`Collection`, and `Element` — more method coverage than the hand-written
+file, since every mixin method is typed. The public entry point also
+re-exports the old broad node/edge alias family (`Singular`,
+`NodeSingular`, `EdgeSingular`, `NodeCollection`, `EdgeCollection`), and the
+documented search/traversal helpers return those aliases where appropriate.
+The old `index.d.ts` (6,644 lines) is kept in the repo as a reference. A
+docmaker-based audit (`npm run test:types:docs`) checks that the generated
+`build/dts` surface matches the documented `cy.*` / `eles.*` / `ele.*` /
+`node.*` / `edge.*` API — with **no allowlisted exceptions**.
+
+All three areas that previously diverged from the hand-written file are now
+reproduced from source:
 
 **`Css.*` style-property types — done.** `src/style/css-types.mts` is now
 generated from the runtime style inventory (`src/style/properties.mts`) by
@@ -96,26 +98,24 @@ typed `any` on the base so the narrowed variants stay usable as handler
 parameters (function-parameter contravariance), matching the old declarations.
 `typescript/tests/api.test-d.ts` exercises all three target kinds.
 
-One area of the hand-written file is **not yet reproduced** from source and is
-the remaining work to reach full parity:
-
-1. **Node/edge public projections** — `NodeCollection` and
-  `EdgeCollection` are re-exported again, but they still structurally
-  inherit some cross-kind methods from the wide internal `Collection`
-  type in the generated declarations. Fully matching the docs requires a
-  dedicated public node/edge projection layer that omits edge-only
-  methods from node types and node-only methods from edge types. The exact
-  cross-kind method lists currently tolerated live in the
-  `allowedResidualExtras` allowlist in `test/types-docmaker-surface.mjs`
-  (18 edge-only methods leaking onto `NodeCollection`, 58 node-only onto
-  `EdgeCollection`).
-
-Until then, downstream TypeScript users still see some node/edge
-cross-kind methods on the generated `NodeCollection` / `EdgeCollection`
-aliases.
-Reverting `package.json` `types` to `./index.d.ts` restores the richer
-hand-written types if that trade-off is preferred while the above source
-enrichment is completed.
+**Node/edge public projections — done.** `src/collection/eles-types.mts`
+keeps a wide internal `Collection`/`Element` (the shared prototype carries
+every element method at runtime, and internal code relies on that), and
+derives the public types by omitting the other kind's members:
+`NodeCollection`/`NodeSingular` drop the edge-only members (`source`,
+`target`, endpoints, edge geometry, …) and `EdgeCollection`/`EdgeSingular`
+drop the node-only members (compounds, degree, position, grab/lock,
+clustering, …). The omitted name lists (`EdgeOnlyKeys`/`NodeOnlyKeys`) are
+the documented cross-kind split, and a new kind-agnostic base
+`SharedCollection` lets internal helpers accept any collection without
+casts. The docmaker audit now resolves the effective member set through the
+TypeScript type checker (so it understands the `Omit<>`-based projections)
+and passes with no residual allowlist; `typescript/tests/api.test-d.ts`
+asserts (via `@ts-expect-error`) that node types reject edge-only methods
+and vice versa.
+
+The generated `.d.ts` is now the source-of-truth type surface; the
+hand-written `index.d.ts` remains only as a historical reference.
 
 ## Current validation coverage and limits
 
@@ -131,11 +131,13 @@ parity with the old hand-written `index.d.ts`:
   and representative usage, but it is not an exhaustive public API
   parity test.
 - `npm run test:types:docs` audits the freshly generated
-  `build/dts/index.d.ts` against `documentation/docmaker.json`, but only
-  for the broad documented surfaces represented as `cy.*`, `eles.*`, and
-  `ele.*` plus the narrowed `NodeCollection` / `EdgeCollection` aliases.
-  It is a doc-surface audit, not a symbol-for-symbol comparison against
-  the old `index.d.ts`.
+  `build/dts/index.d.ts` against `documentation/docmaker.json` for the
+  documented `cy.*`, `eles.*`, `ele.*`, `node.*`, and `edge.*` surfaces. It
+  resolves effective members through the TypeScript type checker (so it
+  understands the `Omit<>`-based node/edge projections) and runs with **no
+  residual allowlist** — it both rejects undocumented members and requires
+  documented ones on each kind. It is a doc-surface audit, not a
+  symbol-for-symbol comparison against the old `index.d.ts`.
 - `npm run test:types:css` audits the generated `Css.*` style surface
   against the live runtime property inventory in `src/style/properties.mts`,
   failing on any documented-but-untyped or typed-but-unknown property. It
@@ -145,17 +147,10 @@ parity with the old hand-written `index.d.ts`:
 
 Known limitations of the current docmaker audit:
 
-- It currently passes with an explicit allowlist of known residual
-  exceptions for `NodeCollection` and `EdgeCollection` in
-  `test/types-docmaker-surface.mjs`. Those exceptions are the remaining
-  cross-kind methods inherited from the wide internal `Collection` type.
-- It enforces that undocumented `cy.*`, `eles.*`, and `ele.*` methods are
-  not exposed on the generated declarations, but it does **not** yet give
-  that same unconditional guarantee for narrowed node/edge projections.
-- It does not validate the exact overload shapes, generic constraints,
-  or argument/return precision of every documented API entry; it checks
-  presence/absence of the documented member names on the audited public
-  interfaces.
+- It enforces presence/absence of documented member *names* on the audited
+  public interfaces (`cy.*`, `eles.*`, `ele.*`, `node.*`, `edge.*`), but it
+  does not validate the exact overload shapes, generic constraints, or
+  argument/return precision of every documented API entry.
 - It does not assert full top-level export parity with the old manual
   declarations beyond the names used in the representative consumer test
   (e.g. broad alias-family presence like `NodeSingular` / `EdgeSingular`

dist/cytoscape.d.ts

@@ -531,21 +531,21 @@ interface CollectionComparators {
   is(selector: string): boolean;
   some(fn: CollectionTestFn, thisArg?: unknown): boolean;
   every(fn: CollectionTestFn, thisArg?: unknown): boolean;
-  same(collection: Collection | Element$1 | string): boolean;
-  anySame(collection: Collection | Element$1 | string): boolean;
-  allAreNeighbors(collection: Collection | Element$1 | string): boolean;
-  allAreNeighbours(collection: Collection | Element$1 | string): boolean;
-  contains(collection: Collection | Element$1 | string): boolean;
-  has(collection: Collection | Element$1 | string): boolean;
+  same(collection: SharedCollection | string): boolean;
+  anySame(collection: SharedCollection | string): boolean;
+  allAreNeighbors(collection: SharedCollection | string): boolean;
+  allAreNeighbours(collection: SharedCollection | string): boolean;
+  contains(collection: SharedCollection | string): boolean;
+  has(collection: SharedCollection | string): boolean;
 }
 //#endregion
 //#region src/collection/filter.d.mts
 /** A predicate run against each element of a collection. */
 type FilterEleFn = (ele: Element$1, i: number, eles: Collection) => boolean | unknown;
 /** Inputs accepted by `.filter()` and friends: selector string, predicate, or collection. */
-type FilterArg = string | FilterEleFn | Collection | Element$1 | undefined | null;
+type FilterArg = string | FilterEleFn | SharedCollection | undefined | null;
 /** Inputs accepted by set operations: selector string or collection. */
-type SetArg = string | Collection | Element$1 | undefined | null;
+type SetArg = string | SharedCollection | undefined | null;
 /** Result of `.diff()`/`.difference()`. */
 interface DiffResult {
   left: Collection;
@@ -1500,12 +1500,12 @@ interface RemoveDataFunc<Self> {
 //#region src/collection/data.d.mts
 /** Data/scratch accessors contributed to the collection prototype. */
 interface CollectionData {
-  data: DataFunc<Collection>;
-  removeData: RemoveDataFunc<Collection>;
-  scratch: DataFunc<Collection>;
-  removeScratch: RemoveDataFunc<Collection>;
-  attr: DataFunc<Collection>;
-  removeAttr: RemoveDataFunc<Collection>;
+  data: DataFunc<SharedCollection>;
+  removeData: RemoveDataFunc<SharedCollection>;
+  scratch: DataFunc<SharedCollection>;
+  removeScratch: RemoveDataFunc<SharedCollection>;
+  attr: DataFunc<SharedCollection>;
+  removeAttr: RemoveDataFunc<SharedCollection>;
   id(): string | undefined;
 }
 //#endregion
@@ -1533,25 +1533,25 @@ type PositionFn = (ele: Element$1, i: number) => Position | undefined | false;
  * full/partial Position, a (name, value) pair, or an event handler).
  */
 interface PositionAccessor {
-  (this: Collection): Position;
-  (this: Collection, pos: Partial<Position>): Collection;
-  (this: Collection, name: string): number;
-  (this: Collection, name: string, value: number): Collection;
-  (this: Collection, handler: (...args: any[]) => void): Collection;
+  (this: SharedCollection): Position;
+  (this: SharedCollection, pos: Partial<Position>): Collection;
+  (this: SharedCollection, name: string): number;
+  (this: SharedCollection, name: string, value: number): Collection;
+  (this: SharedCollection, handler: (...args: any[]) => void): Collection;
 }
 /** Position accessor methods contributed to the collection prototype. */
 interface CollectionPosition {
   position: PositionAccessor;
   modelPosition: PositionAccessor;
   point: PositionAccessor;
-  positions(this: Collection, pos: Partial<Position> | PositionFn, silent?: boolean): Collection;
-  modelPositions(this: Collection, pos: Partial<Position> | PositionFn, silent?: boolean): Collection;
-  points(this: Collection, pos: Partial<Position> | PositionFn, silent?: boolean): Collection;
-  shift(this: Collection, dim: Partial<Position> | string, val?: number | boolean, silent?: boolean): Collection;
-  renderedPosition(this: Collection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
-  renderedPoint(this: Collection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
-  relativePosition(this: Collection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
-  relativePoint(this: Collection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
+  positions(this: SharedCollection, pos: Partial<Position> | PositionFn, silent?: boolean): Collection;
+  modelPositions(this: SharedCollection, pos: Partial<Position> | PositionFn, silent?: boolean): Collection;
+  points(this: SharedCollection, pos: Partial<Position> | PositionFn, silent?: boolean): Collection;
+  shift(this: SharedCollection, dim: Partial<Position> | string, val?: number | boolean, silent?: boolean): Collection;
+  renderedPosition(this: SharedCollection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
+  renderedPoint(this: SharedCollection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
+  relativePosition(this: SharedCollection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
+  relativePoint(this: SharedCollection, dim?: Partial<Position> | string, val?: number): Position | number | Collection | undefined;
 }
 //#endregion
 //#region src/collection/dimensions/bounds.d.mts
@@ -1571,11 +1571,11 @@ interface BoundingBoxOptions {
 }
 /** Bounding-box methods contributed to the collection prototype. */
 interface CollectionBounds {
-  renderedBoundingBox(this: Collection, options?: BoundingBoxOptions): BoundingBox;
-  renderedBoundingbox(this: Collection, options?: BoundingBoxOptions): BoundingBox;
-  boundingBox(this: Collection, options?: BoundingBoxOptions): BoundingBox;
-  boundingbox(this: Collection, options?: BoundingBoxOptions): BoundingBox;
-  bb(this: Collection, options?: BoundingBoxOptions): BoundingBox;
+  renderedBoundingBox(this: SharedCollection, options?: BoundingBoxOptions): BoundingBox;
+  renderedBoundingbox(this: SharedCollection, options?: BoundingBoxOptions): BoundingBox;
+  boundingBox(this: SharedCollection, options?: BoundingBoxOptions): BoundingBox;
+  boundingbox(this: SharedCollection, options?: BoundingBoxOptions): BoundingBox;
+  bb(this: SharedCollection, options?: BoundingBoxOptions): BoundingBox;
 }
 //#endregion
 //#region src/collection/dimensions/width-height.d.mts
@@ -1725,11 +1725,11 @@ interface LayoutDimensions {
 }
 /** Layout methods contributed to the collection prototype. */
 interface CollectionLayout {
-  layoutDimensions(this: Collection, options: LayoutDimensionsOptions): LayoutDimensions;
-  layoutPositions(this: Collection, layout: LayoutLike, options: LayoutOptions, fn: LayoutPositionFn): Collection;
-  layout(this: Collection, options?: Partial<LayoutOptions>): LayoutLike;
-  createLayout(this: Collection, options?: Partial<LayoutOptions>): LayoutLike;
-  makeLayout(this: Collection, options?: Partial<LayoutOptions>): LayoutLike;
+  layoutDimensions(this: SharedCollection, options: LayoutDimensionsOptions): LayoutDimensions;
+  layoutPositions(this: SharedCollection, layout: LayoutLike, options: LayoutOptions, fn: LayoutPositionFn): Collection;
+  layout(this: SharedCollection, options?: Partial<LayoutOptions>): LayoutLike;
+  createLayout(this: SharedCollection, options?: Partial<LayoutOptions>): LayoutLike;
+  makeLayout(this: SharedCollection, options?: Partial<LayoutOptions>): LayoutLike;
 }
 //#endregion
 //#region src/collection/style.d.mts
@@ -1770,7 +1770,7 @@ interface CollectionSwitchFunctions {
 //#endregion
 //#region src/collection/traversing.d.mts
 /** Selector/filter argument accepted by traversal methods. */
-type SelectorArg = string | ((ele: Element$1, i: number, eles: Collection) => boolean | unknown) | Collection | Element$1 | undefined | null;
+type SelectorArg = string | ((ele: Element$1, i: number, eles: Collection) => boolean | unknown) | SharedCollection | undefined | null;
 interface CollectionTraversing {
   roots(selector?: SelectorArg): NodeCollection;
   leaves(selector?: SelectorArg): NodeCollection;
@@ -1921,9 +1921,14 @@ interface Collection extends CollectionBaseFns, CollectionAlgorithms, Collection
 }
 /** A single element (node or edge); array-like of itself, length 1. */
 interface Element$1 extends Collection {}
-type PublicSelectorArg = string | Collection | Element$1 | ((ele: Element$1, i: number, eles: Collection) => boolean | unknown) | undefined | null;
+type PublicSelectorArg = string | SharedCollection | ((ele: Element$1, i: number, eles: Collection) => boolean | unknown) | undefined | null;
 type Singular = Element$1;
-interface NodeCollection extends Collection {
+/** Edge-only members hidden from the public node types. */
+type EdgeOnlyKeys = 'source' | 'target' | 'sources' | 'targets' | 'connectedNodes' | 'parallelEdges' | 'codirectedEdges' | 'isLoop' | 'isSimple' | 'midpoint' | 'controlPoints' | 'segmentPoints' | 'sourceEndpoint' | 'targetEndpoint' | 'renderedMidpoint' | 'renderedControlPoints' | 'renderedSegmentPoints' | 'renderedSourceEndpoint' | 'renderedTargetEndpoint';
+/** Node-only members hidden from the public edge types. */
+type NodeOnlyKeys = 'parent' | 'parents' | 'ancestors' | 'commonAncestors' | 'children' | 'siblings' | 'descendants' | 'roots' | 'leaves' | 'orphans' | 'nonorphans' | 'isParent' | 'isChild' | 'isChildless' | 'isOrphan' | 'connectedEdges' | 'edgesWith' | 'edgesTo' | 'degree' | 'indegree' | 'outdegree' | 'totalDegree' | 'minDegree' | 'maxDegree' | 'minIndegree' | 'maxIndegree' | 'minOutdegree' | 'maxOutdegree' | 'incomers' | 'outgoers' | 'successors' | 'predecessors' | 'position' | 'positions' | 'modelPosition' | 'modelPositions' | 'point' | 'points' | 'relativePosition' | 'relativePoint' | 'renderedPosition' | 'renderedPoint' | 'shift' | 'grabbable' | 'grabbed' | 'grabify' | 'ungrabify' | 'lock' | 'unlock' | 'locked' | 'layoutDimensions' | 'layoutPositions' | 'affinityPropagation' | 'ap' | 'fuzzyCMeans' | 'fcm' | 'hierarchicalClustering' | 'hca' | 'kMeans' | 'kMedoids';
+/** Node-kind return-type narrowings layered over the wide collection. */
+interface NodeCollectionNarrowed {
   parent(selector?: PublicSelectorArg): NodeCollection;
   parents(selector?: PublicSelectorArg): NodeCollection;
   ancestors(selector?: PublicSelectorArg): NodeCollection;
@@ -1937,19 +1942,24 @@ interface NodeCollection extends Collection {
   leaves(selector?: PublicSelectorArg): NodeCollection;
   connectedEdges(selector?: PublicSelectorArg): EdgeCollection;
 }
-interface EdgeCollection extends Collection {
+/** Edge-kind return-type narrowings layered over the wide collection. */
+interface EdgeCollectionNarrowed {
   source(selector?: PublicSelectorArg): NodeSingular;
   target(selector?: PublicSelectorArg): NodeSingular;
   sources(selector?: PublicSelectorArg): NodeCollection;
   targets(selector?: PublicSelectorArg): NodeCollection;
-  edgesWith(otherNodes: string | Collection): EdgeCollection;
-  edgesTo(otherNodes: string | Collection): EdgeCollection;
   connectedNodes(selector?: PublicSelectorArg): NodeCollection;
   parallelEdges(selector?: PublicSelectorArg): EdgeCollection;
   codirectedEdges(selector?: PublicSelectorArg): EdgeCollection;
 }
-type NodeSingular = Singular & NodeCollection;
-type EdgeSingular = Singular & EdgeCollection;
+type NodeNarrowedKeys = keyof NodeCollectionNarrowed;
+type EdgeNarrowedKeys = keyof EdgeCollectionNarrowed;
+/** Kind-agnostic collection: members common to both nodes and edges. */
+type SharedCollection = Omit<Collection, EdgeOnlyKeys | NodeOnlyKeys>;
+type NodeCollection = Omit<Collection, EdgeOnlyKeys | NodeNarrowedKeys> & NodeCollectionNarrowed;
+type EdgeCollection = Omit<Collection, NodeOnlyKeys | EdgeNarrowedKeys> & EdgeCollectionNarrowed;
+type NodeSingular = Omit<Element$1, EdgeOnlyKeys | NodeNarrowedKeys> & NodeCollectionNarrowed;
+type EdgeSingular = Omit<Element$1, NodeOnlyKeys | EdgeNarrowedKeys> & EdgeCollectionNarrowed;
 //#endregion
 //#region src/style/css-types.d.mts
 /**

src/collection/algorithms/betweenness-centrality.mts

@@ -1,6 +1,6 @@
 import Heap from '../../heap.mjs';
 import * as util from '../../util/index.mjs';
-import type { Collection, Element } from '../eles-types.mjs';
+import type { Collection, SharedCollection, Element } from '../eles-types.mjs';
 
 /** Edge weighting function. */
 export type BetweennessWeightFn = ( edge: Element ) => number;
@@ -38,7 +38,7 @@ let elesfn = ({
 
     // starting
     let V = this.nodes();
-    let A: Record<string, Collection> = {};
+    let A: Record<string, SharedCollection> = {};
     let _C: Record<string, number> = {};
     let max = 0;
     let C = {