refactor(experiments): deprecate link method and update documentation to use runExperiment() instead

[marliessophie]

Greptile Summary

This PR deprecates the link() method on FetchedDataset items and redirects users to the runExperiment() API, removing the detailed JSDoc examples in favour of a deprecation notice and a runtime warn() log.

• The link property on each dataset item is now marked @deprecated in its JSDoc, and createDatasetItemLinkFunction emits a getGlobalLogger().warn() on every invocation.
• LinkDatasetItemFunction's type-level documentation now points to langfuse.experiment.run(), while the property-level JSDoc and runtime warning inconsistently reference runExperiment() — two different API surfaces that will confuse migrating users.
• The @deprecated tag was also placed on the items array property itself, not just on the link method inside each element, which will cause IDE tooling to strike through dataset.items even for code that never calls link().

Confidence Score: 4/5

The runtime behaviour of link() is unchanged; the only additions are a deprecation warning and updated JSDoc. The inconsistency in the migration target affects developer guidance rather than runtime correctness.

The LinkDatasetItemFunction type doc and the runtime warn() message both say langfuse.experiment.run(), while the FetchedDataset.items JSDoc says runExperiment(). These are two distinct methods, so users reading different parts of the documentation will be directed to different APIs when migrating away from link(). Additionally, placing @deprecated on the items array itself will cause IDE tooling to strike through any access to dataset.items, even for code that never touches link().

packages/client/src/dataset/index.ts — the deprecation message in LinkDatasetItemFunction and the runtime warning should be reconciled with the runExperiment() references used everywhere else.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User calls link on dataset item] --> B[createDatasetItemLinkFunction closure]
    B --> C[Emit deprecation warning via getGlobalLogger]
    C --> D[Extract traceId and spanId from otelSpan]
    D --> E[Call langfuseClient.api.datasetRunItems.create]
    E --> F[Return DatasetRunItem]

    G[Recommended migration path] --> H[dataset.runExperiment or langfuse.experiment.run]
    H --> I[ExperimentManager handles iteration and linking]
    I --> F

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User calls link on dataset item] --> B[createDatasetItemLinkFunction closure]
    B --> C[Emit deprecation warning via getGlobalLogger]
    C --> D[Extract traceId and spanId from otelSpan]
    D --> E[Call langfuseClient.api.datasetRunItems.create]
    E --> F[Return DatasetRunItem]

    G[Recommended migration path] --> H[dataset.runExperiment or langfuse.experiment.run]
    H --> I[ExperimentManager handles iteration and linking]
    I --> F

Loading

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
packages/client/src/dataset/index.ts:174-176
The deprecation message on `LinkDatasetItemFunction` and the runtime warning both say `langfuse.experiment.run()`, but the JSDoc on `FetchedDataset.items` (and its `link` property) says `runExperiment()`. These point to two different methods, so a user migrating away from `link()` will see contradictory guidance depending on where they look. The PR title indicates `runExperiment()` is the intended canonical replacement — the type-level doc and the runtime warning should match.

```suggestion
 * @deprecated Use `runExperiment()` instead for running experiments on datasets.
 * @see {@link https://langfuse.com/docs/evaluation/experiments/experiments-via-sdk#experiment-runner-sdk} Experiment SDK documentation
 * @public
```

### Issue 2 of 3
packages/client/src/dataset/index.ts:442-444
The same inconsistency exists in the runtime warning: it tells users to call `langfuse.experiment.run()` while the property-level JSDoc points to `runExperiment()`. A developer who reads the console warning at runtime and tries to look up `langfuse.experiment.run()` may not land on the intended `dataset.runExperiment()` shorthand.

```suggestion
      getGlobalLogger().warn(
        "dataset.items[].link() is deprecated. Use runExperiment() instead.",
      );
```

### Issue 3 of 3
packages/client/src/dataset/index.ts:157-161
The `@deprecated` tag is placed on the `items` array property itself rather than solely on the `link` method inside it. This implies to IDE tooling and users that `items` as a whole is deprecated, when only the `link` method on each element is. Users will see a strikethrough on `dataset.items` even when they are just reading items without using `link`.

```suggestion
  /** Dataset items fetched from this dataset. */
  items: (DatasetItem & {
    /** @deprecated Use `runExperiment()` instead. */
    link: LinkDatasetItemFunction;
  })[];
```

_{Reviews (1): Last reviewed commit: "refactor(experiments): deprecate link me..." | Re-trigger Greptile}

Greptile also left 3 inline comments on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Ready	Preview	Jul 2, 2026 7:47pm

[github-actions]

@claude review

[claude]

LGTM — small, mechanical deprecation change adding @deprecated tags and a runtime warning.

Extended reasoning...

Overview

This PR touches a single file (packages/client/src/dataset/index.ts) to mark the dataset.items[].link() API as deprecated in favor of runExperiment(). The changes are limited to: (1) adding @deprecated JSDoc tags on FetchedDataset.items[].link and the LinkDatasetItemFunction type alias, (2) simplifying the JSDoc on LinkDatasetItemFunction by removing examples that promoted the deprecated path, and (3) adding a runtime logger.warn inside the link closure. No behavior changes to the actual linking logic.

Security risks

None. This is documentation and a logger.warn call — no auth, crypto, input validation, or data-handling code is touched. The deprecation warning is a pure side effect with no user-controllable content.

Level of scrutiny

Low. This is a deprecation-marking PR: zero runtime behavior change to the underlying API beyond an emitted warning string. The risk surface is essentially limited to whether the deprecation messaging is accurate, which it is.

Other factors

The two inline nits posted by the bug hunter — a couple of leftover item.link() references in JSDoc @example blocks and the per-call (rather than once-per-process) warning — are both polish items, not correctness issues. The author can address them at their discretion; neither blocks the deprecation signal from landing. No outstanding human reviewer comments to resolve.