> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Effect-TS/tsgo/llms.txt
> Use this file to discover all available pages before exploring further.

# Effect-native diagnostics

> Diagnostics that encourage using Effect-native APIs and abstractions instead of raw JavaScript equivalents.

Effect-native diagnostics guide you toward the Effect ecosystem's purpose-built APIs for common operations — HTTP requests, JSON parsing, schema validation, and more. All rules in this category are **off by default** (except `preferSchemaOverJson` which is a suggestion), so you opt in to the ones that fit your project's strictness requirements.

<Info>
  All rules in this category are ➖ off by default or 💡 suggestion level. Enable them via `diagnosticSeverity` in your plugin config.
</Info>

## `extendsNativeError`

**Severity:** ➖ off by default  ·  **V3/V4:** ✓ / ✓

Warns when a class directly extends the native JavaScript `Error` class. Native `Error` subclasses are untagged and indistinguishable at the type level in Effect's failure channel. Using `Data.TaggedError` instead gives your errors a `_tag` discriminant that enables precise `Effect.catchTag` handling.

```typescript theme={null}
import { Data } from "effect"

// ❌ Violation — native Error is untagged
class DatabaseError extends Error {
  constructor(message: string) {
    super(message)
    this.name = "DatabaseError"
  }
}

// ✅ Correct — tagged error enables precise error handling
class DatabaseError extends Data.TaggedError("DatabaseError")<{
  message: string
}> {}

// Now you can handle it precisely:
// Effect.catchTag("DatabaseError", (e) => ...)
```

To enable:

```jsonc theme={null}
{ "diagnosticSeverity": { "extendsNativeError": "warning" } }
```

***

## `globalFetch`

**Severity:** ➖ off by default  ·  **V3/V4:** ✓ / ✓

Warns when the global `fetch` function is used instead of the Effect HTTP client. The global `fetch` is a Promise-based API that throws on network errors and returns responses that require manual error checking. The Effect HTTP client integrates errors into the typed error channel.

```typescript theme={null}
import { Effect } from "effect"
import { HttpClient } from "@effect/platform"

// ❌ Violation — global fetch, errors are untyped
const getUser = Effect.gen(function* () {
  const response = await fetch("/api/users/1") // Promise, not Effect
  return response.json()
})

// ✅ Correct — Effect HTTP client with typed errors
const getUser = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient
  const response = yield* client.get("/api/users/1")
  return yield* response.json
})
```

To enable:

```jsonc theme={null}
{ "diagnosticSeverity": { "globalFetch": "warning" } }
```

***

## `instanceOfSchema`

**Severity:** ➖ off by default  ·  **Fix:** 🔧  ·  **V3/V4:** ✓ / ✓

Suggests using `Schema.is` instead of the `instanceof` operator for Effect Schema types. `instanceof` does not account for Schema's structural validation and decoded representations, while `Schema.is` performs a proper type-guard check that respects the schema's constraints.

```typescript theme={null}
import { Schema } from "effect"

const UserSchema = Schema.Struct({ id: Schema.String, name: Schema.String })
type User = Schema.Schema.Type<typeof UserSchema>

declare const value: unknown

// ❌ Violation — instanceof does not validate schema constraints
if (value instanceof Object && "id" in value) {
  // not a proper schema check
}

// ✅ Correct — Schema.is performs a proper type-guard
const isUser = Schema.is(UserSchema)
if (isUser(value)) {
  // value is User here, fully type-safe
}
```

The quick fix replaces the `instanceof` check with `Schema.is(...)` automatically.

To enable:

```jsonc theme={null}
{ "diagnosticSeverity": { "instanceOfSchema": "warning" } }
```

***

## `nodeBuiltinImport`

**Severity:** ➖ off by default  ·  **V3/V4:** ✓ / ✓

Warns when you import Node.js built-in modules (like `fs`, `path`, `crypto`) that have Effect-native counterparts in `@effect/platform`. The Effect platform modules provide the same functionality with typed errors and Effect integration.

```typescript theme={null}
// ❌ Violation — importing Node.js built-in directly
import * as fs from "node:fs"
import * as path from "node:path"

// ✅ Correct — use Effect platform counterparts
import { FileSystem } from "@effect/platform"
import { NodeFileSystem } from "@effect/platform-node"

const program = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem
  const content = yield* fs.readFileString("./config.json")
  return content
})
```

To enable:

```jsonc theme={null}
{ "diagnosticSeverity": { "nodeBuiltinImport": "warning" } }
```

***

## `preferSchemaOverJson`

**Severity:** 💡 suggestion  ·  **V3/V4:** ✓ / ✓

Suggests using Effect Schema for JSON operations instead of `JSON.parse` and `JSON.stringify`. `JSON.parse` throws on invalid input and returns `any`; Effect Schema provides type-safe parsing with proper error handling through the effect error channel.

```typescript theme={null}
import { Effect, Schema } from "effect"

const UserSchema = Schema.Struct({ id: Schema.String, name: Schema.String })

// ❌ Violation — JSON.parse returns any and throws on error
const parseUser = (raw: string) => {
  const data = JSON.parse(raw) // any, can throw
  return data as User
}

// ✅ Correct — Schema.decode provides typed parsing with Effect errors
const parseUser = (raw: string) =>
  Effect.gen(function* () {
    const json = yield* Effect.try({
      try: () => JSON.parse(raw),
      catch: (e) => new ParseError({ cause: e })
    })
    return yield* Schema.decode(UserSchema)(json)
  })
```