Object Property Omission Utility

Common errors

• TypeError: omit is not a function

  cause Attempting to use `import { omit } from 'omit.js'` in an ES Module context, or `const omit = require('omit.js').omit;` in a CommonJS context. The library exports its main function as a default export for ESM.
  fix For ES Modules, use `import omit from 'omit.js';`. For CommonJS, use `const omit = require('omit.js');`.

• Property 'someNestedProp' of 'object' is undefined after omit operation.

  cause `omit.js` only operates on top-level properties. If you omit a parent property, all its nested contents will also be removed. If you intended to omit a nested property, `omit.js` is not the right tool for that directly.
  fix To omit nested properties, you need to either restructure your object before calling `omit.js` (e.g., flatten it) or use a different utility designed for deep property manipulation. For example, `omit(myObject, ['parent.nestedProp'])` will not work; `omit(myObject, ['parent'])` would remove `parent` entirely.

• Type 'Omit<MyType, 'field'>' is not assignable to type 'MyType'.

  cause This error typically occurs in TypeScript when you're attempting to assign a type that has properties omitted by the `omit.js` function (or `Omit` utility type) back to a type that expects those properties to exist.
  fix Ensure that the type of the variable receiving the result of `omit.js` (or `Omit<Type, Keys>`) correctly reflects the properties that have been removed. You might need to define a new type with `Omit<OriginalType, 'field1' | 'field2'>` or `Partial<OriginalType>`.

Warnings

• breaking Version 2.0.0 involved significant changes to the build system (switching from `rc-tools` to `father`) and internal dependencies. While the primary API `omit(obj, fields)` remained consistent, these internal changes could lead to breaking changes in module resolution, bundling behavior, or dependency conflicts for some consumers depending on their specific build setups.
  Fix: Review your module resolution settings, especially if you encountered issues upgrading from `1.x.x` to `2.x.x`. Ensure your bundler (Webpack, Rollup, etc.) or Node.js environment is configured to correctly resolve ES Modules if you are using `import` syntax.
• gotcha The `omit.js` function performs a shallow copy of the object. This means that while the top-level properties are new references (or omitted), any nested objects or arrays are copied by reference, not by value. Mutating a nested object in the original will also affect the corresponding nested object in the shallow-copied result (unless that nested object was itself omitted).
  Fix: If you require a deep copy, you must implement your own deep cloning logic (e.g., using `structuredClone` in modern environments, or a dedicated deep-cloning library like `lodash.clonedeep`) before or after using `omit.js`.
• deprecated The functionality provided by `omit.js` can often be achieved with native JavaScript features like object destructuring with rest/spread syntax (`{ id, ...rest } = obj;`). For TypeScript, the built-in `Omit<Type, Keys>` utility type provides compile-time type manipulation for excluding properties, making external libraries for this specific task less necessary in many modern projects.
  Fix: Consider refactoring to use native JavaScript for runtime omission (`const { excludedProp, ...rest } = myObject;`) and TypeScript's `Omit` utility type (`type NewType = Omit<OriginalType, 'prop1' | 'prop2'>;`) for compile-time type transformation. This can reduce dependency count and leverage language features.
• gotcha The package has seen very limited maintenance since its last release (v2.0.2) in 2018. While its core functionality is simple and stable, users should be aware that it may not receive updates for new JavaScript features, bug fixes, or security patches, which could be a concern for long-term projects or those requiring active support.
  Fix: Evaluate if the benefits of a lightweight utility outweigh the risks of a minimally maintained package. For critical applications, consider using actively maintained alternatives or implementing the omission logic natively.

Install

• npm install omit.js npm
• yarn add omit.js yarn
• pnpm add omit.js pnpm

Imports

• omit
  wrong:

  import { omit } from 'omit.js'; // `omit.js` uses a default export for ESM
  const omit = require('omit.js').omit;

  correct:

  import omit from 'omit.js';

  For ESM, `omit.js` provides a default export. Ensure your build configuration supports importing from `.js` files without explicit extensions if not using a bundler.
• omit
  wrong:

  import omit from 'omit.js'; // CommonJS environments do not support ES Modules `import` syntax

  correct:

  const omit = require('omit.js');

  This is the standard CommonJS `require` syntax as demonstrated in the package's README.
• OmitFunction
  wrong:

  import { Omit } from 'omit.js'; // Omit is a built-in TypeScript utility type; avoid name collision.

  correct:

  import type { OmitFunction } from 'omit.js';

  When using TypeScript, if you need to type the `omit` function itself, look for an exported function type (e.g., `OmitFunction` or similar) to avoid conflicts with TypeScript's intrinsic `Omit<Type, Keys>` utility type.

Quickstart

Demonstrates how to import and use `omit.js` to filter properties from an object, creating a shallow copy. It shows omitting multiple and single fields, and highlights the non-mutating behavior on the top-level object, while also noting the shallow copy aspect for nested objects.

import omit from 'omit.js';

const userData = {
  id: 'user-123',
  username: 'jsmith',
  email: 'jsmith@example.com',
  passwordHash: 'somehashedvalue',
  createdAt: new Date(),
  settings: { theme: 'dark', notifications: true }
};

// Use omit.js to create a new object without sensitive or unnecessary fields
const publicProfile = omit(userData, ['passwordHash', 'email', 'createdAt']);

console.log('Public Profile:', publicProfile);
// Expected: { id: 'user-123', username: 'jsmith', settings: { theme: 'dark', notifications: true } }

// The original object remains untouched
console.log('Original User Data:', userData);

const postData = {
  title: 'My First Post',
  content: 'Hello World!',
  authorId: 'user-123',
  tags: ['javascript', 'webdev']
};

// Omit a single field
const postWithoutAuthor = omit(postData, ['authorId']);
console.log('Post without Author:', postWithoutAuthor);

// Important: omit.js creates a shallow copy. Nested objects like 'settings'
// in 'publicProfile' are copied by reference. Changes to 'userData.settings'
// after calling omit will be reflected in 'publicProfile.settings'.