Merge pull request #198 from webdeveric/dev

Added `additionalProperties` support to `shape()`

Author: webdeveric

bench/hasAdditionalProperties.bench.ts

@@ -0,0 +1,23 @@
+import { bench } from 'vitest';
+
+import { hasAdditionalProperties } from '../src/hasAdditionalProperties.js';
+
+const input = {
+  name: 'Test',
+  age: 100_000,
+  job: {
+    title: 'Tester',
+  },
+};
+
+const input2 = {
+  ...input,
+  extra: true,
+};
+
+const knownProperties = ['name', 'age', 'job'];
+
+bench('hasAdditionalProperties()', () => {
+  hasAdditionalProperties(input, knownProperties);
+  hasAdditionalProperties(input2, knownProperties);
+});

src/hasAdditionalProperties.ts

@@ -0,0 +1,8 @@
+/**
+ * Determine if the `input` object has properties other than the provided `knownProperties`.
+ */
+export const hasAdditionalProperties = (input: object, knownProperties: PropertyKey[]): boolean => {
+  const properties = Array.isArray(input) ? [...knownProperties.map(String), 'length'] : knownProperties;
+
+  return !Reflect.ownKeys(input).every((key) => properties.includes(key));
+};

src/index.ts

@@ -35,6 +35,7 @@ export * from './getPackageName.js';
 export * from './getPaths.js';
 export * from './getRandomItem.js';
 export * from './getType.js';
+export * from './hasAdditionalProperties.js';
 export * from './inRange.js';
 export * from './isEmpty.js';
 export * from './iterateForever.js';

src/predicate/assume.ts

@@ -0,0 +1,10 @@
+/**
+ * This function is used to create a type guard that always returns true, effectively allowing
+ * the input to be treated as the specified type without any runtime checks.
+ *
+ * @privateRemarks
+ * The `is` prefix is omitted because there is not any conditional logic in the function.
+ * It is more of a command to `tsc` to assume the type rather than a check.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+export const assume = <Type>(_input: unknown, ..._args: any[]): _input is Type => true;

src/predicate/factory/is.ts

@@ -1,7 +1,9 @@
 import type { TypePredicateFn } from '../../types/functions.js';
-import type { Pretty, Writable } from '../../types/utils.js';
 
+/**
+ * Use `Object.is()` to compare `input` against allowed values.
+ */
 export const is =
-  <const T extends unknown[]>(...options: T): TypePredicateFn<Pretty<Writable<T[number]>>> =>
+  <const T extends unknown[]>(...values: T): TypePredicateFn<T[number]> =>
   (input: unknown): input is T[number] =>
-    options.some((option) => Object.is(input, option));
+    values.some((value) => Object.is(input, value));

src/predicate/factory/shape.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/ban-types */
+import { hasAdditionalProperties } from '../../hasAdditionalProperties.js';
 import { isAnyObject } from '../isAnyObject.js';
 
 import { literal } from './literal.js';
@@ -40,24 +41,26 @@ export type InferTypeFromShape<Shape extends ObjectShapeRecord<object>> = {
 
 export const shape = <Type extends object, Shape extends ObjectShapeRecord<Type> = ObjectShapeRecord<Type>>(
   objectShape: Shape,
+  additionalProperties = true,
 ): TypePredicateFn<Pretty<Type & InferTypeFromShape<Shape>>> => {
-  const entries: [key: string | symbol, predicate: TypePredicateFn<unknown>][] = Reflect.ownKeys(objectShape).map(
-    (key) => {
-      const value = Reflect.get(objectShape, key);
-
-      const predicate =
-        typeof value === 'function'
-          ? (value as TypePredicateFn<unknown>)
-          : value instanceof RegExp
-            ? matching(value)
-            : isAnyObject(value)
-              ? shape(value)
-              : literal(value);
-
-      return [key, predicate];
-    },
-  );
+  const knownProperties = Reflect.ownKeys(objectShape);
+  const entries: [key: string | symbol, predicate: TypePredicateFn<unknown>][] = knownProperties.map((key) => {
+    const value = Reflect.get(objectShape, key);
+
+    const predicate =
+      typeof value === 'function'
+        ? (value as TypePredicateFn<unknown>)
+        : value instanceof RegExp
+          ? matching(value)
+          : isAnyObject(value)
+            ? shape(value)
+            : literal(value);
+
+    return [key, predicate];
+  });
 
   return (input: unknown): input is Pretty<Type & InferTypeFromShape<Shape>> =>
-    isAnyObject(input) && entries.every(([key, predicate]) => predicate(Reflect.get(input, key)));
+    isAnyObject(input) &&
+    entries.every(([key, predicate]) => predicate(Reflect.get(input, key))) &&
+    (additionalProperties || !hasAdditionalProperties(input, knownProperties));
 };

src/predicate/index.ts

@@ -1,3 +1,4 @@
+export * from './assume.js';
 export * from './isAny.js';
 export * from './isAnyObject.js';
 export * from './isAnyObjectWith.js';

src/predicate/isAny.ts

@@ -1,2 +1,4 @@
+import { assume } from './assume.js';
+
 /* eslint-disable @typescript-eslint/no-explicit-any */
-export const isAny = (_input: unknown): _input is any => true;
+export const isAny = assume<any>;

src/predicate/isUnknown.ts

@@ -1 +1,3 @@
-export const isUnknown = (_input: unknown): _input is unknown => true;
+import { assume } from './assume.js';
+
+export const isUnknown = assume<unknown>;

test/hasAdditionalProperties.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { hasAdditionalProperties } from '../src/hasAdditionalProperties.js';
+
+describe('hasAdditionalProperties()', () => {
+  it('returns true when additional properties are detected', () => {
+    expect(hasAdditionalProperties({ a: 1, b: 2 }, ['a'])).toBeTruthy();
+  });
+
+  it('returns false when additional properties are not detected', () => {
+    expect(hasAdditionalProperties({ a: 1, [Symbol.for('b')]: 2 }, ['a', Symbol.for('b')])).toBeFalsy();
+  });
+
+  it('automatically allows `length` when the input is an array', () => {
+    expect(hasAdditionalProperties([0, 1], [0])).toBeTruthy();
+    expect(hasAdditionalProperties([0, 1], [0, 'length'])).toBeTruthy();
+
+    expect(hasAdditionalProperties([0, 1], [0, 1])).toBeFalsy();
+    expect(hasAdditionalProperties([0, 1], [0, 1, 'length'])).toBeFalsy();
+  });
+});