Rename default export to named export includeKeys() and add excludeKeys() (#18)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: Richienb

benchmark.js

@@ -1,4 +1,4 @@
-import filterObj from 'filter-obj';
+import {includeKeys} from 'filter-obj';
 
 // Benchmark `filter-obj`.
 // Higher `loopCount` give more precise results but last longer.
@@ -10,7 +10,7 @@ const benchmark = function (loopCount, objectSize, predicateSize) {
 
 	console.time();
 	for (let index = 0; index < loopCount; index += 1) {
-		filterObj(bigObject, predicate);
+		includeKeys(bigObject, predicate);
 	}
 
 	console.timeEnd();

index.d.ts

@@ -3,35 +3,73 @@ Filter object keys and values into a new object.
 
 @param object - The source object to filter properties from.
 @param predicate - Predicate function that detemines whether a property should be assigned to the new object.
-@param includeKeys - Property names that should be assigned to the new object.
+@param keys - Property names that should be assigned to the new object.
 
 @example
 ```
-import filterObject from 'filter-obj';
+import {includeKeys} from 'filter-obj';
 
 const object = {
 	foo: true,
 	bar: false
 };
 
-const newObject = filterObject(object, (key, value) => value === true);
+const newObject = includeKeys(object, (key, value) => value === true);
 //=> {foo: true}
 
-const newObject2 = filterObject(object, ['bar']);
+const newObject2 = includeKeys(object, ['bar']);
 //=> {bar: false}
 ```
 */
-export default function filterObject<ObjectType extends Record<string, any>>(
+export function includeKeys<ObjectType extends Record<string, any>>(
 	object: ObjectType,
 	predicate: (
 		key: keyof ObjectType,
 		value: ObjectType[keyof ObjectType]
 	) => boolean
 ): Partial<ObjectType>;
-export default function filterObject<
+export function includeKeys<
 	ObjectType extends Record<string, any>,
 	IncludedKeys extends keyof ObjectType,
 >(
 	object: ObjectType,
-	includeKeys: readonly IncludedKeys[]
+	keys: readonly IncludedKeys[]
 ): Pick<ObjectType, IncludedKeys>;
+
+/**
+Filter object keys and values into a new object.
+
+@param object - The source object to filter properties from.
+@param predicate - Predicate function that determines whether a property should not be assigned to the new object.
+@param keys - Property names that should not be assigned to the new object.
+
+@example
+```
+import {excludeKeys} from 'filter-obj';
+
+const object = {
+	foo: true,
+	bar: false
+};
+
+const newObject = excludeKeys(object, (key, value) => value === true);
+//=> {bar: false}
+
+const newObject3 = excludeKeys(object, ['bar']);
+//=> {foo: true}
+```
+*/
+export function excludeKeys<ObjectType extends Record<string, any>>(
+	object: ObjectType,
+	predicate: (
+		key: keyof ObjectType,
+		value: ObjectType[keyof ObjectType]
+	) => boolean
+): Partial<ObjectType>;
+export function excludeKeys<
+	ObjectType extends Record<string, any>,
+	ExcludedKeys extends keyof ObjectType,
+>(
+	object: ObjectType,
+	keys: readonly ExcludedKeys[]
+): Omit<ObjectType, ExcludedKeys>;

index.js

@@ -1,4 +1,4 @@
-export default function filterObject(object, predicate) {
+export function includeKeys(object, predicate) {
 	const result = {};
 
 	if (Array.isArray(predicate)) {
@@ -31,3 +31,12 @@ export default function filterObject(object, predicate) {
 
 	return result;
 }
+
+export function excludeKeys(object, predicate) {
+	if (Array.isArray(predicate)) {
+		const set = new Set(predicate);
+		return includeKeys(object, key => !set.has(key));
+	}
+
+	return includeKeys(object, (key, value, object) => !predicate(key, value, object));
+}

index.test-d.ts

@@ -1,22 +1,37 @@
 import {expectType, expectError} from 'tsd';
-import filterObject from './index.js';
+import {includeKeys, excludeKeys} from './index.js';
 
 const object = {
 	foo: 'foo',
 	bar: 1,
 };
 
 expectType<Partial<typeof object>>(
-	filterObject(object, (key, value) => {
+	includeKeys(object, (key, value) => {
 		expectType<'foo' | 'bar'>(key);
 		expectType<string | number>(value);
 
 		return false;
 	}),
 );
 expectError<typeof object>(
-	filterObject(object, () => false),
+	includeKeys(object, () => false),
 );
-expectType<{foo: string}>(filterObject(object, ['foo']));
-expectError<typeof object>(filterObject(object, ['foo']));
-expectError(filterObject(object, ['baz']));
+expectType<{foo: string}>(includeKeys(object, ['foo']));
+expectError<typeof object>(includeKeys(object, ['foo']));
+expectError(includeKeys(object, ['baz']));
+
+expectType<Partial<typeof object>>(
+	excludeKeys(object, (key, value) => {
+		expectType<'foo' | 'bar'>(key);
+		expectType<string | number>(value);
+
+		return false;
+	}),
+);
+expectError<typeof object>(
+	excludeKeys(object, () => false),
+);
+expectType<{bar: number}>(excludeKeys(object, ['foo']));
+expectError<typeof object>(excludeKeys(object, ['foo']));
+expectError(excludeKeys(object, ['baz']));

readme.md

@@ -11,26 +11,34 @@ npm install filter-obj
 ## Usage
 
 ```js
-import filterObject from 'filter-obj';
+import {includeKeys, excludeKeys} from 'filter-obj';
 
 const object = {
 	foo: true,
 	bar: false
 };
 
-const newObject = filterObject(object, (key, value) => value === true);
+const newObject = includeKeys(object, (key, value) => value === true);
 //=> {foo: true}
 
-const newObject2 = filterObject(object, ['bar']);
+const newObject2 = includeKeys(object, ['bar']);
 //=> {bar: false}
+
+const newObject = excludeKeys(object, (key, value) => value === true);
+//=> {bar: false}
+
+const newObject3 = excludeKeys(object, ['bar']);
+//=> {foo: true}
 ```
 
 ## API
 
 Symbol keys are not copied over to the new object.
 
-### filterObject(source, filter)
-### filterObject(source, includeKeys)
+### includeKeys(source, filter)
+### includeKeys(source, keys)
+### excludeKeys(source, filter)
+### excludeKeys(source, keys)
 
 #### source
 
@@ -42,13 +50,13 @@ The source object to filter properties from.
 
 Type: `(sourceKey, sourceValue, source) => boolean`
 
-A predicate function that detemines whether a property should be assigned to the new object.
+A predicate function that detemines whether a property should be filtered.
 
-#### includeKeys
+#### keys
 
 Type: `string[]`
 
-An array of property names that should be assigned to the new object.
+An array of property names to be filtered.
 
 ## Related
 

test.js

@@ -1,48 +1,94 @@
 import test from 'ava';
-import filterObject from './index.js';
+import {includeKeys, excludeKeys} from './index.js';
 
-test('function predicate returns a boolean', t => {
-	t.is(Object.keys(filterObject({foo: true, bar: false}, () => true)).length, 2);
-	t.is(Object.keys(filterObject({foo: true, bar: false}, () => false)).length, 0);
+test('includeKeys: function predicate returns a boolean', t => {
+	t.is(Object.keys(includeKeys({foo: true, bar: false}, () => true)).length, 2);
+	t.is(Object.keys(includeKeys({foo: true, bar: false}, () => false)).length, 0);
 });
 
-test('function predicate passes the key as argument', t => {
-	t.true(filterObject({foo: true}, key => key === 'foo').foo);
+test('includeKeys: function predicate passes the key as argument', t => {
+	t.true(includeKeys({foo: true}, key => key === 'foo').foo);
 });
 
-test('function predicate passes the value as argument', t => {
-	t.is(filterObject({foo: 'test'}, (key, value) => value === 'test').foo, 'test');
+test('includeKeys: function predicate passes the value as argument', t => {
+	t.is(includeKeys({foo: 'test'}, (key, value) => value === 'test').foo, 'test');
 });
 
-test('function predicate passes the object as argument', t => {
-	t.true(filterObject({foo: true}, (key, value, object) => object.foo).foo);
+test('includeKeys: function predicate passes the object as argument', t => {
+	t.true(includeKeys({foo: true}, (key, value, object) => object.foo).foo);
 });
 
-test('array predicate', t => {
-	t.deepEqual(Object.keys(filterObject({foo: true, bar: false}, ['foo'])), ['foo']);
+test('includeKeys: array predicate', t => {
+	t.deepEqual(Object.keys(includeKeys({foo: true, bar: false}, ['foo'])), ['foo']);
 });
 
-test('symbol properties are omitted', t => {
+test('includeKeys: symbol properties are omitted', t => {
 	const symbol = Symbol('test');
 	const input = {[symbol]: true};
-	t.is(filterObject(input, () => true)[symbol], undefined);
+	t.is(includeKeys(input, () => true)[symbol], undefined);
 });
 
-test('non-enumerable properties are omitted', t => {
+test('includeKeys: non-enumerable properties are omitted', t => {
 	const input = Object.defineProperty({}, 'test', {value: true, enumerable: false});
-	t.is(filterObject(input, () => true).test, undefined);
+	t.is(includeKeys(input, () => true).test, undefined);
 });
 
-test('inherited properties are omitted', t => {
+test('includeKeys: inherited properties are omitted', t => {
 	const Parent = class {
 		test() {}
 	};
 	const Child = class extends Parent {};
 	const input = new Child();
-	t.is(filterObject(input, () => true).test, undefined);
+	t.is(includeKeys(input, () => true).test, undefined);
 });
 
-test('__proto__ keys', t => {
+test('includeKeys: __proto__ keys', t => {
 	const input = {__proto__: {foo: true}};
-	t.deepEqual(filterObject(input, () => true), input);
+	t.deepEqual(includeKeys(input, () => true), input);
+});
+
+test('excludeKeys: function predicate returns a boolean', t => {
+	t.is(Object.keys(excludeKeys({foo: true, bar: false}, () => true)).length, 0);
+	t.is(Object.keys(excludeKeys({foo: true, bar: false}, () => false)).length, 2);
+});
+
+test('excludeKeys: function predicate passes the key as argument', t => {
+	t.true(excludeKeys({foo: true}, key => key !== 'foo').foo);
+});
+
+test('excludeKeys: function predicate passes the value as argument', t => {
+	t.is(excludeKeys({foo: 'test'}, (key, value) => value !== 'test').foo, 'test');
+});
+
+test('excludeKeys: function predicate passes the object as argument', t => {
+	t.true(excludeKeys({foo: true}, (key, value, object) => !object.foo).foo);
+});
+
+test('excludeKeys: array predicate', t => {
+	t.deepEqual(Object.keys(excludeKeys({foo: true, bar: false}, ['bar'])), ['foo']);
+});
+
+test('excludeKeys: symbol properties are omitted', t => {
+	const symbol = Symbol('test');
+	const input = {[symbol]: true};
+	t.is(excludeKeys(input, () => false)[symbol], undefined);
+});
+
+test('excludeKeys: non-enumerable properties are omitted', t => {
+	const input = Object.defineProperty({}, 'test', {value: true, enumerable: false});
+	t.is(excludeKeys(input, () => false).test, undefined);
+});
+
+test('excludeKeys: inherited properties are omitted', t => {
+	const Parent = class {
+		test() {}
+	};
+	const Child = class extends Parent {};
+	const input = new Child();
+	t.is(excludeKeys(input, () => false).test, undefined);
+});
+
+test('excludeKeys: __proto__ keys', t => {
+	const input = {__proto__: {foo: true}};
+	t.deepEqual(excludeKeys(input, () => false), input);
 });