LINQ to TypeScript

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require` syntax in a project configured for ECMAScript Modules (ESM) after LinqToTypeScript v11.
  fix Change `const myLinq = require('linq-to-typescript');` to `import * as myLinq from 'linq-to-typescript';` or `import { from } from 'linq-to-typescript';`. Ensure `"type": "module"` is set in your `package.json`.

• TypeError: (0 , _linqToTypescript.from) is not a function

  cause This error typically occurs when there's a module resolution mismatch or incorrect import statement, especially in environments transpiling ESM to CJS, or when `from` is not correctly imported.
  fix Verify that `import { from } from 'linq-to-typescript';` is used and that your build tools (e.g., Webpack, Rollup, Babel) are configured to correctly handle ESM. Check `tsconfig.json` for `moduleResolution` and `module` settings.

• TS2307: Cannot find module 'linq-to-typescript' or its corresponding type declarations.

  cause Incorrect `tsconfig.json` configuration, particularly `target` and `lib` settings not matching the package's requirements, or issues with module resolution.
  fix Ensure your `tsconfig.json` includes `"target": "es2022"` and `"lib": ["es2022"]`. Also, verify that `moduleResolution` is set appropriately, e.g., `"nodenext"` or `"bundler"` for modern Node.js environments.

• UnhandledPromiseRejectionWarning: TypeError: [some method] is not a function

  cause Often happens when attempting to call an asynchronous LINQ method (e.g., `selectAsync`, `asParallel`) without correctly awaiting the `fromAsync` wrapper or the preceding async operation, or if `initializeLinq` for native types isn't called.
  fix Ensure that `await` is used before calling methods on `IAsyncEnumerable` or `IParallelEnumerable`. If using native extensions, confirm `initializeLinq()` has been called globally before methods are invoked.

Warnings

• breaking Starting with v11.0.0, the package ships exclusively with ECMAScript Modules (ESM). CommonJS is no longer supported, requiring project configuration (e.g., `"type": "module"` in `package.json`) and `import` syntax.
  Fix: Migrate all `require()` statements to `import` statements. Ensure your `package.json` specifies `"type": "module"` or use a `.mjs` extension for files using ESM imports. Update `tsconfig.json` `module` option if necessary.
• breaking The `zip` method's behavior was updated in v10.0.0 to align with .NET's implementation when dealing with enumerations of different lengths, which might alter results for existing code relying on previous behavior.
  Fix: Review existing uses of `zip` to ensure compatibility with the .NET-standard behavior. If the old behavior is needed, implement custom logic.
• gotcha LinqToTypeScript v12.0.0 and above are built with TypeScript 5.6.X and target ES2022. While generally backward compatible, using significantly older TypeScript versions in your project might lead to type-checking or build issues.
  Fix: It is recommended to use TypeScript 5.6.X or newer. Ensure your `tsconfig.json` has `"target": "es2022"` and `"lib": ["es2022"]`.
• gotcha The package requires Node.js version 17 or newer due to its engine specification. Running in older Node.js environments will result in errors.
  Fix: Upgrade your Node.js environment to version 17 or higher. Use a Node.js version manager like `nvm` to easily switch versions.

Install

• npm install linq-to-typescript npm
• yarn add linq-to-typescript yarn
• pnpm add linq-to-typescript pnpm

Imports

• from
  wrong:

  const { from } = require('linq-to-typescript')

  correct:

  import { from } from 'linq-to-typescript'

  Used to wrap iterable data sources for synchronous LINQ operations. The package is ESM-only since v11.0.0, so CommonJS `require` is not supported.
• initializeLinq
  wrong:

  const { initializeLinq } = require('linq-to-typescript')

  correct:

  import { initializeLinq } from 'linq-to-typescript'

  A utility function that binds LINQ methods directly to native JavaScript types like `Array`, `Map`, `Set`, and `String`, allowing for a more fluent, extension-method-like syntax. Requires `declare global` type augmentations.
• IEnumerable
  wrong:

  import IEnumerable from 'linq-to-typescript'

  correct:

  import { IEnumerable } from 'linq-to-typescript'

  The core interface representing a sequence of elements that can be queried. Primarily used for type declarations and when implementing custom enumerable types. It is a named export, not a default export.
• IAsyncEnumerable

  import { IAsyncEnumerable } from 'linq-to-typescript'

  The interface for sequences that support asynchronous iteration. Essential for operations that involve promises or awaitable data sources.

Quickstart

This quickstart demonstrates both the `from` wrapper and the native type extension pattern using `initializeLinq` for synchronous and asynchronous LINQ operations on arrays.

import { from, initializeLinq, IEnumerable } from 'linq-to-typescript';

// 1. Declare that the JS types implement the IEnumerable interface
declare global {
    interface Array<T> extends IEnumerable<T> { }
    interface String extends IEnumerable<string> { }
}

// 2. Bind Linq Functions to Array, Map, etc
initializeLinq();

async function demonstrateLinq() {
  console.log('--- Using Wrapper (from) ---');
  const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
  const evenNumbersWrapper = from(numbers)
    .where((x) => x % 2 === 0)
    .select((x) => x * 2)
    .toArray();
  console.log('Even numbers doubled (wrapper):', evenNumbersWrapper); // Expected: [4, 8, 12, 16, 20]

  console.log('\n--- Using Extended Native Types ---');
  const oddNumbersNative = numbers.where((x) => x % 2 !== 0).toArray();
  console.log('Odd numbers (native extension):', oddNumbersNative); // Expected: [1, 3, 5, 7, 9]

  console.log('\n--- Async Operations ---');
  const asyncData = [10, 20, 30];
  const processedAsyncData = await from(asyncData)
    .selectAsync(async (x) => {
      await new Promise(res => setTimeout(res, 50)); // Simulate async delay
      return x + 1;
    })
    .toArray();
  console.log('Processed async data:', processedAsyncData); // Expected: [11, 21, 31]
}

demonstrateLinq();