Document as const recommendation

Closes #83

Author: sindresorhus

index.d.ts

@@ -94,9 +94,9 @@ export type Options = {
 	/**
 	Exclude keys from being camel-cased.
 
-	If this option can be statically determined, it's recommended to add `as const` to it.
-
 	@default []
+
+	For correct TypeScript types when using this option with a string array, add `as const` to the array.
 	*/
 	readonly exclude?: ReadonlyArray<string | RegExp>;
 
@@ -164,10 +164,10 @@ export type Options = {
 	/**
 	Exclude children at the given object paths in dot-notation from being camel-cased. For example, with an object like `{a: {b: '🦄'}}`, the object path to reach the unicorn is `'a.b'`.
 
-	If this option can be statically determined, it's recommended to add `as const` to it.
-
 	@default []
 
+	For correct TypeScript types when using this option, add `as const` to the array.
+
 	@example
 	```
 	import camelcaseKeys from 'camelcase-keys';

index.test-d.ts

@@ -442,3 +442,92 @@ expectType<Array<{'4.2': string}>>(camelcaseKeys([{'4.2': 'foo'}]));
 
 // Non-numeric keys starting with numbers should still be transformed
 expectType<{'42Foo': string}>(camelcaseKeys({'42-foo': 'value'}));
+
+// Test for issue #83 - exclude without `as const`
+type Language = {
+	iso_639_1: string;
+	name: string;
+};
+
+type Image = {
+	aspect_ratio: number;
+	file_path: string;
+	height: number;
+	iso_639_1: string | undefined;
+	vote_average: number;
+	vote_count: number;
+	width: number;
+};
+
+type MovieDetails = {
+	id: number;
+	spoken_languages: Language[];
+	images: Image[];
+};
+
+const movieData: MovieDetails = {
+	id: 1,
+	spoken_languages: [
+		{iso_639_1: 'en', name: 'English'},
+	],
+	images: [
+		{
+			aspect_ratio: 1.5,
+			file_path: '/path.jpg',
+			height: 100,
+			iso_639_1: 'en',
+			vote_average: 5,
+			vote_count: 10,
+			width: 150,
+		},
+	],
+};
+
+// WITHOUT `as const` - the problematic case
+const result1 = camelcaseKeys(movieData, {
+	exclude: ['iso_639_1', 'iso_3166_1'],
+	deep: true,
+});
+
+// Since exclude is string[], TypeScript can't properly exclude specific keys
+// It will convert everything to camelCase
+expectType<{
+	id: number;
+	spokenLanguages: Array<{
+		iso6391: string; // Bug: should be iso_639_1 but TypeScript doesn't know
+		name: string;
+	}>;
+	images: Array<{
+		aspectRatio: number;
+		filePath: string;
+		height: number;
+		iso6391: string | undefined; // Bug: should be iso_639_1 but TypeScript doesn't know
+		voteAverage: number;
+		voteCount: number;
+		width: number;
+	}>;
+}>(result1);
+
+// WITH `as const` - this works correctly
+const result2 = camelcaseKeys(movieData, {
+	exclude: ['iso_639_1', 'iso_3166_1'] as const,
+	deep: true,
+});
+
+// With as const, TypeScript knows the exact strings in the exclude array
+expectType<{
+	id: number;
+	spokenLanguages: Array<{
+		iso_639_1: string; // Correctly preserved
+		name: string;
+	}>;
+	images: Array<{
+		aspectRatio: number;
+		filePath: string;
+		height: number;
+		iso_639_1: string | undefined; // Correctly preserved
+		voteAverage: number;
+		voteCount: number;
+		width: number;
+	}>;
+}>(result2);

package.json

@@ -64,5 +64,10 @@
 		"matcha": "^0.7.0",
 		"tsd": "^0.33.0",
 		"xo": "^1.2.2"
+	},
+	"xo": {
+		"rules": {
+			"@typescript-eslint/unified-signatures": "off"
+		}
 	}
 }

readme.md

@@ -54,6 +54,8 @@ Default: `[]`
 
 Exclude keys from being camel-cased.
 
+For correct TypeScript types when using this option with a string array, add `as const` to the array.
+
 ##### deep
 
 Type: `boolean`\
@@ -119,6 +121,8 @@ Default: `[]`
 
 Exclude children at the given object paths in dot-notation from being camel-cased.
 
+For correct TypeScript types when using this option, add `as const` to the array.
+
 For example, with an object like `{a: {b: '🦄'}}`, the object path to reach the unicorn is `'a.b'`.
 
 ```js