Add safeCastTo() #61

readme.md

@@ -24,6 +24,7 @@ import {isDefined} from 'ts-extras';
 **General**
 
 - [`asWritable`](source/as-writable.ts) - Cast the given value to be [`Writable`](https://github.com/sindresorhus/type-fest/blob/main/source/writable.d.ts).
+- [`safeCastTo`](source/safe-cast-to.ts) - Cast a value to the given type safely.
 
 **Type guard**
 

source/index.ts

@@ -1,3 +1,4 @@
+export {safeCastTo} from './safe-cast-to.js';
 export {arrayIncludes} from './array-includes.js';
 export {asWritable} from './as-writable.js';
 export {assertError} from './assert-error.js';

source/safe-cast-to.ts

@@ -0,0 +1,31 @@
+/**
+Cast a value to the given type safely.
+
+This is useful since the `as` keyword allows you to convert between two unrelated types, which is type-unsafe. For example, converting a number to a string type.
+
+However, this function only allows you to cast a given value to a type that is compatible with it, avoiding the potential risk of using "as" and not breaking the type safety of your code.
+
+@example
+```
+type Foo = {
+	a: string;
+	b?: number;
+};
+
+declare const possibleUndefined: Foo | undefined;
+
+const foo = possibleUndefined ?? safeCastTo<Partial<Foo>>({});
+console.log(foo.a ?? '', foo.b ?? 0);
+
+const bar = possibleUndefined ?? {};
+// @ts-expect-error
+console.log(bar.a ?? '', bar.b ?? 0);
+//             ^^^ Property 'a' does not exist on type '{}'.(2339)
+//                          ^^^ Property 'b' does not exist on type '{}'.(2339)
+```
+
+@category General
+*/
+export function safeCastTo<T>(value: T): T {
+	return value;
+}

test/safe-cast-to.ts

@@ -0,0 +1,38 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import test from 'ava';
+import {expectTypeOf} from 'expect-type';
+import {safeCastTo} from '../source/index.js';
+
+test('safeCastTo()', t => {
+	type Foo = {
+		a: string;
+		b?: number;
+	};
+
+	const EmptyObject = {};
+	const foo: Foo = {
+		a: '',
+		b: 0,
+	};
+
+	t.is(EmptyObject, safeCastTo(EmptyObject));
+	t.is(foo, safeCastTo(foo));
+
+	expectTypeOf({}).toEqualTypeOf<{}>();
+	expectTypeOf(safeCastTo({})).toEqualTypeOf<{}>();
+	expectTypeOf({}).not.toEqualTypeOf<Partial<Foo>>();
+	expectTypeOf(safeCastTo({})).not.toEqualTypeOf<Partial<Foo>>();
+	expectTypeOf(safeCastTo<Partial<Foo>>({})).toEqualTypeOf<Partial<Foo>>();
+	expectTypeOf(safeCastTo<Partial<Foo>>({}).a).toEqualTypeOf<string | undefined>();
+	expectTypeOf(safeCastTo<Partial<Foo>>({}).b).toEqualTypeOf<number | undefined>();
+
+	expectTypeOf(foo).toEqualTypeOf<Foo>();
+	expectTypeOf(safeCastTo(foo)).toEqualTypeOf<Foo>();
+	expectTypeOf(safeCastTo<Partial<Foo>>(foo)).not.toEqualTypeOf<Foo>();
+	expectTypeOf(safeCastTo<Partial<Foo>>(foo)).toEqualTypeOf<Partial<Foo>>();
+
+	// @ts-expect-error
+	safeCastTo<Foo>({});
+	// @ts-expect-error
+	safeCastTo<Required<Foo>>(foo);
+});