Documentationcurrent version
Help us improve the docs by fixing typos and proposing enhancements.

Nikita

Action "fs.base.stat"

Retrieve file information.

File information

The mode parameter indicates the file type. For conveniency, the @nikitajs/core/lib/utils/stats module provide functions to check each possible file types.

Example

Check if target is a file:

utils = require('@nikitajs/core/lib/utils')
const {stats} = await nikita
.file.touch("/tmp/a_file")
.fs.base.stat("/tmp/a_file")
assert(utils.stats.isFile(stats.mode) === true)

Check if target is a directory:

utils = require('@nikitajs/core/lib/utils')
const {stats} = await nikita
.fs.base.mkdir("/tmp/a_file")
.fs.base.stat("/tmp/a_file")
assert(utils.stats.isDirectory(stats.mode) === true)

Note

The stat command return an empty stdout in some circounstances like uploading a large file with file.download, thus the activation of retry and sleep confguration properties.

Schema definitions

The parameters include a subset as the one of the Node.js native fs.Stats object.

TODO: we shall be able to reference this as a $ref once schema does apply to returned values.

definitions_output =
  type: 'object'
  properties:
    'stats':
      type: 'object'
      properties:
        'mode':
          $ref: 'module://@nikitajs/core/src/actions/fs/base/chmod#/definitions/config/properties/mode'
        'uid':
          type: 'integer'
          description: '''
          The numeric user identifier of the user that owns the file
          (POSIX).
          '''
        'gid':
          type: 'integer'
          description: '''
          The numeric group identifier of the group that owns the file
          (POSIX).
          '''
        'size':
          type: 'integer'
          description: '''
          The size of the file in bytes.
          '''
        'atime':
          type: 'integer'
          description: '''
          The timestamp indicating the last time this file was accessed
          expressed in milliseconds since the POSIX Epoch.
          '''
        'mtime':
          type: 'integer'
          description: '''
          The timestamp indicating the last time this file was modified
          expressed in milliseconds since the POSIX Epoch.
          '''

definitions =
  config:
    type: 'object'
    properties:
      'dereference':
        type: 'boolean'
        description: '''
        Follow links, similar to `lstat`, default is "true", just like in the
        native Node.js `fs.stat` function, use `nikita.fs.lstat` to retrive
        link information.
        '''
      'target':
        oneOf: [{type: 'string'}, {instanceof: 'Buffer'}]
        description: '''
        Location of the file to analyse
        '''
    required: ['target']

Handler

handler = ({config}) ->
  # Normalize configuration
  config.dereference ?= true
  dereference = if config.dereference then '-L' else ''
  try
    {stdout} = await @execute
      command: """
      [ ! -e #{config.target} ] && exit 3
      if [ -d /private ]; then
        stat #{dereference} -f '%Xp|%u|%g|%z|%a|%m' #{escapeshellarg config.target} # MacOS
      else
        stat #{dereference} -c '%f|%u|%g|%s|%X|%Y' #{escapeshellarg config.target} # Linux
      fi
      """
      trim: true
    [rawmodehex, uid, gid, size, atime, mtime] = stdout.split '|'
    stats:
      mode: parseInt rawmodehex, 16 # dont know why `rawmodehex` was prefixed by `"0xa1ed"`
      uid: parseInt uid, 10
      gid: parseInt gid, 10
      size: parseInt size, 10
      atime: parseInt atime, 10
      mtime: parseInt mtime, 10
  catch err
    err = errors.NIKITA_FS_STAT_TARGET_ENOENT config:config, err: err if err.exit_code is 3
    throw err

Exports

module.exports =
  handler: handler
  metadata:
    argument_to_config: 'target'
    log: false
    raw_output: true
    definitions: definitions
  definitions_output: definitions_output

Errors

errors =
  NIKITA_FS_STAT_TARGET_ENOENT: ({config, err}) ->
    utils.error 'NIKITA_FS_STAT_TARGET_ENOENT', [
      'failed to stat the target, no file exists for target,'
      "got #{JSON.stringify config.target}"
    ],
      exit_code: err.exit_code
      errno: -2
      syscall: 'rmdir'
      path: config.target

Dependencies

utils = require '../../../utils'
{escapeshellarg} = utils.string

Stat implementation

On Linux, the format argument is '-c'. The following codes are used:

  • %f The raw mode in hexadecimal.
  • %u The user ID of owner.
  • %g The group ID of owner.
  • %s The block size of file.
  • %X The time of last access, seconds since Epoch.
  • %y The time of last modification, human-readable.

On MacOS, the format argument is '-f'. The following codes are used:

  • %Xp File type and permissions in hexadecimal.
  • %u The user ID of owner.
  • %g The group ID of owner.
  • %z The size of file in bytes.
  • %a The time file was last accessed.
  • %m The time file was last modified.
Edit on GitHub
Navigate
About

Nikita is an open source project hosted on GitHub and developed by Adaltas.