fix(types): make assign return type more accurate + add Assign type

[aleclarson]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

• Add the Assign type, which tries to be as accurate as possible.
• Add the BuiltInType utility type as a union type of all built-in types (including DOM-specific and NodeJS-specific types when possible).
• Add the OptionalKeys and RequiredKeys utility types.

CustomClassRegistry

Since there's no built-in way to differentiate a “plain object” type and a custom class instance type, I've added the CustomClassRegistry interface. Anyone can extend this in their project by using “declaration merging”:

class FooBar {
  foo: unknown
  bar: unknown
}

declare module 'radashi' {
  interface CustomClassRegistry {
    FooBar: FooBar
  }
}

Now the assign function's return type won't suggest that FooBar instances were merged with. Check out this before-and-after example:

// BEFORE
const result = assign(
  { a: new FooBar },
  { a: { foo: '' } }
)
// ^? result: { a: { foo: string; bar: unknown } }

// AFTER
const result = assign(
  { a: new FooBar },
  { a: { foo: '' } }
)
// ^? result: { a: { foo: string } }

BEWARE: Any class you add to CustomClassRegistry must not have identical properties as any other “plain object” types you ever plan to use, because as far as TypeScript is concerned, they are identical. This could lead to suboptimal result types.

Related issue, if any:

Resolves #141 (cc @crishoj)

For any code change,

• Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

Yes

Bundle impact

Status	File	Size	Difference (%)
M	src/object/assign.ts	373 1	+0 (+0%)

Footnotes

1. Function size includes the import dependencies of the function. ↩

[github-actions]

A new beta version 12.2.0-beta.6b76988 has been published to NPM. 🚀

To install:

pnpm add radashi@12.2.0-beta.6b76988

The radashi@beta tag also includes this PR.