initial commit

[squeep-log-helper] / README.md

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..fdb6c26
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# @squeep/log-helper
+
+Utilities for standardized logging.
+
+## API
+
+- `fileScope(filepath, options)`
+  Returns a function which will decorate function names with some combination of the source file path, package name, and package version.  If the filepath is `index.js`, it will be replaced by its containing directory.  Defaults for what is included are determined by Squeep opinions on package layouts.
+
+  Example:
+
+  ```javascript
+  // Assuming this file is located at 'project/lib/subdir/code.js'
+  // Assuming project/package.json defines 'name' as 'project'
+  const { fileScope } = require('@squeep/log-helper');
+  const _fileScope = fileScope(__filename, { includeVersion: false });
+
+  function example() {
+    const _scope = _fileScope('example');
+    console.log(_scope); // Will show 'project:subdir/code:example'
+  }
+   ```
+
+  Options:
+  - `includePackage` Package name from `package.json`.
+  - `includeVersion` Package version from `package.json`.  If this is `true`, `includePackage` will also become `true`.
+  - `includePath` The path to the file, relative to the `package.json` file.
+  - `leftTrim` How much of the beginning of the path to elide. (e.g. 3 would render `foo/bar` as `/bar`)
+  - `delimiter` Placed between fields, defaults to `:`.
+  - `prefix` A field included before the package name.
+
+  Defaults, based on directory existing in project:
+  |                | `src` | `lib` | other |
+  |----------------|-------|-------|-------|
+  | includePackage | false | true  | false |
+  | includeVersion | false | true  | false |
+  | includePath    | true  | true  | false |
+  | leftTrim       | 4     | 4     | 0     |
+
+  If any errors are encountered while trying to determine the path or package metadata, the scope will be prefixed with a '?'.