ln.js

Makes hard or symbolic links (symlinks) between files or directories like the ln command.

There are multi-platform file-system commands compatible with ln from UN*X implemented for Node.js in JavaScript, like symlink-dir or ln-cli, but they have different interface and different behaviour than the ln command. Instead of reusing the knowledge of the ln command, you would have to learn their new interface. This project aims to provide the well-known interface of the ln command.

This package offers only command-line interface, because programmatic interface is provided by link and symlink from node:fs. See also other commands compatible with their counterparts from UN*X - cat.js, cp.js, mkdir.js, mv.js and rm.js.

Synopsis

The following scripts from package.json won't work on Windows:

rm -rf dist
mkdir -p dist
cat src/umd-prolog.txt src/code.js src/umd-epilog.txt > dist/index.umd.js
cp src/index.d.ts dist
mv LICENSE doc
ln -s ../src src

Replace them with the following ones, which run on any operating system which is supported by Node.js:

rm-j -rf dist
mkdir-j -p dist
cat-j src/umd-prolog.txt src/code.js src/umd-epilog.txt > dist/index.umd.js
cp-j src/index.d.ts dist
mv-j LICENSE doc
ln-j -s ../src src

Notice that the only difference is the suffix -j behind the command names.

Installation

This module can be installed in your project using NPM, PNPM or Yarn. Make sure, that you use Node.js version 16.15 or newer.

$ npm i -D @unixcompat/ln.js
$ pnpm i -D @unixcompat/ln.js
$ yarn add -D @unixcompat/ln.js

Command-line Interface

See also man ln for the original POSIX documentation or for the extended Linux implementation.

Usage: ln-j [-fjLnsv] [--] src... dest

Options:
  -c|--cwd <dir>              directory to start looking for the source files
  -D|--dry-run                only print paths of source files or directories
  -f|--force                  remove existing destination files
  -j|--junctions              use junctions on Windows (otherwise ignored)
  -L|--logical                dereference srcs that are symbolic links
  -n|--no-dereference         treat dests as a normal files if it is
                                a symbolic link to a directory
  -P|--physical              make hard links directly to symbolic links
  -s|--symbolic               make symbolic links instead of hard links
  -v|--verbose                print path of each copied file or directory
  -V|--version                print version number
  -h|--help                   print usage instructions

Examples:
  $ ln-j src/prog.js dist/prog.js
  $ ln-j -j jones smith /home/nick/clients

Differences

The following options are specific to this command:

-D|--dry-run    only print path of each file or directory
-c|--cwd <dir>  directory to start looking for the source files
-j|--junctions  use junctions on Windows (otherwise ignored)

Also, the arguments may be BASH patterns. The pattern matching will ignore symbolic links. The argument -c|--cwd will be used only as a base directory to expand the BASH patterns in.

The following options from the Linux version are not supported:

--backup[=CONTROL]
       make a backup of each existing destination file
-b     like --backup but does not accept an argument
-d, -F, --directory
       allow the superuser to attempt to hard link directories
       (note: will probably fail due to system restrictions, even
       for the superuser)
-i, --interactive
       prompt whether to remove destinations
-P, --physical
       make hard links directly to symbolic links

-r, --relative
       with -s, create links relative to link location

-s, --symbolic
       make symbolic links instead of hard links

-S, --suffix=SUFFIX
       override the usual backup suffix

-t, --target-directory=DIRECTORY
       specify the DIRECTORY in which to create the links

-T, --no-target-directory
       treat LINK_NAME as a normal file always

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using npm test.

License

Copyright (c) 2023 Ferdinand Prantl

Licensed under the MIT license.