René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Deprecate `insertVertex` and `insertEdge` legacy methods in AbstractGraph","articleBody":"The methods `insertVertex` and `insertEdge` come from mxGraph. They take a long list of parameters, which makes them hard to use and maintain. It's also not practical when adding new features, since each new feature often requires an additional parameter.\n\n- `insertVertex` legacy signature:  \n  https://github.com/maxGraph/maxGraph/blob/9130103a8e03123fd9b844caec5b7603a8746175/packages/core/src/view/mixins/VertexMixin.type.ts#L86-L97  \n- `insertEdge` legacy signature:  \n  https://github.com/maxGraph/maxGraph/blob/9130103a8e03123fd9b844caec5b7603a8746175/packages/core/src/view/mixins/EdgeMixin.type.ts#L185-L192\n\nIn maxGraph, we've already introduced new methods that take a single options object instead of a long list of arguments:\n\n- New `insertVertex` method:  \n  https://github.com/maxGraph/maxGraph/blob/9130103a8e03123fd9b844caec5b7603a8746175/packages/core/src/view/mixins/VertexMixin.type.ts#L132\n\n- New `insertEdge` method:  \n  https://github.com/maxGraph/maxGraph/blob/9130103a8e03123fd9b844caec5b7603a8746175/packages/core/src/view/mixins/EdgeMixin.type.ts#L201\n\nThese new APIs are easier to use:\n- Optional parameters can just be omitted (no need for `null` or `undefined`)\n- They are easier to read\n- Easier to extend with new features\n\nHowever, many examples and parts of the documentation still use the old methods. That makes it harder to encourage adoption of the new APIs and to plan the removal of the legacy ones.\n\n\u003e [!IMPORTANT]\n\u003e The old methods are already marked as legacy in their JSDoc.\n\n\n### Proposal\n\nWe should officially deprecate the legacy methods and promote the new ones. We won’t remove them yet, to avoid breaking changes and help users migrating from mxGraph.\n\n\n### Tasks (non-exhaustive)\n\n- [ ] Mark `insertVertex` and `insertEdge` as `@deprecated` in the source code\n  - Include the version in which they are deprecated\n- [x] Update JSDoc examples to use the new API. Done in #876\n- [x] Update documentation references. Done in #876\n  - [x] lots of usage in  tutorial/manual \n  - [x] in particular in https://maxgraph.github.io/maxGraph/docs/manual/model-and-transactions#inserting-cells\n- [ ] Update stories and examples:\n  - [x] examples in this repository. Done in #876\n  - [ ] examples in https://github.com/maxGraph/maxGraph-integration-examples/\n  - [ ] stories","author":{"url":"https://github.com/tbouffard","@type":"Person","name":"tbouffard"},"datePublished":"2025-06-26T07:06:43.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/856/maxGraph/issues/856"}