doc: deprecate non-string type in fs.symlink()

[LiviaMedeiros]

Disallows any type except for 'dir', 'file', 'junction', or undefined in fs.symlink(), fs.symlinkSync(), and fsPromises.symlink()
The implementation would be unconditional validating with validateOneOf(type, 'type', ['dir', 'file', 'junction', undefined]), i.e. throwing an error instead of defaulting to autodetection (or instead of ignoring on non-windows platforms).

Refs: #42894 (comment)

Not sure if it's worth the potential breakage. On a long run, replacing it with an object parameter (for example, { type: 'file', force: true, relative: false }) to allow additional options might make more sense.

[aduh95]

Why not leave this validation at the FS level, or libuv? Doing it in Node.js seems weird to me, and potentially bad for forward compatibility.

[aduh95]

/cc @nodejs/fs

[LiviaMedeiros]

libuv receives flags (0, UV_FS_SYMLINK_DIR, UV_FS_SYMLINK_JUNCTION), the string parameter is Node.js-specific.
The current error (ERR_FS_INVALID_SYMLINK_TYPE) thrown for invalid strings is Node.js-specific as well.

[aduh95]

Oh so we don't need a deprecation, using an invalid string is already throwing.

[aduh95]

@LiviaMedeiros is #44641 (comment) correct or am I missing something?

[LiviaMedeiros]

If I remember correctly, it's true for invalid strings; but any parameter with typeof ... !== 'string' is interpreted as default ('file' for API, 0 for internals and libuv).
The deprecation was specifically for non-string arguments.

[aduh95]

The documentation already indicates it should be a string, I don't think we need a deprecation for that. It sounds like we can tighten up the check as a semver major directly, unless there's a massive ecosystem breakage of doing so.